Start small. Build the whole app.

TurboGears is a Python web framework for services, JSON APIs and database-backed web apps. Start with one file and grow into a full-stack project.

Try TurboGears Explore the docs

Start with one file

Serve your first response without a generated project. Add controllers and templates as you need them.

Build beyond the endpoint

Generate a web app with templates, SQLAlchemy models and authentication already connected.

Make your API discoverable

The API quickstart includes validation and generated OpenAPI documentation. Build a JSON API →

Start small

One file. A working web service. Use Python 3.10+ in a virtual environment. Save this as myapp.py:

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

class RootController(TGController):
    @expose(content_type="text/plain")
    def index(self):
        return 'Hello World'

config = MinimalApplicationConfigurator()
config.update_blueprint({
    'root_controller': RootController()
})

print("Serving on port 8080...")
httpd = make_server('', 8080, config.make_wsgi_app())
httpd.serve_forever()

Install and run:

python -m pip install TurboGears2
python myapp.py

Open http://localhost:8080/ to see Hello World. Keep building: the minimal tutorial →

Build the whole app

Ready for a database-backed project? Gearbox, the development toolkit, generates your application’s structure. In a Python 3.10+ virtual environment, run:

python -m pip install tg.devtools
gearbox quickstart myproj
cd myproj
python -m pip install -e '.[development]'
gearbox setup-app -c development.ini
gearbox serve -c development.ini

setup-app creates a local development database with demo data. Open http://localhost:8080/ to explore the generated app, then follow its README.rst to make it your own.

Full-stack quickstart guide →

Prefer an API? Use gearbox quickstart-api myapi and follow the JSON API tutorial.

Give your coding agent project context

Generated project instructions and optional development tools help agents inspect your app, create conventional project files and check it in a running application context. Your app’s runtime stays independent of agent tooling.

Explore agent tooling → · See a worked example