This document provides several methods of installing TurboGears; the method you choose will depend on your level of experience and platform.
We recommend installing TurboGears 2 into a virtual environment which will prevent any interference with your system’s installed packages and won’t unknowingly upgrade any python libraries that your system needs.
If you want to build packages of TurboGears for your system please send an email to turbogears-trunk@googlegroups.com
- Python
- Setuptools
- Database & Drivers
- other dependencies
- virtualenv
TurboGears works with any version of python between 2.4 and 2.6. The most widely deployed version of python at the moment of this writing is version 2.5. Both python 2.4 and python 2.6 require additional steps which will be covered in the appropriate sections. Python 3.0 is currently unsupported due to lack of support in many of our upstream packages.
We recommend you use your system’s default python install or follow the instructions provided here: http://python.org/download/
If you don’t know which version of python you have installed you can find out with the following command:
$ python --version
Python 2.5.2
download http://peak.telecommunity.com/dist/ez_setup.py and then run it from the command line.
$ wget http://peak.telecommunity.com/dist/ez_setup.py | sudo python
You may also use your system’s package for setuptools.
TODO
Hint
You most likely want setuptools 0.6c9 or greater as this one provides fixes to work with svn1.5. If you ever get an error regarding ‘log’ please run:
$ easy_install -U setuptools
To confirm this worked run:
$ python
>>> import setuptools
>>> setuptools.__version__
'0.6c9'
Hint
The installation of the database backend is a topic outside of the scope of this document.
TurboGears uses SQLAlchemy as its default ORM (Object Relational Mapper) layer. SQLAlchemy maintains excellent documentation on all the engines supported.
Python 2.4 users will also need to install pysqlite themselves in order to use the sqlite database in the default configuration
Cygwin users can’t use sqlite as it does not include the necessary binary file (sqlite3.dll). If you want to run Cygwin you’ll need to install a different database.
You will most likely need a C compiler and the python header files. Please see the appropriate section below.
We include pre-compiled binaries for windows in our package index.
If you want to help us keep all binaries up to date please write to turbogears-trunk@googlegroups.com to become part of our windows egg building team
You may also want the win32api package as it provides some very useful tools for windows developers, the first you will encounter is the ability to make virtualenv work with paths that contain spaces.
See also pylunch
See also windows installer
You must perform all operations, including setup operations, within DOS command windows, not Cygwin command window.
Xcode is required to build some binary dependancies and is available on the OS X CD or at http://developer.apple.com/tools/xcode/.
Debian derived Linux versions require python-dev and build-essential:
$ apt-get install python-dev
$ apt-get install build-essential
Nothing extra is required as Gentoo has a full development environment configured by default.
You’ll need a working version of the GCC compiler installed, as well as the Python headers.
We strongly advise you to install all your TurboGears apps inside a virtualenv. If you ask for support without a virtualenv to isolate your packages we will usually ask you to go get virtualenv before proceeding further.
virtualenv is a tool that you can use to keep your Python path clean and tidy. It allows you to install new packages and all of their dependencies into a clean working environment, thus eliminating the possibility that installing turbogears or some other new package will break your existing Python environment.
The other great advantage of virtualenv is that it allows you to run multiple versions of the same package in parallel which is great for running both the production version and the development version of an application on the same machine.
People with a sys-admin background could consider virtualenv as a variation of an OS jail (chroot) which is also good for security as your installation is totally isolated. This makes virtualenv great for deploying production sites.
installing virtualenv:
On Windows:
easy_install virtualenv
On Unix:
$ sudo easy_install virtualenv
On Unix (non-root):
$ easy_install --install-dir=$HOME/lib/python2.5/ --script-dir=$HOME/bin/ virtualenv
will output something like:
Searching for virtualenv
Reading http://pypi.python.org/simple/virtualenv/
Best match: virtualenv 1.3.2
Downloading http://pypi.python.org/packages/2.5/v/virtualenv/virtualenv-1.3.2-py2.5.egg#md5=1db8cdd823739c79330a138327239551
Processing virtualenv-1.3.2-py2.5.egg
.....
Processing dependencies for virtualenv
Finished processing dependencies for virtualenv
We provide several methods for installing TurboGears which depend on the level of control you want over it
- tutorial (still not complete)
- tg2-bootstrap.py
- plain virtualenv
- using pip (experimental)
- development version
Hint
Please note we are using tg2env as the name of the virtual environment. This is simply a convention in our documentation, the name of the virtualenv depends totally on the user and should be named according to the project it contains.
If this is your first time using TurboGears you can use the bootstrap script. tg2-bootstrap.py is a custom virtualenv script. It will:
- create a virtualenv for you
- install the latest TurboGears in it
Download and run the script with the following commands:
wget http://www.turbogears.org/2.0/downloads/current/tg2-bootstrap.py
python tg2-bootstrap.py --no-site-packages tg2env
First, cd to the directory where you want your virtual environment for TurboGears 2. Note the virtualenv will be created as a subdirectory here.
Now create a new virtual environment named tg2env
$ virtualenv --no-site-packages tg2env
that produces something like this:
Using real prefix '/usr/local'
New python executable in tg2env/bin/python
Installing setuptools............done.
First go inside the virtualenv:
$ cd tg2env
On Windows you activate a virtualenv with the command:
Scripts\activate.bat
On Unix you activate a virtualenv with the command:
$ source bin/activate
If you are on Unix your prompt should change to indicate that you’re in a virtualenv. It will look something like this:
(tg2env)username@host:~/tg2env$
The net result of activating your virtualenv is that your PATH variable now points to the tools in tg2evn/bin and your python will look for libraries in tg2evn/lib.
Therefore you need to reactivate your virtualenv every time you want to work on your tg2env environment.
You’ll be able to install the latest released version of TurboGears via:
(tg2env)$ easy_install -i http://www.turbogears.org/2.0/downloads/current/index tg.devtools
Warning
if you are upgrading from a previous TG2 version your command should be:
(tg2env)$ easy_install -U -i http://www.turbogears.org/2.0/downloads/current/index tg.devtools
TurboGears and all of its dependencies should download and install themselves. (This may take several minutes.)
When you are done working simply run the deactivate virtualenv shell command:
(tg2env)user@host:~/tg2env$ deactivate
user@host:~/tg2env$
This isn’t really needed but it’s good practice if you want to switch your shell to do some other work.
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.
Warning
pip is not supported under windows!
Just add the --pip flag to the bootstrap script:
$ python tg2-bootstrap.py --no-site-packages --pip tg2env
- All major Linux distributions have this installed. The package is normally named subversion
- On windows you can download the Subversion installer
Check out the latest code from the subversion repositories:
(tg2dev)$ svn co http://svn.turbogears.org/projects/tg.devtools/trunk tgdevtools
(tg2dev)$ svn co http://svn.turbogears.org/trunk tg2
Tell setuptools to use these versions that you have just checked out via SVN:
(tg2dev)$ cd tg2
(tg2dev)$ python setup.py develop
(tg2dev)$ cd ../tgdevtools
(tg2dev)$ python setup.py develop
use the --trunk flag to the bootstrap script:
$ python tg2-bootstrap.py --no-site-packages --trunk tg2env
or install via pip manually
$ easy_install pip
$ pip install -e svn+http://svn.turbogears.org/trunk
$ pip install -e svn+http://svn.turbogears.org/projects/tg.devtools/trunk
To check if you installed TurboGears 2 correctly, type
(tg2env)$ paster --help
and you should see something like:
Usage: paster [paster_options] COMMAND [command_options]
Options:
--version show program's version number and exit
--plugin=PLUGINS Add a plugin to the list of commands (plugins are Egg
specs; will also require() the Egg)
-h, --help Show this help message
Commands:
create Create the file layout for a Python distribution
help Display help
make-config Install a package and create a fresh config file/directory
points Show information about entry points
post Run a request for the described application
request Run a request for the described application
serve Serve the described application
setup-app Setup an application, given a config file
TurboGears2:
quickstart Create a new TurboGears 2 project.
tginfo Show TurboGears 2 related projects and their versions
Notice the “TurboGears2” command section at the end of the output – this indicates that turbogears is installed in your current path.
Paster has replaced the old tg-admin command, and most of the tg-admin commands have now been re-implemented as paster commands. For example, tg-admin quickstart command has changed to paster quickstart, and tg-admin info command has changed to paster tginfo.
For a full list of turbogears commands see Command Line reference
If you are new to turbogears you will want to continue with the Quick Start Guide
If you are a TG1 user be sure to check out our What’s new in TurboGears 2.0 page to get a picture of what’s changed in TurboGears2 so far.