Static Assets

An asset is any file inside a Python package that is not a Python source file: a stylesheet, an image, a template. Pyramid addresses assets with an asset specification, written package:path/inside/the/package, for example bookshelf_shelves:static/css/shelf.css. The part before the colon is a dotted package name, the part after it is a /-separated path relative to the package directory. Pyramid resolves it with the pkg_resources API (Pyramid 2.1 still imports it, which is why 2.1 needs a setuptools older than 82), which is also what makes assets overridable (see Overriding Assets) and what lets a package installed as a wheel or zip serve its own files.

There is a second, relative form without a package name (static/css/shelf.css). Pyramid APIs that accept it resolve it against a "current package" that each API documents: usually the package that contains the code making the call. Relative specifications are convenient in a single package and fragile in shared helper code, so this page uses full specifications everywhere. Where a Pyramid API takes a filesystem path, it generally also accepts an absolute path, with the caveats noted below.

The examples need a package to point at. In a real project the cookiecutter has already created static/ inside the application package (see Cookiecutter Projects & pserve). This first block creates a small equivalent in a temporary directory so that the rest of the page can be run unchanged: a stylesheet and its gzipped twin, a script, an index.html, a favicon and a second package that will play the role of a theme later.

Source: Pyramid: Static Assets

Configurator.add_static_view(name, path, **kw) registers a directory of files so that they are served below a URL prefix. name is the prefix (static serves /static/...) and path is the directory, as an asset specification or an absolute path. Everything under that directory is served recursively, the Content-Type comes from the file extension, and by default the files are reachable by anonymous users. Underneath, Pyramid does nothing exotic: it registers a route named __static/ (the name with a double underscore in front and a trailing slash) whose pattern is static/*subpath, and a view on that route whose callable is an instance of pyramid.static.static_view created with use_subpath=True. Because it is an ordinary route, it takes part in route ordering, shows up in proutes, accepts route_prefix from config.include and can be given any add_route keyword argument (such as factory) through the keyword arguments of add_static_view.

The block below serves the demo package and shows the pieces working together: a view that links to two assets, the files served with the right content type and no cache headers, the directory URL answered with index.html, and a missing file and a path-escape attempt both answered with 404.

Source: Pyramid: Configurator.add_static_view

A few behaviours follow from that implementation and are worth knowing before they surprise you.

You should never write /static/css/shelf.css by hand. request.static_url(spec, **kw) returns an absolute URL and request.static_path(spec, **kw) the same URL without scheme and host; both take the asset specification of the file and look up which static view or external base it belongs to. They accept the keyword arguments of route_url: _query, _anchor, _app_url, _scheme, _host and _port. The benefit is the one every URL-generation API offers: if you rename the prefix, move the view behind a route_prefix or switch to an external base URL, every generated link follows.

If no static view or external base matches the specification, static_url raises ValueError (No static URL definition matching ...), which is the usual symptom of a typo in the package name or of calling it for a file outside any registered directory. The functions pyramid.url.static_url(path, request) and static_path(path, request) are older spellings of the same API.

Source: Pyramid: Request.static_url

In a template the same call is available through the template engine’s helpers. With pyramid_jinja2 the package provides filters static_url_filter and static_path_filter in pyramid_jinja2.filters, but they are not active until you register them under names with the jinja2.filters setting. (The cookiecutter project skips the filters and calls {{ request.static_url('bookshelf_shelves:static/theme.css') }} in its layout template, which works in any engine.) The template below is written to the demo package and rendered through a view, so the HTML contains the URL, busted or not, that the registered static view produces. In Jinja the expression is written {{ 'shelves_demo:static/css/shelf.css'|static_url }}; with Chameleon or Mako you call request.static_url(...) directly, as the Getting Started page does for routes. The template engines themselves are the subject of the Templates page.

Source: pyramid_jinja2 documentation

Browsers cache what you tell them to cache, and Pyramid tells them nothing by default. add_static_view passes cache_max_age=None to the view it creates, so a response carries Last-Modified and Content-Length but no Cache-Control and no Expires. (The class pyramid.static.static_view, used directly, defaults to 3600 seconds. The two defaults differ, which is easy to forget when you move a view from one form to the other.) The browser then revalidates with If-Modified-Since on each use, which costs a round trip per file but never serves stale content.

Setting cache_max_age switches that to "trust the cache for this long". That is only safe when the URL changes whenever the content does, which is the whole point of the next section; a long cache_max_age on stable URLs means visitors see old stylesheets until their cache expires.

Source: Pyramid: pyramid.static.static_view

The combination that gives the best performance is a very long cache lifetime plus URLs that change when the file changes. Pyramid’s hook for that is config.add_cache_buster(path, cachebust, explicit=False): it registers an object implementing pyramid.interfaces.ICacheBuster, a callable (request, subpath, kw) that returns a possibly modified (subpath, kw), for every asset below path. From then on static_url and static_path run the buster before building the URL. Only URL generation is affected. The buster does not serve anything, so the files must still be reachable under the URL it produces. path is a directory (the trailing slash is added for you) and the longest matching registration wins.

Pyramid ships three implementations.

The constant buster and a per-file buster look like this. The second class reads the file through an AssetResolver and returns the first eight hex digits of its SHA-256; the token is cached because the file does not change while the process runs. Note the signature of tokenize: the installed source calls it with (request, subpath, kw), and the pathspec of the asset is in kw. (The git-hash example in the narrative chapter still shows an older tokenize(self, pathspec) form, which would fail with that call.)

Source: Pyramid: Cache Busting

Query-string busters are simple but have a well-known weakness: many caching proxies decline to cache a URL that has a query string. The narrative chapter therefore recommends changing a path segment when possible, which means renaming the file, which in turn means the file must exist under the new name. That is the job of a build tool (hash the content, write shelf.7f3a1c.css, record the mapping in a manifest), and of ManifestCacheBuster on the Pyramid side. The manifest is a flat JSON object from the source path to the hashed path. The example writes one, registers the buster and shows both the generated URL and that the hashed file is what must be served:

Source: Pyramid: Cache Busting

Three details of ManifestCacheBuster matter in practice. With the default reload=False the manifest is read immediately, so a missing file stops the application at startup (a crash at boot is better than links that silently lack their hashes). With reload=True the file is re-read when it changes and a missing file counts as an empty mapping; that is a development convenience and the class documentation advises against it in production. And because the format is whatever parse_manifest(content) returns, a subclass adapts other tools. Build tools such as Vite write a manifest whose values are objects rather than strings; a two-line override turns that into the flat mapping:

Source: Vite: Backend Integration

Cache busting only rewrites the URLs that Pyramid generates. References inside stylesheets and scripts (url(img/cover.png), dynamic import()) are invisible to it, because Pyramid knows nothing about their content. The narrative chapter’s advice is to let the asset pipeline rewrite those references into their final hashed form, so that the files stay truly static and can be hosted by Pyramid or by a CDN without changes; templating the CSS and calling static_url inside it works but makes your "static" files depend on the application.

To switch every buster off in development without editing the calls, set the pyramid.prevent_cachebust setting or the PYRAMID_PREVENT_CACHEBUST environment variable to a true value. The decision is made when the registrations are committed, so it applies to the whole process.

Source: Pyramid: Preventing Cache Busting

When name of add_static_view is a URL, Pyramid registers no route and no view. It only remembers the base URL, and static_url produces links beneath it. The files still have to be there (copied to a bucket, or served by another web server), and that server must be configured to answer the generated URLs; Pyramid does not check. The cache_max_age argument is ignored because Pyramid is not serving the files, so cache headers are the job of the CDN or server. Together with a cache buster the setup is typically "hashed names, long lifetime, CDN in front".

The narrative chapter suggests reading the base from a custom setting so that the same code serves from the application in development and from a CDN in production. Since the setting value is just a URL prefix, one line of the .ini file moves the assets:

Source: Pyramid: Generating Static Asset URLs

Compressing text assets on every request wastes CPU, and compressing them once at build time is free. Since Pyramid version 2.0, content_encodings=["gzip"] tells the static view that shelf.css.gz is the gzip form of shelf.css. When the client’s Accept-Encoding includes an encoding for which a sibling file exists, the view serves the smallest acceptable file and sets Content-Encoding accordingly; if the sibling is missing or the client does not accept the encoding, the plain file is sent. When any alternative exists the response also gets Vary: Accept-Encoding, which caches need to keep the two forms apart. The file extensions are looked up in mimetypes.encodings_map: .gz, .Z, .bz2, .xz and .br are present on Python 3.13, so content_encodings=["br"] works with .br files; if an encoding you need is missing, add it to the dictionary before configuring the view.

WebTest’s TestApp decodes a gzipped body and drops the Content-Encoding header before your assertion sees it, so this particular test uses WebOb’s Request.get_response against the WSGI app instead.

Source: Pyramid: Serving Pre-compressed Assets

By default a static view is open to everyone, even in an application that sets a default permission. Passing permission to add_static_view requires that permission for every file in the directory; the check is made by the application’s security policy against the default root factory’s ACL (or against the factory you pass through the keyword arguments, since they go to add_route). The security machinery is the subject of the security pages of this section; the example uses the smallest possible policy, with a request header standing in for authentication, which is only acceptable in a test:

Source: Pyramid: Serving Static Assets

A permission on a directory is the simple case. When the rule depends on the individual file (a book’s cover that only its owner may see, an uploaded manuscript), do not put the files in a static directory at all: write a view callable that checks the rule and returns a pyramid.response.FileResponse. User uploads in particular should live outside the package and be served by such a view, never by a public static view, and never under a URL that lets the user choose the file name or content type.

add_static_view cannot serve one file, and it cannot serve a directory at the root of the site. Both are done with plain views, and pyramid.static.static_view is the same helper that add_static_view uses, available for direct use. The favicon is the classic single file: a view returns a FileResponse, which sets the length and the content type from the file extension and serves the file as fast as the server allows. A catch-all static view at the root is a static_view instance with use_subpath=True registered on a route /*subpath that comes last in the routing table, because it matches everything.

Source: Pyramid: Advanced: Serving Static Assets Using a View Callable

Two caveats from the chapter. static_url cannot generate URLs for files served this way, because it only knows the directories registered with add_static_view. And the root-relative form does not work in an application that uses traversal: the route matches before traversal starts and would swallow every view without a route_name; there the static_view has to be registered as the Not Found view instead.

config.override_asset(to_override, override_with) lets one package replace assets of another without forking it. It works for single files, for directories (both specifications must end in a slash) and for the static views built on those packages. This is how a deployment replaces a logo or a stylesheet in a reusable application, and how themes stack: several calls naming the same to_override form a search path in which the first existing file wins and the original is the fallback. The specification may omit the colon and path to redirect a whole package, may start with a dot to be relative to the configuring package, and may be an absolute filesystem path, which is the supported way to serve files that live outside any package. A static view or static_url then keeps working on the original specification.

Source: Pyramid: Overriding Assets

Two interactions with cache busting are worth knowing. An asset-aware buster such as ManifestCacheBuster has a manifest for the original assets only, so an overridden file would receive the token of the file it replaced. The remedy is add_cache_buster(path, buster, explicit=True) with a second buster for the override package, matched against the raw specification (rawspec, the location of the file actually served) instead of the virtual one. And Pyramid 2.1 changed the lookup for stacked overrides: the cache buster now finds the first file that exists in the override stack, instead of the first override regardless of whether it has the file.

Pyramid’s static view is a good development server and a bad CDN. In production the standard arrangement is that a reverse proxy (nginx, Apache) or a CDN serves the files straight from disk or object storage and forwards only dynamic requests to the Waitress, Gunicorn or mod_wsgi workers. Because the URLs come from static_url, this is a configuration change and not a code change: either keep name='static' and let the proxy answer /static/ before the request reaches the application, or switch name to the CDN URL as in the previous section. Pair it with a cache buster and a long lifetime. The proxy needs the files on its own disk, so the build or the container image must put them there (the same hashed names as the manifest says).

Source: nginx: alias and nginx: ngx_http_gzip_static_module

The gzip_static directive belongs to an optional nginx module that must be compiled in; it mirrors what content_encodings does in Pyramid, using the same .gz siblings. Deployment as a whole (Waitress, Gunicorn, mod_wsgi, proxies and containers) belongs to the deployment page of this section, and the equivalent decisions in other frameworks are described in Flask: Static Files & Assets, Tornado: Static Files and FastAPI: Static Files, Templates & Frontend.

The directory traversal protection of static_view (the %2e%2e request in the first example returns 404) is part of Pyramid, but treat it as a last line of defence: do not feed user input into path or into a FileResponse filename in your own views, and keep static directories free of anything you would not publish.

Pyramid’s distinguishing choices are the asset specification (files addressed by package, so they can be overridden and installed as part of a wheel) and the explicit cache-buster interface. Tornado’s built-in hash and Django’s manifest storage give you busting without a decision; Pyramid asks you to choose and in exchange lets you plug in your own pipeline.