TurboGears 2.5: a hybrid framework that runs as one file or a full stack

One framework, two shapes, and the decision happens at configuration time

TurboGears is described as a hybrid web framework that can act both as a full stack framework and as a microframework. The project notes put it plainly: you can use it both ways, and it helps you get going fast and gets out of your way when you want it to.

The mechanism is visible in the minimal example. A `MinimalApplicationConfigurator` is created, given a root controller through `update_blueprint`, and then turned into a WSGI application with `config.make_wsgi_app()`. There is no project scaffolding, no settings file, no template directory and no ORM. The whole thing is a Python file you run directly.

That is the same shape as a microframework such as Flask or Bottle, and the difference from those is what happens when you want more. The full stack layer is where TurboGears adds an ORM-backed model layer, template engines, an identity and authorisation system, and the notion of pluggable applications that can be mounted into a site.

The repository description says the full stack layer is implemented on top of a microframework core, with support for SQL DBMS, MongoDB and pluggable applications. That is the architecture in one sentence: the microframework is the foundation, the full stack layer is an addition, and the same importable package serves both.

The project notes are explicit that the examples shown are in minimal mode and points to a separate repository, tg2devtools, for the full stack examples. That is a fair arrangement, and it is also a reminder that the full stack path is a separate learning curve rather than a switch in the same file.

The homepage is turbogears.org, the documentation is at turbogears.readthedocs.io, and the project is on PyPI as TurboGears2.

The minimal mode example is the whole quickstart

The getting started instructions are short enough to reproduce, and they show the shape of the framework better than a description would.

The install is pip, after getting pip if you do not have it:

$ curl -O 'https://bootstrap.pypa.io/get-pip.py'
$ python get-pip.py

$ pip install TurboGears2

Then you write a `webapp.py`:

from wsgiref.simple_server import make_server
from tg import MinimalApplicationConfigurator
from tg import expose, TGController

# RootController of our web app, in charge of serving content for /
class RootController(TGController):
    @expose(content_type="text/plain")
    def index(self):
        return 'Hello World'

# Configure a new minimal application with our root controller.
config = MinimalApplicationConfigurator()
config.update_blueprint({
    'root_controller': RootController()
})

# Serve the newly configured web application.
print("Serving on port 8080...")
httpd = make_server('', 8080, config.make_wsgi_app())
httpd.serve_forever()

and you run it with `python webapp.py` and open `http://localhost:8080/`.

Two details in that example carry most of the design. The controller uses `@expose(content_type="text/plain")` on a method of a `TGController` subclass, so routing is an annotation on the controller rather than a separate route table. And the server is `wsgiref.simple_server`, the standard library one, which means the example needs no web server dependency at all and the framework is reachable over plain WSGI.

That WSGI point is the real constraint on adopting this today. TurboGears is a WSGI application framework, and WSGI is synchronous, so an async Python deployment is not what this is built for.

The dependency list explains what the core is and is not

The runtime dependencies in pyproject.toml are worth reading closely, because they define the core's size.

There are four: `WebOb>=1.8.9,<1.10.0`, which is the request and response object library that most Python web stacks sit on, `crank>=0.9.0,<0.10.0`, which is the routing and controller layer, `repoze.lru`, a caching decorator, and `MarkupSafe` for escaping.

That is a small core, and it tells you that TurboGears does not force an ORM, a template engine, a form library or an admin interface on you. You choose what to add, and you add them as pluggable applications.

The optional `testing` extra is where the full stack surface shows up. It pulls pytest with coverage, and then the alternatives: `zope.sqlalchemy`, `sqlalchemy`, `ming` for MongoDB, `repoze.who` for identity, `Genshi`, `Mako` and `Kajiki` as template engines, `jinja2` as a fourth, `formencode` for forms, `WebTest` and `backlash` for functional testing of a WSGI app, plus `Beaker` for caching sessions and `raven` for error reporting.

Having three or four template engines listed at once is a characteristic of a framework that grew up around a pluggable application model rather than around one opinion. It also means the choice is yours to make, and that the documentation has more surface to cover.

The keywords in the project metadata give the same summary: framework, full-stack, microframework, python, python-2, python-3, web, webframework.

A licence that is MIT style but not quite MIT

The licence wording in the README is worth reading closely, because it is unusual and it is a factual constraint.

TurboGears is licensed under an MIT-style license, with the text in LICENSE.txt. But the README adds two qualifications: other incorporated projects may be licensed under different licenses, and all licenses allow for non-commercial and commercial use.

So the framework itself is permissively licensed and there is no copyleft obligation, but the MIT-style phrasing plus the note about incorporated projects means you cannot assume every dependency in the tree carries the same terms. The LICENSE.txt file at the repository root is where the actual grant is, and the repository listing shows a LICENSE.txt alongside CHANGES.txt, CONTRIBUTING.txt, a `.coveragerc`, a `.devcontainer/` directory, `scripts/`, `setup.py` and the `tg/` package directory.

The metadata records the license as MIT with `license = { text = "MIT" }`, and the classifiers list Python 3.10 through 3.14 as supported versions, with `requires-python = ">=3.10"`.

The authors list is long and includes names you may recognise from the Python web world, which tells you something about the project's history: Alessandro Molina, Mark Ramm, Christopher Perkins, Jonathan LaCour, Rick Copland, Alberto Valverde and Michael Pedersen. The build system is setuptools with a modern floor, `setuptools>=61.0`, and the package is not zip safe, so it installs as a directory rather than an egg.

The release history shows a long gap and a recent burst

The version history is the most informative thing about the project.

The recent releases are tg2.5.1 dated 2026-10-12, tg2.5.0 dated 2025-02-18, and tg2.4.3 dated 2020-03-01. So version 2.4.3 sat as the release for roughly five years, then 2.5.0 arrived in early 2025, and 2.5.1 followed in October 2026.

That pattern says two things at once. The project is not dead, because the last release and the last push are both within days of each other, and the repository is not archived. And it says the long 2.4.x era was a maintenance period rather than an active development one, which is what you would expect of a framework whose core dependencies are four packages and whose differentiating layer lives in pluggable applications rather than in this repository.

The default branch is `development`, and the continuous integration badges point at a workflow called run-tests.yml with coverage tracked on Coveralls against the development branch. There is also a CodeTriage badge and a Gitter room badge, both of which point at the community channels of an older generation of Python projects.

For an adopter, the practical reading is that TurboGears 2.5 is a maintained release line with a recent patch, that the ecosystem around it is where the activity is, and that the core you install is deliberately small. The repository is not archived and the last push was on 2026-10-12.

Where TurboGears is the wrong choice

Three boundaries are concrete.

The first is the WSGI and synchronous model. The example serves the application through `wsgiref.simple_server`, and the whole stack is WSGI. If your deployment target is an async stack, or if the workload you have is dominated by many concurrent slow I/O calls rather than by CPU bound work, that is a poor fit, and there are frameworks built for it.

The second is the size of the ecosystem compared with the full stack frameworks that compete with it. TurboGears gives you pluggable applications and a choice of template engines, which is genuine flexibility, but you assemble the stack yourself. A team that wants a batteries included framework with an admin interface generated from your models will not find that here.

The third is the documentation shape. The documentation lives at turbogears.readthedocs.io and is written in reStructuredText, and the tutorials named in the README are Getting Started with Turbogears and Building a Wiki in 20 minutes. The latter title tells you the target audience, and the wiki build is a good first project precisely because it is small and complete. But if you are used to modern, heavily cross linked API documentation, the experience is dated.

The alternative to name is a modern Python framework with an async core and a large third party ecosystem. The difference in approach is that TurboGears treats the full stack layer as an optional set of pluggable applications on a WSGI microframework core, so you can take only the pieces you want and assemble the rest, whereas a batteries included framework gives you a decided stack and a large community of extensions for it. Neither is wrong, but the trade is assembly work against ecosystem depth, and TurboGears also competes directly with the option of staying in a microframework and writing the parts you need yourself.

Editorial conclusion

Adopt TurboGears if you want a Python framework that starts as a single file and grows into a full stack MVC application with pluggable applications and a real ORM story, and you are comfortable with a framework whose documentation and templates are reStructuredText. Do not adopt it if you want a modern async framework or a large selection of batteries-included components, since the core depends on four modest packages and the full stack layer lives in separate pluggable packages. Verify first which template engines and ORM backends you need in the testing extra, that your deployment target is WSGI, and what the non MIT parts of the licence cover.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. TurboGears/tg2 on GitHub