Python Pyramid

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

This section is written against Pyramid 2.1 (released 2026-03-11, Python 3.10 or newer), checked on 2026-10-07. That release follows 2.0 (2021) and 2.0.2 (2023), so Pyramid is a mature, slow-moving project: releases are rare, the PyPI status is "Mature", and the companion packages (pyramid_tm, pyramid_jinja2, pyramid_debugtoolbar, pyramid_retry) change even less often. That stability is part of the appeal, and it also means that many tutorials and books still describe the 1.x APIs that 2.0 deprecated. Every page says which version introduced or removed a feature, and What’s Changed & Migration collects the differences.

What Pyramid is

Pyramid is a general-purpose Python web framework from the Pylons Project. It began as repoze.bfg in 2008, inherits ideas from Zope, and was renamed Pyramid in 2010. Its motto is "start small, finish big": a complete application fits in one file, and the same configuration system scales to large applications assembled from reusable pieces.

Three ideas set it apart from Flask and Django:

  • Explicit, conflict-checked configuration. A Configurator records what you register (routes, views, predicates, tweens, security policy). Pyramid detects conflicting registrations at startup and resolves them with a clear rule, which makes config.include() a safe composition mechanism for large applications and add-ons.

  • Two ways to find a view. URL dispatch maps patterns such as /api/books/{id} to routes, and traversal walks a tree of resources, so the URL /shelves/ada/dune becomes a context object that carries its own permissions. Both can be combined in one application.

  • Security as a first-class layer. A single security policy decides who the user is and what they may do, and per-object access control lists are inherited down the resource tree.

Pyramid is a WSGI and synchronous framework. There are no async views in 2.1, so concurrency comes from the WSGI server’s threads or workers, and the Pyramid Community Cookbook describes an ASGI wrapping recipe for the rare case where it is needed. For frameworks built around an event loop, see the ref:backend/tornado/introduction-and-architecture.adoc[Tornado] and ref:backend/fastapi/index.adoc[FastAPI] sections.

This section is for developers who:

  • know Python and want a framework that stays out of the way for small services but offers fine-grained authorization, hierarchical resources and extensibility for large ones

  • are coming from Flask or Django and want to understand what Pyramid does differently, and when it is the better choice (see Introduction & Architecture, the Flask introduction and the Django introduction)

  • maintain an existing Pyramid application and need the 2.x idioms (security policy, pyproject.toml, SQLAlchemy 2.0, JSON-only sessions) rather than the patterns in older tutorials

The Bookshelf Shelves scenario

Every example builds one small original application, Bookshelf Shelves, so the pages fit together instead of being isolated snippets:

  • public shelves owned by users, addressed by traversal (/shelves/{shelf}/{book}), with access control lists inherited from the shelf: owners edit, everyone else reads

  • a JSON API under URL dispatch (/api/books/{id}) using the json renderer and __json__

  • SQLAlchemy 2.0 with pyramid_tm and Alembic (the cookiecutter sqlalchemy backend) and Jinja2 templates through pyramid_jinja2

  • a security policy built on AuthTktCookieHelper, CSRF protection on forms, and Deform and Colander forms

  • English and Spanish translations, a timing tween, the debug toolbar in development, WebTest functional tests, and Waitress or Gunicorn deployment

Diagram of the Bookshelf Shelves application. Browsers, API clients and operators reach an nginx reverse proxy and a Waitress or Gunicorn WSGI server. Inside the Pyramid application, tweens wrap URL dispatch and traversal, which feed a security policy with ACLs and then views and renderers. Forms and CSRF, internationalization and static assets, and development extras sit alongside. Views use a SQLAlchemy 2.0 session joined to the pyramid_tm transaction, which talks to the database, and Alembic manages the schema.
Figure 1. Bookshelf Shelves: clients, WSGI server, the Pyramid application layers and the data stores

The generated project layout (development.ini, production.ini, testing.ini, a package with routes.py, views/, templates/, static/ and a tests/ folder) is introduced on ref:backend/pyramid/cookiecutter-projects-and-pserve.adoc[Cookiecutter Projects & pserve].

Reading path

The pages are ordered so that each one builds on the previous ones. Read them in this order the first time, then use them as a reference:

  1. Foundations: what Pyramid is, a single-file application, a cookiecutter project run with pserve, the configurator and the .ini settings.

  2. Routing and views: URL dispatch, traversal, view configuration and predicates, exception views, renderers, templates, the request and response, and static assets.

  3. State, forms and security: sessions and flash messages, Deform and Colander forms, the 2.0 security policy, ACL-based authorization and CSRF protection.

  4. Data: SQLAlchemy with pyramid_tm and Alembic, then ZODB and other stores.

  5. Extending, tooling and testing: events, tweens and view derivers, add-ons, internationalization, the p-scripts, logging and the debug toolbar, and testing with pyramid.testing and WebTest.

  6. Production and beyond: deployment, advanced topics, and what changed between versions.

The cheat sheet at Pyramid Cheat Sheet condenses the whole section onto one page for quick lookup.

mindmap root((Python Pyramid)) Foundations Introduction and architecture Getting started Cookiecutter and pserve Configurator Settings and ini files Routing and views URL dispatch Traversal Views and predicates Exception views Renderers and JSON Templates Request and response Static assets State and security Sessions and flash Deform and Colander Security policy ACLs and permissions CSRF Data SQLAlchemy and pyramid_tm Alembic migrations ZODB and other stores Extending and tooling Events tweens and derivers Add-ons Internationalization p-scripts Logging and debug toolbar Testing Production Waitress and Gunicorn nginx and proxies Changes and migration
Figure 2. The section at a glance

The Pyramid pages link to existing material instead of repeating it, and cover only what Pyramid adds.

Topic Where it lives How the Pyramid section relates

The Python language, packaging, virtual environments, pytest

Python Reference, including Virtual Environments & Packaging and Testing

Pyramid pages link here for general Python and cover only what Pyramid adds.

Other Python web frameworks

Python FastAPI, Flask, Python Tornado and Django

The introduction compares Pyramid with each of them and says when each is the better fit.

OAuth 2.0, OpenID Connect, JWT theory

OAuth Reference

The security pages cover the Pyramid security policy and leave the protocol theory here.

Cross-origin requests

CORS

The CSRF page links here for browser cross-origin rules.

Docker and containers

Docker

The deployment page shows only the Pyramid-specific parts and links here for the rest.

Kubernetes

Kubernetes Reference

The deployment page links here for probes, rollouts and scaling.

Cloud deployment

Cloud

Managed container services described there can run a Pyramid image unchanged.

Database engines

SQL Reference, MongoDB Reference and Redis Reference

The data pages cover only how to wire each one into Pyramid (sessions, transactions, request methods).

Architecture

Architecture, Architectural Patterns and Starting a New Project: Which Path and Which Technologies

Background on layering patterns, and how to decide whether Pyramid is the right starting point.

Messaging and scheduling

Messaging Reference and Scheduling

Work that outgrows a request thread belongs in a queue or a scheduler described there.

Bibliography

Every source used to prepare this section is listed here, each linked to its official site. Individual pages list the subset they derive from under their own == References heading.

Pylons Project, add-ons and the Community Cookbook

Specifications and standards

The official documentation linked above is authoritative; where it and an older tutorial differ, the documentation of the version you run prevails.