Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

570 lines (369 sloc) 15.762 kb



:term:`pyramid_jinja2` is a set of bindings that make templates written for the :term:`Jinja2` templating system work under the :term:`Pyramid` web framework.


Install using setuptools, e.g. (within a virtualenv):

$ $myvenv/bin/easy_install pyramid_jinja2



If you start a project from scratch, consider using the :ref:`project template <jinja2_starter_template>` which comes with a working setup and sensible defaults.

There are multiple ways to make sure that pyramid_jinja2 is active. All are completely equivalent:

  1. Use the :py:func:`~pyramid_jinja2.includeme` function via :py:meth:`~pyramid.config.Configurator.include`:

    config = Configurator()
  2. Add pyramid_jinja2 to the list of your pyramid.includes in your :file:`.ini` settings file:

    pyramid.includes =
  3. If you're using pyramid_zcml instead of imperative configuration, ensure that some ZCML file with an analogue of the following contents is executed by your Pyramid application:

    <include package="pyramid_jinja2"/>

Once activated either of these says, the following happens:

  1. Files with the :file:`.jinja2` extension are considered to be :term:`Jinja2` templates.
  2. The :func:`pyramid_jinja2.add_jinja2_search_path` directive is added to the :term:`Configurator` instance.
  3. The :func:`pyramid_jinja2.add_jinja2_extension` directive is added to the :term:`Configurator` instance.
  4. The :func:`pyramid_jinja2.get_jinja2_environment` directive is added to the :term:`Configurator` instance.
  5. :py:class:`jinja2.Environment` is constructed and registered globally.

To setup the Jinja2 search path either one of the following steps must be taken:

  1. Add :ref:`setting_jinja2_directories` to your :file:`.ini` settings file using the pyramid asset spec:

    jinja2.directories = yourapp:templates
  2. Or Alternatively by using the :func:`~pyramid_jinja2.add_jinja2_search_path` directive attached to your application's :term:`Configurator` instance also using the pyramid asset spec:



If you do not explicitly configure your Jinja2 search path it will default to the root of your application. If the specified template is not found in the root of your application and you did not specify a package on the template path it will then try to load the template path relative to the module's caller package. For example:

Without the search path configured:


With the search path configured:


If you view module is in app.module.view and your template is under :file:`app/module/templates/mytemplate.jinja2` you can access that asset in a few different ways.

Using the full path:


Using the package:


Using the relative path to current package:


You need to be careful when using relative paths though, if there is an :file:`app/templates/mytemplate.jinja2` this will be used instead as Jinja2 lookup will first try the path relative to the root of the app and then it will try the path relative to the current package.

Finally, to make sure your :file:`.jinja2` template files are included in your package's source distribution (e.g. when using python sdist), add *.jinja2 to your :file:``:

recursive-include yourapp *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.jinja2 *.js *.html *.xml


Once :term:`pyramid_jinja2` been activated :file:`.jinja2` templates can be loaded either by looking up names that would be found on the :term:`Jinja2` search path or by looking up asset specifications.

Template Lookups

The default lookup mechanism for templates uses the :term:`Jinja2` search path (specified with :ref:`setting_jinja2_directories` or by using the :func:`~pyramid_jinja2.add_jinja2_search_path` directive on the :term:`Configurator` instance).

Rendering :term:`Jinja2` templates with a view like this is typically done as follows (where the :file:`templates` directory is expected to live in the search path):

Rendering templates outside of a view (and without a request) can be done using the renderer api:

:term:`Template Inheritance`

:term:`Template inheritance` can use asset specs in the same manner as regular template lookups. An example:

For further information on :term:`Template Inheritance` in Jinja2 templates please see :ref:`Template Inheritance <jinja2:template-inheritance>` in Jinja2 documentation.

Asset Specification Lookups

Looking up templates via asset specification is a feature specific to :term:`Pyramid`. For further info please see :ref:`Understanding Asset Specifications <pyramid:asset_specifications>`. Overriding templates in this style uses the standard :ref:`pyramid asset overriding technique <pyramid:overriding_assets_section>`.

Internalization (i18n)

When :term:`pyramid_jinja2` is included as pyramid application, :ref:`jinja2.ext.i18n <jinja2:i18n-extension>` is automatically activated.

Be sure to configure jinja2.i18n.domain according to setup.cfg domain settings. By default, jinja2.i18n.domain is set to the package name of the pyramid application.


:term:`Jinja2` derives additional settings to configure its template renderer. Many of these settings are optional and only need to be set if they should be different from the default. The below values can be present in the :file:`.ini` file used to configure the Pyramid application (in the app section representing your Pyramid app) or they can be passed directly within the settings argument passed to a Pyramid Configurator.

Generic Settings

These setttings correspond to the ones documented in Jinja2. Set them accordingly.

For reference please see:


For the boolean settings please use true or false














Jinja2 autoescape setting.

Possible values: true or false.


By default Jinja2 sets autoescaping to False.

pyramid_jinja2 sets it to true as it is considered a good security practice.


This is a Pyramid setting (not a pyramid_jinja2 one)

For usage see :ref:`Pyramid: Automatically Reloading Templates <pyramid:reload_templates_section>`.

true or false representing whether Jinja2 templates should be reloaded when they change on disk. Useful for development to be true. This setting sets to Jinja2 auto_reload setting.

The rationale for using is a differently named setting is: this setting existed when Pyramid only supported Chameleon and Mako templates and acts uniformly across the template renderers.



Deprecated as of version 1.5, use :ref:`setting_reload_templates` instead


Use Pyramid :ref:`setting_reload_templates` setting.


A list of directory names or a newline-delimited string with each line representing a directory name. These locations are where Jinja2 will search for templates. Each can optionally be an absolute resource specification (e.g. package:subdirectory/).


The input encoding of templates. Defaults to utf-8.


Changes the undefined types that are used when a variable name lookup fails. If unset, defaults to :py:class:`~jinja2.Undefined` (silent ignore). Setting it to strict will trigger :py:class:`~jinja2.StrictUndefined` behavior (raising an error, this is recommended for development). Setting it to debug will trigger :py:class:`~jinja2.DebugUndefined`, which outputs debug information in some cases. See Undefined Types


A list of extension objects or a newline-delimited set of dotted import locations where each line represents an extension. :ref:`jinja2.ext.i18n <jinja2:i18n-extension>` is automatically activated.


Pyramid domain for translations. See :term:`Translation Domain` in Pyramid documentation. Defaults to the package name of the pyramid application.


A dictionary mapping filter name to filter object, or a newline-delimted string with each line in the format:

name =

representing :ref:`Jinja2 filters <jinja2:writing-filters>`.


A dictionary mapping global name to global template object, or a newline-delimited string with each line in the format:

name =

representing :ref:`Jinja2 globals <jinja2:global-namespace>`


A dictionary mapping test name to test object, or a newline-delimted string with each line in the format:

name =

representing :ref:`Jinja2 tests <jinja2:writing-tests>`.


If set to true, a filesystem bytecode cache will be configured (in a directory determined by :ref:`setting_jinja2_byte_cache_dir`.) To configure other types of bytecode caching, jinja2.bytecode_caching may also be set directly to an instance of :class:`jinja2.BytecodeCache` (This can not be done in a paste .ini file, however, it must be done programatically.) By default, no bytecode cache is configured.

Note that configuring a filesystem bytecode cache will (not surprisiningly) generate files in the cache directory. As templates are changed, some of these will become stale, pointless wastes of disk space. You are advised to consider a clean up strategy (such as a cron job) to check for and remove such files.

See the :ref:`Jinja2 Documentation <jinja2:bytecode-cache>` for more information on bytecode caching.


Absolute path to directory to store bytecode cache files. Defaults to the system temporary directory. This is only used if jinja2.bytecode_caching is set to true.


true or false to enable the use of newstyle gettext calls. Defaults to false.

See Newstyle Gettext

Jinja2 Filters

pyramid_jinja2 provides following filters.

To use these filters, configure the settings of jinja2.filters:

And use the filters in template.

<a href="{{context|model_url('edit')}}">Edit</a>

<a href="{{'top'|route_url}}">Top</a>

<link rel="stylesheet" href="{{'yourapp:static/css/style.css'|static_url}}" />

Creating a Jinja2 Pyramid Project

After you've got pyramid_jinja2 installed, you can invoke one of the following commands to create a Jinja2-based Pyramid project.

On Pyramid 1.0, 1.1, or 1.2:

$ $myvenv/bin/paster create -t pyramid_jinja2_starter myproject

On Pyramid 1.3:

$ $myenv/bin/pcreate -s pyramid_jinja2_starter myproject

After it's created, you can visit the myproject directory and run develop. At that point you can start the application like any other Pyramid application.

This is a good way to see a working Pyramid application that uses Jinja2, even if you wind up not using the result.

Paster Template I18N

The paster template automatically sets up pot/po/mo locale files for use with the generated project.

The usual pattern for working with i18n in pyramid_jinja2 is as follows:

More Information

Reporting Bugs / Development Versions

Visit to download development or tagged versions.

Visit to report bugs.

Indices and tables

Jump to Line
Something went wrong with that request. Please try again.