TurboGears 2.1 Documentation


TurboGears is a web framework written in Python that combines best-of-breed technologies to offer a developer rapid initial ramp-up, an even learning curve, and scalability as your project grows. TurboGears is built on a stack of technologies that allows us to focus on the parts that are important only to TurboGears. Although TurboGears provides fully featured ORM (Object Relational Mapper), Templating Languages, and URL dispatch mechanisms, the codebase remains less than 2000 lines of executable code.

It is important to note that this version of TurboGears is a reinvention of the original TurboGears project developed by Kevin Dangoor. TurboGears 2.x was developed to increase cooperation between the Python Web Framework community, especially with the Pylons project. TurboGears also leverages WSGI (Web Server Gateway Interface) components available today. WSGI allows web applications to share a common api to provide a layered approach to generating web content.

The TurboGears Stack: An Overview

TurboGears 2.x represents a change from some of the components in TurboGears 1.x, but we’ve now invested in a set of components that we think will continue to be at the center of python web development for years to come. From the beginning TurboGears was designed to be a Full Stack framework built from best-of-breed components. TurboGears takes some of the guesswork out of choosing from the various components available by providing you with a set of productive defaults, while still providing the abilty to change those defaults if something better meets the needs of your project.

The TurboGears stack is made up of a four main components that aim at increasing web development productivity. Each of these components can in fact be used independently, or within other applications, so the knowledge you gain by learning about these components is highly applicable to other projects you might do, including those outside the scope of web design. Here is a breakdown of what you can expect to see in the stack.


ToscaWidgets is a full-featured widgetting library that makes it easier to coordinate front end design with server development. In the previous version of TurboGears this role was delegated to a single JavaScript framework: MochiKit. ToscaWidgets gives you the choice to incorporate your JS library of choice, either for your entire site, or for individual pages.

Genshi was popularized by the project tracking software called Trac. Genshi provides an easy way to create templated content by providing developers with pythonic tools, (x)html validation, and useful debugging messages. Kid developers coming over from TurboGears 1.1 will feel at home with the familiar syntax.

Pylons is our web server of choice. Pylons is a good choice for our web server, because it embraces WSGI, and is also broken into smaller swappable components. Pylons gives us routing, caching, sessions, and a set of thread-safe globals to make development easier. Why Not Just Merge With Pylons? because we want to provide a “fully configured” application stack to enable features such as the TurboGears Administration System.

SQLAlchemy has been called the best Object Relational Mapper in any language. SQLAlchemy provides a solid foundation to build your data-driven application from. SA allows you to abstract your database to Python objects, while still giving you access to your database in tabular, and even SQL form. Using SQLAlchemy also gives you the ability to use a number of add-on tools like migrate and bootalchemy.

Getting Started

Get TurboGears installed and serving up the main page for your new project Read more …


For the new TurboGears user, this is the place to start. These tutorials are intended to get you started working quickly and give you a feel for how TurboGears applications work. Read more …

Working with TurboGears

How to accomplish given tasks using TurboGears, from authentication, to caching, to user-session management. This collection of documents should normally be explored after you’ve followed through a tutorial or two. Read more …

Getting To Know TurboGears

Learn what’s new in the latest TurboGears. Explore the architecture. Learn what components come with the default install of TurboGears, what components are installed via the default quickstart, and how all of them tie together to serve your site. Read more …

Extensions and Tools

Discover new extensions and tools to enhance your installation of TurboGears. Read more …


A selection of papers and comments showing how TurboGears helped other developers solve the problems they had. Read more …

Indices and tables


These documents are a work in progress, so please feel free to tackle some of the items and send in patches!


Difficulty: Medium. make docs more linky.


Link to Pylons book for specific “more information”

Web Server Gateway Interface