Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Linux/BSD/OSX Installer
Shell Python Other


Plone 5.0b2: Unified Installer

The Plone Unified Installer is a source-installation kit that installs Plone and its dependencies from source on most Unix-like platforms. The kit includes Plone and Zope and will download components like Python if needed. Python is installed in a way that will not change or interfere with your system Python.

This version includes Plone 5.0b2, Zope 2.13.x, and uses Python 2.7.x.

Feedback/bugs to Plone Development Workspace for component: Installer (Unified)

For a guide to installing and maintaining Plone, see Installing and maintaining Plone sites

If you are a deploying Plone for production on a new server, consider using our Ansible full-stack installer <>.

Important:Back up your existing Plone site prior to running the installer or running buildout to update.
Important:Debian/Ubuntu users. Read platform notes if you wish to install under /usr/local.

Outline of this document

Installation Instructions

The installer will compile Python, Zope, and key required libraries from source on an as-needed basis. (Basic build tools and common libraries are required. See Utility Dependencies and Libraries Required below.

PLEASE NOTE:You have the option to run the installation as root or a normal user. There are serious security implications to this choice.

The non-root method produces an install that will run the Zope server with the same privileges as the installing user. This is probably not an acceptable security profile for a production server, but is much easier for testing and development purposes or if you take care to set users and privileges yourself.

The 'root' method produces an install that runs the Zope server as a distinct user identity with minimal privileges (unless you add them). Providing adequate security for a production server requires many more steps, but this is a better starting point.

PLEASE NOTE:You have the option to install Plone as a standalone (single-instance) setup or as a clustered (ZEO) setup.

The clustered (ZEO) setup will take advantage of multi-core CPUs and is recommended for a production deployment, while the standalone method is easier for development or testing.

For a non-super-user (rootless) installation

If you run the installation while logged in as a normal (non-root) user, Python/Zope/Plone will be built at $HOME/Plone (the user's home directory, Plone subdirectory). You will need to start Zope using the user identity used for the build, and it will run with the privileges of that user.

To install Plone 5.0b2 in a stand-alone (single Zope instance) configuration:

  • cd to the installer directory and issue the following command:

    >> ./ standalone

To install Plone 5.0b2 in a ZEO Cluster (ZEO server, 2 clients) configuration:

  • cd to the installer directory and issue the following command:

    >> ./ zeo

For a super-user (root) installation

If you run the installation with root privileges, it will install Python/Zope/Plone to /opt/plone.

[Darwin (OS X) Note: Under Darwin, the default installation is to /Applications/Plone for the root install. Please replace /opt with /Applications in the instructions below.]

Two Plone users will be created: plone_daemon and plone_buildout. You will need to start Plone as plone_daemon and run buildout as plone_buildout. The install will also create a plone_group group that includes both plone users.

To install Plone 5.0b2 in a stand-alone (single Zope instance) configuration:

  • cd to the installer directory and issue the following command:

    >> sudo ./ standalone

    or on a sudo-less system:

    >> su; ./ standalone

To install Plone 5.0b2 in a ZEO Cluster (ZEO server, 2 clients) configuration:

  • cd to the installer directory and issue the following command:

    >> sudo ./ zeo

    or on a sudo-less system:

    >> su; ./ zeo

The "sudo" utility is required for a root install. This security utility is included with most recent Unix workalikes and is easily installed on other systems. On BSD-heritage systems, this in the security directory of the ports collection.

Installation Options

Usage:[sudo] [options] standalone|zeo

Install methods available:

standalone:install standalone zope instance
zeo:install zeo cluster

Use sudo (or run as root) for root install.



Use to specify top-level path for installs. Plone instances and Python will be built inside this directory. Default is /opt/plone for root install, $HOME/Plone for non-root.

PLEASE NOTE: Your pathname should not include spaces.

 Use to specify the name of the operating instance to be created. This will be created inside the target directory. Default is 'zinstance' for standalone, 'zeocluster' for ZEO.
 Use with the "zeo" install method to specify the number of Zope clients you wish to create. Default is 2.
 In a root install, sets the effective system user for running the instance. Default is 'plone_daemon'. Ignored for non-root installs.
 In a server-mode install, sets the overall system owner of the installation. Default is 'plone_buildout'. This is the user id that should be employed to run buildout or make src or product changes. Ignored for non-root installs.
 In a server-mode install, sets the effective system group for the daemon and buildout users. Default is 'plone_group'. Ignored for non-server-mode installs.
 If you have an already built Python that's adequate to run Zope / Plone, you may specify it here. virtualenv will be used to isolate the copy used for the install. The specified Python will need to have been built with support for libz and libjpeg and include the Python Imaging Library.
--build-python If you do not have a suitable Python available, the installer will build one for you if you set this option. Requires Internet access to download Python source.
 If not specified, a random password will be generated.
--without-ssl Optional. Allows the build to proceed without ssl dependency tests.
--static-lxml Forces a static build of lxml's libxml2 and libxslt dependencies. Requires Internet access to download components.

Note that you may run repeatedly for the same target so long as you either use a different installation method or specify different instance names. Installations to the same target will share the same Python and egg/download cache.

Upgrade From Plone 2.5 or Non-Buildout 3.x


Utility Dependencies

Most of these are included with system "build" kits.

  • gcc
  • g++ (gcc-c++)
  • GNU make
  • GNU tar
  • patch
  • gunzip and bunzip2
  • posix-compliant /bin/sh
  • curl or wget

Libraries Required

Install libraries prior to running installer. Development versions of some packages are required for headers. Debian/Ubuntu package names are included below. RPM equivalents follow in a separate subsection.

Required if you use your system Python 2.7.x

  • build-essential
  • libjpeg-dev
  • python-dev
  • libxml2-dev
  • libxslt1-dev

Required if you need to build Python 2.7.x

  • build-essential
  • libssl-dev
  • libz-dev
  • libjpeg-dev
  • readline-dev
  • libxml2-dev
  • libxslt1-dev

LibXML2/LibXSLT versions

Many older systems have inadequate libxslt/libxml libraries. There is no point in installing old libraries. Plone requires libxml2 >= 2.7.8 and libxslt 1.1.26. In this case, use the --static-lxml option to get the installer to build and statically link these libraries.

RPM Equivalents

These are the RPM equivalents for the Debian/Ubuntu packages listed above:

  • gcc-c++
  • patch
  • openssl-devel
  • libjpeg-devel
  • libxslt-devel
  • readline-devel
  • make
  • which


Mainly used to support indexing of office-automation documents.

  • wv (used to index Word documents)

    wv may be installed after Plone install.

  • poppler-utils (used to index PDFs)

    poppler-utils may be installed after Plone install.

Install Location, Root Install

  • Base install at /opt/plone by default. This may be changed with the --target installation option. If you change it, you'll also need to change the paths below.
  • Python installed at /opt/plone/Python-2.7
  • For ZEO Cluster:
    • ZEO cluster (server and 2 clients) installed and configured at /opt/plone/zeocluster Both --target and --name options may change this.
    • Add-on Products folder at /opt/plone/zeocluster/ products. (You may also install products via buildout.)
    • Data.fs (ZODB) at /opt/plone/zeocluster/var/filestorage
    • adminPassword.txt at /opt/plone/zeocluster/adminPassword.txt
  • For Stand-Alone:
    • Zope Instance installed and configured at /opt/plone/zinstance Both --target and --name options may change this.
    • Add-on Products folder at /opt/plone/zinstance/products (You may also install products via buildout.)
    • Data.fs (ZODB) at /opt/plone/zinstance/var/filestorage
    • adminPassword.txt at /opt/plone/zinstance/adminPassword.txt

Install Location, Root-less Install

  • Base install at $HOME/Plone, where $HOME is the user's home directory, by default. This may be changed with the --target installation option. If you change it, you'll also need to change the paths below.
  • Python installed at $HOME/Plone/Python-2.7
  • For ZEO Cluster:
    • ZEO cluster (server and 2 clients) installed and configured at $HOME/Plone/zeocluster Both --target and --name options may change this.
    • Add-on Products folder at $HOME/Plone/zeocluster/products (You may also install products via buildout.)
    • Data.fs (ZODB) at $HOME/Plone/zeocluster/var/filestorage
    • adminPassword.txt at $HOME/Plone/zeocluster/adminPassword.txt
  • For Stand-Alone:
    • Zope Instance installed and configured at $HOME/Plone/zinstance Both --target and --name options may change this.
    • Add-on Products folder at $HOME/Plone/zinstance/products (You may also install products via buildout.)
    • Data.fs (ZODB) at $HOME/Plone/zinstance/var/filestorage
    • adminPassword.txt at $HOME/zinstance/adminPassword.txt

Startup/Shutdown/Restart/Status instructions

Root Install

To start Plone:

>> sudo -u plone_daemon /opt/plone/zeocluster/bin/plonectl start

To stop Plone:

>> sudo -u plone_daemon /opt/plone/zeocluster/bin/plonectl stop

To restart Plone:

>> sudo -u plone_daemon /opt/plone/zeocluster/bin/plonectl restart

To check status:

>> sudo -u plone_daemon /opt/plone/zeocluster/bin/plonectl status

Replace "zeocluster" with "zinstance" or your instance name if this wasn't a standard zeo install.

Root-less Install

To start Plone:

>> $HOME/Plone/zeocluster/bin/plonectl start

To stop Plone:

>> $HOME/Plone/zeocluster/bin/plonectl stop

To restart Plone:

>> $HOME/Plone/zeocluster/bin/plonectl restart

To check status:

>> $HOME/Plone/zeocluster/bin/plonectl status

Replace "zeocluster" with "zinstance" or your instance name if this wasn't a standard zeo install.


  • Stand-Alone:

    • Zope server runs on port 8080

      Edit buildout.cfg and run bin/buildout to change port.

  • ZEO Cluster:

    • ZEO server runs on port 8100
    • ZEO client1 runs on port 8080
    • ZEO client2 runs on port 8081
    • ...

Edit buildout.cfg and run bin/buildout to change ports.

Post-installation instructions

You should be able to view the welcome page at http://localhost:8080/

That page offers options to create a new Plone site and to use the Zope Management Interface (ZMI) for lower-level control. Among the ZMI options is the ability to create additional Plone instances inside the Zope Zope object database.

(Use the admin password provided at yourinstance/adminPassword.txt)

Select "Plone site" from the "Add item" drop-down menu near top right to add a Plone site. This only needs to be done once for each Plone site you wish to add.

To change the admin password, click the "Password" link for the admin user at http://localhost:8080/acl_users/users/manage_users

Password changes will not be reflected in adminPassword.txt

Root Install Notes

If you install as root, the installer will set you instance up for operation under specific user and group ids.



This user id will be used to own the "var" and "backup" components of the install. You should run Plone using this user id:

sudo -u plone_daemon bin/plonectl start


This user id will own everything else in your installation. You must run buildout using this user id:

sudo -u plone_buildout bin/buildout


The id, "plone" unless you specify otherwise, will be created if it doesn't exist.

The Zope daemon will be set up run under this user id, and the user will be the owner of the files in the instance and buildout cache subdirectories.

This means that you will need to prefix your start/stop/buildout commands with:

sudo -u plone

to make sure they run under the correct user id.

If you try to start Zope as root, it will automatically switch effective ID to the configured user. However, you'll need to be sure to run buildout (for configuration updates) via sudo. Running buildout as root is a security risk.

Installation Errors

The installer may fail for a variety of reasons. If the error message is not helpful, check the detailed installation log, install.log, to look for problems. You may be able to get help on the #plone IRC channel on, or from the Plone Community Forum or the plone-setup mailing list. See Plone Support Center. If you suspect the error is due to a bug in the installer, see the Installer Bug Reports section below.

Built Python does not meet requirements

This error is usually caused by a failure of the Python build to find system libraries. This should only happen, though, if the Unified Installer itself did find the libraries. Otherwise, the installation would have failed much earlier.

On Debian, Ubuntu systems, the likely cause is that your system is not accurately reporting its "multiarch" architecture. This seems to mainly happen on systems that have been upgraded from development versions.

Other systems may just be using unexpected locations for libraries. This is common on systems that have uncomfortable relationships with the GNU toolset and install GNU tools in separate locations.

Whatever the cause, the general solution is to tell the Python setup routines about the unexpected library location using the LDPATH environment variable. For example, if your readline library was in /usr/lib/oddspot, you could try running the installer with a command like:

LDPATH="-L/usr/lib/oddspot" ./ zeo ...

Updating After Installation

Always back up your installation before customizing or updating.

Customizing the installation

You may control most aspects of your installation, including changing ports and adding new packages and products by editing the buildout.cfg file in your instance home.

See tutorial Installing add-on packages with Buildout for information on buildout options.

Apply settings by running bin/buildout in your buildout installation directory.

Third-party products installed

  • PIL (Python Imaging Library)
  • lxml, libxml2, libxslt

Platform Notes

The install script requires a POSIX-compliant version of sh. If your version of sh fails on test expressions, you may need to edit the install script to specify use of zsh, bash or a later version of sh.

The install script requires several GNU build utilities such as gcc, g++, make, gunzip, bunzip2 and tar.


There is a bug in the platform patch for Python's that prevents installation of Python libraries under /usr/local for recent versions of Python's setuptools and recent versions of debian/ubuntu.

If you need to install under /usr/local, you'll need to establish a symbolic or hard link to alias the path to something other than /usr/local for purposes of the Plone install.

(For the curious: look for the bug in the get_config_h_filename function in There's nothing subtle about it.)

Mac OS X

OS X users will generally need to install XCode and XCode Command Line Tools. Some have had luck using Homebrew to provide GNU build tools. We only test with XCode.

XCode command-line tools have a separate step in recent versions of XCode. If you seem to be missing gcc, you've missed that install step.

Building Python libraries with C-language components requires an extra step in XCode 5.1+. See Apple's release notes for 5.1. The Unified Installer takes care of this for you when building the initial Plone, but you need to supply the environment flags when adding new Python eggs that have C-language components.


If you're using MacPorts, it's probably best to follow an all-or-nothing strategy: either use ports to pre-install all the dependencies (Python-2.7, libxml2, libxslt, readline and libjpg), or don't use it at all.

Mac OS X Server

If you are using LDAP for directory services, the script may be unable to reliably create users and groups.

In a custom environment such as this, scripted creation of users and groups for a root installation of Plone may be inappropriate.

You can use Workgroup Manager (Apple Server Admin Tools) to create groups that are typical to a production installation of Plone:

  • plone
  • zeo

then create users with UIDs below 500:

  • plone
  • zeo

For each user: - match the Primary Group ID to the corresponding group - decide whether to allow a shell - specify the path to the home directory.

For root installation of a ZEO cluster on Mac OS X, custom paths might be:

  • /Applications/Plone/homes/plone
  • /Applications/Plone/homes/zeo

when scripted installation of Plone proceeds, it will make that directory hierarchy for you.

After you configure users and groups to suit your planned use of Plone, you can re-run


The Unified Installer is not smart enough to install Python 2.7.x on OpenBSD/NetBSD; it just requires too many platform- specific patches. Instead of having the installer build Python, just make sure Python 2.7 is preinstalled with system packages or ports.

Test builds on OpenBSD 4.2 succeeded with the following packages pre-installed:

block-sorting file compressor, unencumbered
interpreted object-oriented programming language
expat module for Python

If you are unable to install python-expat-2.6.7, you may need to install the xbase file set, which includes expat in some versions of OpenBSD (4.2).


If you're using an *nix system that does not use GNU build tools, you probably already know that installing open-source software based on GNU tools requires some extra work. Ideally, you'll have already installed the full GNU build tool kit and become proficient with specifying compile and link paths to them via CFLAGS and LDFLAGS. Expect to use those skills when installing Plone. If CFLAGS/LDFLAGS/CPPFLAGS are in the environment when the installer is run, it will use them rather than set its own. As with other environments, preinstall as many dependencies as possible.

Installing behind HTTP proxies

The installer should not need to access network resources for most installs, as it includes the needed components. However, if you need to use the static xml build, network access will be required. Network access will also be required when you run buildout later.

If you're behind an HTTP proxy, you're going to need to take special measures to access the larger network.

As with Python setuptools in general, indicate an HTTP proxy by setting the http_proxy environment variable:

export http_proxy=

before running the installer or buildout.

If you are using sudo, an extra step is needed to make sure the environment variable passes to the invoked command. Use:

sudo -E ./ ...


sudo -E -u plone_buildout bin/buildout

to pass the execution environment via sudo.

Uninstall instructions

  1. Stop Plone
  2. Remove folder /opt/plone or $HOME/Plone

Backup instructions

  1. Stop Plone

  2. Back up folder /opt/plone or $HOME/Plone:

    >> tar -zcvf Plone-backup.tgz /opt/plone

Live backup is possible and desirable. See Backing up your Plone deployment

Coexistence with System Python

The Python installed by the Unified Installer should not interfere with any other Python on your system. The Installer bundles Python 2.7.9, placing it at /opt/plone/Python-2.7 or $HOME/Plone/Python-2.7

Developer Options

After installation, read the instructions at the top of the develop.cfg file at the top of the instance directory. This provides support for building a development environment.

Custom buildout.cfg Template

You may specify --template= to pick a file to use as a template for the buildout.cfg file. The file must be located in buildout_templates, and should be generally modified on the buildout.cfg included with the installer. The safest customizations will be to add eggs, parts or version pinnings.

The purpose of this option is to allow for feature packaging for particular use cases with common add-on needs.

Installer Bug reports

Open an issue at


The Unified Installer was originally developed for Plone 2.5 by Kamal Gill. Adaptation to Plone 3.x, 4.x, 5.x and buildout: Steve McMahon ( Maintainer for Plone 3.x, 4.x: Steve McMahon and the Plone installer team. Special thanks to Sven Strack.

Thanks for Naotaka Jay Hotta for suggesting -- and offering an initial implementation for -- stand-alone and cluster configuration options.

Thanks to Larry T of the Davis Plone Group for the first implementation of the rootless install.

Thanks to Barry Page and Larry Pitcher for their work on the init scripts.

Something went wrong with that request. Please try again.