Upgrade to a New Plone Version

How to upgrade your Plone installation to a newer version

You need to setup a virtualenv to run buildout in just incase there are dependency issues with the newer Plone version

sudo easy_install virtualenv

Then create the virtualenv:

virtualenv environment_name

More complex command (see virtualenv -h for information):

virtualenv -p python_version --no-site-packages environment_name

Where python_version would be something like python2.7

Activate the environment (cd to the environment locations bin folder:

/path/to/environment_name/bin/. activate

 Install setuptools in the newly activated environment:

sudo easy_install -U setuptools

The virtualenv is primarily used for obtaining an updated version of buildout, bootstrap creates the bin/ directory from where you issue commands such as starting instance/zeoserver, plonectl etc.

First rename the original bootstrap.py file in your instance directory.

mv bootstrap.py bootstrap.py.old

Then download the updated bootstrap.py file:

wget http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py

Delete the bin directory in the instance folder:

rm -rf bin/

Run the bootstrap.py file:

python bootstrap.py

You can now deactivate the virtualenv


Update your buildout to pull down the latest version of Plone:


extends =
#    versions.cfg

# If you change your Plone version, you'll also need to update
# the repository below.
find-links +=


extends =
#    versions.cfg

# If you change your Plone version, you'll also need to update
# the repository below.
find-links +=

Run buildout:


Updating Bootstrap

How to update the bootstrap.py file, (sometimes this is needed to upgrade Plone).

Replace bootstrap.py in the instance folder with:

wget http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py

Troubleshooting Tips

There are many things to do if you get errors. One of which would be to remove any eggs you see in the tracebacks when running buildout or trying to load Zope / Plone.

Sometimes you will receive errors about eggs that end in *-linux-x86_64.egg depending on the OS. You an remove these as you see the errors, although if you get more than two errors please see the next command.

One semi-drastic option is removing every .egg in the buildout-cache folder and re-running buildout

rm -rf buildout-cache/eggs/*py2.7-linux-x86_64.egg

Also note, kss was removed in Plone 4.3 so Quintagroup Plone comments, for example will not work.

Check other includes in buildout if you continue to get errors, check base.cfg which may be included and have references to eggs which are incompatible with the newer version of Plone (you should be able to see it in your buildout.cfg directory).


You may get the error below when upgrading, if you use the add-on: plone.z3cform:

zope.component 0.0 has no such extra feature 'zcml'

This is due to recent changes in the z3cform product.

If you get the error mentioned above, open your buildout.cfg file and completely remove the [fakezope2eggs] section, including its entry in the 'parts' section under the [buildout] heading.

Then add the following to the [zope2] section of the buildout.cfg file:

fake-zope-eggs = true
additional-fake-eggs = ZODB3
skip-fake-eggs =

Upgrading from Plone 3

You will need to install plone.app.blob via buildout to ensure blob storage is supported - make sure to install it on the Plone 3 version before the upgrade. Otherwise you will need to start again.

Further Thoughts

You will be able to find the official Plone upgrade documentation here. There is also some excellent trouble shooting buildout errors documentation located here.

Try a clear and rebuild of the catalog if you get strange 'language' errors, they seem to be caused by unindexed or orphaned items.

Also remember to recompile Python scripts (when doing the reindexing you'll see foreground mode mention it)


In certain circumstances it may simply be best to install a fresh updated version of Plone, install all the add-ons and upgrade them if necessary as the Plone 3 (or earlier) site, then move over the Data.fs and run through any errors one by one you see on the output in foreground mode. Certain emplates from Plone 3 don't work properly with Plone 4 (variables such as here_url for example, do not exist in the newer templates).