# TurboGears Upgrade Guide

Special note for people upgrading from TurboGears 0.5: Some people report needing to update setuptools twice before the easy_install script/exe are created properly. If you find that you're missing easy_install, or get an error about there being no script called easy_install.py, just rerun the setuptools update command.

To upgrade to the latest released version of TurboGears, you should first upgrade setuptools and then upgrade TurboGears. To do so, download the ez_setup.py script. On Windows:

ez_setup.py -U setuptools

easy_install -f http://www.turbogears.org/download/index.html TurboGears

On Mac OS X and other *nix-like systems:

sudo python ez_setup.py --script-dir /usr/local/bin -U setuptools

sudo easy_install -f http://www.turbogears.org/download/index.html --script-dir /usr/local/bin TurboGears

Please also be aware of backwards compatibility issues. These are addressed in the remainder of the guide.

## Updating from 0.5 to 0.8

0.8 has a number of minor backwards incompatible changes. There are only two such changes that you'll likely need to take action on.

The primary one is the renaming of the turbogears* variables. You'll want to do project wide search/replace for these values.

Search for | Replace with
--- | ---
turbogearshtml | tg_template
turbogearsfmt | tg_format
turbogearsflash | tg_flash
turbogearsjs | tg_js

The other noticeable change that you'll come across is that turbogears-admin.py has been renamed to tg-admin. Note that in addition to the base name change, you no longer need to add the .py on the end.

Though they are less likely to pose problems for you, you may wish to check out the complete changelog for additional changes.