2. Download and Install CherryPy – CherryPy Essentials

Chapter 2. Download and Install CherryPy

Like most open-source projects, CherryPy can be downloaded and installed in various ways. Here we will discuss the following three methods:

  • Using a tarball

  • Using easy_install

  • Getting the latest version of the source code using Subversion

Each one brings a different value to the users of the project and it is important to understand the contribution made by each.

Once you have read this chapter, you should be able to retrieve and deploy CherryPy, as well as understand how to use each technique for your own software.


Throughout this book we will assume you have the following packages installed and available.

  • Python 2.4 or above

  • CherryPy 3.0

We will also assume you have knowledge of Python itself as we will not cover the language.


Installing a Python module or package is usually an easy process. First let's discuss the most common way to build and install a new package, thanks to a standard module, distutils, which appeared with Python 2.0.

This module provides a clean interface for specifying how a package is structured, what are the required dependencies, and the building rules of the package. For the user, it usually means typing the following commands:

python setup.py build
python setup.py install

The first one will simply build the package against the rules defined by the developers, reporting errors so that the end user knows about a missing dependency for example. The second one will install the package in the default directory used by Python to store third-party packages or modules. Note that the latter command will call the former by default to quickly check that nothing has changed since the last run.

The default directories where packages and modules are stored are:

  • On UNIX or Linux /usr/local/lib/python2.4/site-packages or /usr/lib/python2.4/site-packages

  • On Microsoft Windows C:\Python or C:\Python2x

  • On MacOS Python:Lib:site-packages

On UNIX or Linux it will depend how your Python installation has been deployed, but the directories given above are the most common. When importing a module, Python will look into a list of directories, some defaults and others provided by the user, until it finds a matching module or else an exception will be raised. The searched list can be modified either by defining the PYTHONPATH environment variable or by amending it from the code itself as follows:

import sys


The PYTHONPATH environment variable is one of the variables read by the Python engine when it is being launched. It contains additional paths to append to the searched list of paths for third-party modules and packages.

Another method is to set a file named after the package with the .pth extension. This file should contain the full path of the package.

Notwithstanding its simplicity, this algorithm has its limitations. Since the sys.path list is ordered you have to make sure that if two paths contain the same module with different versions, the one your application imports is the first one to be reached. This leads us to the following package versioning problem.

Imagine that you install CherryPy 2.2.1 in your global installation of Python; it would be available under the directory /usr/local/lib/site-packages/cherrypy. However, the path does not contain the version information of the package. Therefore, if you must install CherryPy 3.0.0 as well, you have to overwrite the existing installation.

Luckily the Python community has come up with a solution to this problem—eggs. An egg is a compressed folder containing all the files and sub-folders of a package with the version details of the package in its name.


An egg is a distributable bundle, by default zipped, of a Python package or module including information such as the author and the version of the package.

For example, CherryPy 2.2.1 built by Python 2.4 would look like the following: Cherrypy-2.2.1-py2.4.egg. An egg by itself is not very useful; its deployment requires easy_install, a Python module that contains the logic for handling eggs. This means you can have multiple versions deployed in the same directory and leave it up to easy_install to decide which one to load.

In the next sections we will see in detail how to install CherryPy using the most common cases.

Installation from a Tarball

A tarball is a compressed archive of a file or directory. The name comes from the use of the tar utility found on UNIX and related operating systems.


Historically the compression used has usually been gzip and the extension of a tarball is either .tar.gz or .tgz.

CherryPy provides a tarball for each release whether it is alpha, beta, release candidate, or stable. They can all be retrieved from http://download.cherrypy.org/.

CherryPy tarballs contain the complete source code of the library.

To install CherryPy from a tarball you need to go through the following steps:

  1. 1. Download the version that interests you from http://download.cherrypy.org/.

  2. 2. Go to the directory where the tarball has been downloaded and uncompress it:

    • If you are using Linux, type the following command:

      tar zxvf cherrypy-x.y.z.tgz

    In the given command, x.y.z is the version you have fetched.

    • If you are running Microsoft Windows, you can use a utility such as 7-Zip to uncompress the archive via a graphical interface.

  3. 3. Move to the newly created directory and enter the following command, which will build CherryPy:

    python setup.py build
  4. 4. Finally, in order to do a global installation you have to issue the following command (you will more than likely need administrator permissions):

python setup.py install


Note that these commands will have to be issued from a command line. Under Microsoft Windows you will run those from a DOS command prompt

The above steps will perform a global installation of CherryPy on your system for the default Python environment. There are cases where this is not suitable or not possible. For example, you may want to install CherryPy only for a given version of Python; in that case you will have to specify the correct Python binary such as python2.4 in steps 3 and 4 mentioned earlier.

It may also happen that you prefer not to do a global installation, in that case the quickest way under UNIX and Linux is to replace step 4 mentioned earlier with:

python setup.py install --home=~

This will put the files in $HOME/lib/python where $HOME represents your home directory.

Under Microsoft Windows, which has no knowledge of HOME, you would do the following:

python setup.py install --prefix=c:\some\path

The path you choose is not important in itself and you can use whatever suits your environment.

Then you will have to make sure Python goes through that directory when you need to import modules. The easiest way is to set the PYTHONPATH environment variable to the following:

  • On Linux using a bash shell

    export PYTHONPATH=~/lib/python
  • On Microsoft Windows using a command prompt

    set PYTHONPATH=/some/path/


    Note that this will only last while the Command window is opened and will be dropped once you close it. To make the changes permanent you should set the global PYTHONPATH variable via System Properties | Advanced | Environment Variables.

  • On MacOS using a csh shell

    setenv PYTHONPATH "/some/path/"

The PYTHONPATH environment variable will be read at startup by the Python interpreter, which will append it to its internal system path.

Installation through Easy Install

Easy_install is a Python module that can be found on the Python Enterprise Application Kit (PEAK) website to facilitate the deployment of Python packages and modules. From the developer's point of view, it provides an easy API to import Python modules either for a given version or a range of versions. For instance, here is what you would do to load the first CherryPy version greater than 2.2 found in your environment:

>>> from pkg_resources import require
>>> require("cherrypy>=2.2")
[CherryPy 2.2.1 (/home/sylvain/lib/python/

From the user's point of view it simplifies the procedure of downloading, building, and deploying Python products.

Before installing CherryPy, we must install easy_install itself. Download the ez_setup.py module from http://peak.telecommunity.com/dist/ez_setup.py and run it as follows, as a user with administrative rights on the computer:

python ez_setup.py

If you do not have administrator permission, you can use the -install-dir (-d) option as follows:

python ez_setup.py -install-dir=/some/path

Make sure that /some/path is part of the Python system path. You can set PYTHONPATH to that directory for example.

This will set up your environment to support easy_install. Then to install a Python product that supports easy_install, you should issue the following command:

easy_install product_name

easy_install will search the Python Package Index (PyPI) to find the given product. PyPI is a centralized repository of information about Python products.

In order to deploy the latest available version of CherryPy, you should then issue the following command:

easy_install cherrypy

easy_install will then download CherryPy, build, and install it globally to your Python environment. If you prefer installing it in a specific location, you will have to enter the following command:

easy_install --install-dir=~ cherrypy

Once installed, you will have a file named cherrypy.x.y.z-py2.4.egg depending on the latest version of CherryPy.

Installation from Subversion

Subversion is an excellent open-source revision control system that allows developers to carry out projects in a controlled and concurrent manner.

The basic principle of such systems is to register a resource and then keep track of every change made to it, so that any developer can retrieve any previous version, compare two versions, or even follow the evolution over time of the said resource. A resource can be a source code file, a binary, an image, documentation, or anything that is expressible in machine-readable form.

Subversion is centralized, so a project is managed by a subversion server and each client has a copy of it. The developer works on that copy and commits back any changes he or she has made. When a conflict arises, for instance, if another developer has modified the same file and has committed it already, the server will let you know and forbid your commit until you resolve the issue.

Subversion is atomic, which means that if a commit fails on one file the whole commit fails. On the other hand if it succeeds the entire project revision is incremented, not just the files involved.


Subversion is often viewed as the successor of CVS and is considered much friendlier. However, other revision systems also exist such as Monotone or Darcs.

Under Linux, you can either install Subversion from its sources or using a package manager. Let's describe the procedure for the source code.

  1. 1. Get the latest tarball from http://subversion.tigris.org/

  2. 2. Then type the following command in the command console:

tar zxvf subversion-x.y.z.tar.gz

  1. 3. Enter the newly created directory and type: ./configure

  2. 4. Then to build the package itself type: make

  3. 5. You might later need the Python binding for Subversion as well:

     make swig-py
  4. 6. To install Subversion globally, you will need to be the administrator and then enter: make install; make install-swig-py

Most of the time, under Linux or UNIX, it is easier to use Subversion through the command line. However, if you prefer to use a graphical interface, I would advise you to install a fat client application such as eSvn or kdesvn.

Under Microsoft Windows, it is much easier to directly use a graphical application such as TortoiseSVN, which will install the Subversion client as well.

Getting CherryPy using Subversion is recommended in the following situations:

  • A feature exists or a bug has been fixed and is only available in code under development.

  • You decide to work on CherryPy itself.

  • You need to branch from the main trunk in order to try and see a feature, a new design, or simply backport bug fixing in a previous release.

In order to use the most recent version of the project, you will first need to check out the trunk folder found on the Subversion repository. Enter the following command from a shell:

svn co http://svn.cherrypy.org/trunk cherrypy


Under Microsoft Windows you can do this from a command line or simply use TortoiseSVN. Please refer to its documentation for more information.

This will create a cherrypy directory and download the complete source code into it. As it is usually not recommended to deploy globally a version under development; you would type the following command to install CherryPy into a local directory:

  • Under Linux and related systems using a console:

python setup.py install --home=~

  • Under Microsoft Windows using the command prompt:

python setup.py install --prefix=c:\some\path

Then simply point the PYTHONPATH environment variable to the chosen directory.

Note that this directory does not matter as long as it is reachable by the Python process via PYTHONPATH or the standard sys module.

Testing your Installation

Whichever way you decide to install and deploy CherryPy in your environment, you must be able to import it from the Python shell as follows:

>>> import cherrypy
>>> cherrypy.__version__

If you do not install CherryPy globally to your Python environment, do not forget to set the PYTHONPATH environment variable, else you will get an error as follows:

>>> import cherrypy
Traceback (most recent call last):
File "<stdin>", line 1, in ?
ImportError: No module named cherrypy

Keeping CherryPy Up to Date

Updating or upgrading CherryPy will depend on the approach you have taken to install it.

  • Installed using a tarball

    Usually the cleanest way to ensure the update goes smoothly is to first remove the directory containing the package from its location in sys.path, then to follow the steps described previously to install the library.

  • Installed using easy_install

    Updating is one of the key features provided by easy_install.

easy_install -U cherrypy
  • As the eggs containing the library are named after the version they serve, you can simply follow the steps defined in the previous section without removing an existing egg. Be careful though, as this only holds true when the application running specifies precisely which version it requires.

  • Installed using Subversion

    The interesting aspect of this approach is that you can update the library almost continuously. To update your installation, you need to enter svn update from the top directory holding the source code and then issue the python setup.py install command.


As always remember to take a backup of your files before doing an update.


We have discussed in this chapter the different ways of installing CherryPy in your environment via three techniques. The traditional approach is to use an archive containing all the files of the Python package to install and use the setup.py module within that archive. A newer and more common way of deploying a package is to use the easy_install command to install eggs. Finally, if you wish to be synchronized with the latest development of CherryPy, you can get the package from its Subversion repository. Whichever method you follow, they will all lead to CherryPy being available on your system.