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
Configuratorrecords what you register (routes, views, predicates, tweens, security policy). Pyramid detects conflicting registrations at startup and resolves them with a clear rule, which makesconfig.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/dunebecomes 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 thejsonrenderer and__json__ -
SQLAlchemy 2.0 with
pyramid_tmand Alembic (the cookiecuttersqlalchemybackend) and Jinja2 templates throughpyramid_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
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:
-
Foundations: what Pyramid is, a single-file application, a cookiecutter project run with
pserve, the configurator and the.inisettings. -
Routing and views: URL dispatch, traversal, view configuration and predicates, exception views, renderers, templates, the request and response, and static assets.
-
State, forms and security: sessions and flash messages, Deform and Colander forms, the 2.0 security policy, ACL-based authorization and CSRF protection.
-
Data: SQLAlchemy with
pyramid_tmand Alembic, then ZODB and other stores. -
Extending, tooling and testing: events, tweens and view derivers, add-ons, internationalization, the p-scripts, logging and the debug toolbar, and testing with
pyramid.testingand WebTest. -
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.
What’s covered
Where related material lives elsewhere on this site
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 |
The introduction compares Pyramid with each of them and says when each is the better fit. |
|
OAuth 2.0, OpenID Connect, JWT theory |
The security pages cover the Pyramid security policy and leave the protocol theory here. |
|
Cross-origin requests |
The CSRF page links here for browser cross-origin rules. |
|
Docker and containers |
The deployment page shows only the Pyramid-specific parts and links here for the rest. |
|
Kubernetes |
The deployment page links here for probes, rollouts and scaling. |
|
Cloud deployment |
Managed container services described there can run a Pyramid image unchanged. |
|
Database engines |
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 |
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.
Official Pyramid documentation
Published at docs.pylonsproject.org, grouped as the documentation is:
Pylons Project, add-ons and the Community Cookbook
-
Try Pyramid and its add-on catalogue
-
Pyramid Community Cookbook (the URL uses an underscore, unlike the hyphenated
pyramid-chameleon,pyramid-mako,pyramid-retryandpyramid-zodbconndocumentation URLs) -
plaster and PasteDeploy