Alternate Installation Process

This document provides instructions on how to install TurboGears in ways which are not necessarily recommended for the new developer. TurboGears 2.1 Standard Installation describes the recommended new-developer installation environment. This document also includes commonly necessary tasks such as installing database drivers and upgrading an existing TurboGears install.

This includes the following non-standard environments:

32-bit Windows


While Windows is a supported platform for TurboGears, it is not commonly used for deployments. You may wish to consider setting up a virtual machine with a Debian or RPM-based Linux distribution so that your development environment is closer to your deployment environment.

Install Python (download and run an executable or MSI installer):

  • Python – choose version 2.6 or 2.5 for best results

Download and then run it from the command line with Python. Note that you must install a specific version of SetupTools.

c:\working>c:\Python26\python.exe "setuptools==0.6c9"

Once you have run the SetupTools installer, you can add the c:\Python26 and c:\Python26\Scripts directories to your system path (in Control Panel/System/Advanced) so that you can run Python and easy_install from the command line.

c:\working>c:\Python26\Scripts\easy_install.exe virtualenv
c:\working>c:\Python26\Scripts\virtualenv.exe example
c:\working>cd example
(example) C:\working\example>easy_install.exe -i tg.devtools
(example) C:\working\example>paster quickstart example
(example) C:\working\example>cd example
(example) C:\working\example\example>python develop
(example) C:\working\example\example>paster setup-app development.ini
(example) C:\working\example\example>paster serve development.ini

You should now be able to view http://localhost:8080 in a web browser. You can hit CTRL-C on the command-line to stop the server.

Mac OSX Install

OS-X development is normally done with “stock” Python installed via the “one-button installer” (a .dmg file). It is not normally recommended that you use the “system” Python for TurboGears development.

Once Python is installed, you need to install the SetupTools and VirtualEnv packages into the new Python installation. To do so:

$ curl -O
$ sudo python "setuptools==0.6c9"
$ sudo easy_install virtualenv

At this point, you can continue with the TurboGears 2.1 Standard Installation as if you were using a Linux machine.

Linux Root Install


You are strongly encouraged to use a virtualenv-based environment for TurboGears, as this allows you to easily manage your TurboGears installation independent of your platform’s release schedule. Most Linux distributions package only extremely old versions of TurboGears.

On RedHat Enterprise Linux (RHEL) 5, you can install TurboGears from official RPM packages via:

$ yum install TurboGears2 python-tg-devtools

Python 2.4 Installation

Python 2.4 is missing a number of packages that TurboGears requires. To install these packages, you can use easy_install in your virtualenv. While Python 2.5 or 2.6 is recommended, some distributions, such as RHEL 5, use Python 2.4 by default. These instructions describe how to install TurboGears as a non-root virtualenv, if you are using RHEL 5 and wish to install from RPM see Linux Root Install above:

$ virtualenv --no-site-packages tg2env
$ cd tg2env/
$ source bin/activate
(tg2env)$ easy_install hashlib pysqlite uuid functools


For Python 2.4, you must make sure to install Beaker 1.4 or higher. Though it should be automatic, you may need to run this command to get it:

(tg2env)$ easy_install -U beaker

You can continue to follow TurboGears 2.1 Standard Installation from this point forward.

Install Via PIP

pip (or pip installs packages) is an experimental easy_install replacement. It provides many improvements over it’s predecessor and aims to be a full replacement.


pip is not supported under windows!

To install, use pip with the same index URL (the “-i” argument) as for a standard installation via setuptools/easy_install and specify the “-E” argument to provide the name of the VirtualEnv to create.

$ pip install -E tg2env -i tg.devtools

Which will create a tg2env VirtualEnv and install TurboGears into it. From this point, switch to the VirtualEnv, activate it and continue with the TurboGears 2.1 Standard Installation. PIP can also be used to perform a source install using Mercurial, see Source Install (Development Version) for details.

Source Install (Development Version)

Generally you should not need to install a development version of TurboGears unless you wish to contribute to the project (which is strongly encouraged). TurboGears uses the Mercurial Distributed Version Control system hosted on the BitBucket site. For a detailed discussion of how to use Mercurial and BitBucket see Using BitBucket’s Mercurial Service with TurboGears.

Getting Mercurial

  • All major Linux distributions have this software packaged. The package is normally named mercurial
  • On windows you can download the TortoiseHG installer
  • On other platforms you may install the HG command line utility with an easy_install command:
(tg2dev)$ easy_install mercurial

Getting The Source

Check out the latest code from the subversion repositories:

(tg2dev)$ hg clone tgdevtools
(tg2dev)$ hg clone tg

For hacking on the Administrative UI and the CRUD controller:

(tg2dev)$ hg clone tgtools-tgext-crud
(tg2dev)$ hg clone tgtools-tgext-admin

Installing The Sources

Tell setuptools to use these versions that you have just checked out via Mercurial:

  • TurboGears 2 :
(tg2dev)$ cd tg
(tg2dev)$ python develop -i
  • TurboGears 2 developer tools:
(tg2dev)$ cd ../tgdevtools
(tg2dev)$ python develop -i

Source Install Via Pip

This command tells PIP to install the two “trunk” distributions for the TurboGears project as “editable” versions using the Mercurial URLs provided.

$ easy_install pip sqlalchemy
$ pip install -i -E tg2env \
    -e 'hg+' \
    -e 'hg+'