Frequently Asked Questions

This page answers some of the often asked questions about Jinja.

Why is it called Jinja?

The name Jinja was chosen because it’s the name of a Japanese temple andtemple and template share a similar pronunciation. It is not named afterthe city in Uganda.

How fast is it?

We really hate benchmarks especially since they don’t reflect much. Theperformance of a template depends on many factors and you would have tobenchmark different engines in different situations. The benchmarks from thetestsuite show that Jinja2 has a similar performance to Mako and is between10 and 20 times faster than Django’s template engine or Genshi. These numbersshould be taken with tons of salt as the benchmarks that took these numbersonly test a few performance related situations such as looping. Generallyspeaking the performance of a template engine doesn’t matter much as theusual bottleneck in a web application is either the database or the applicationcode.

How Compatible is Jinja2 with Django?

The default syntax of Jinja2 matches Django syntax in many ways. Howeverthis similarity doesn’t mean that you can use a Django template unmodifiedin Jinja2. For example filter arguments use a function call syntax ratherthan a colon to separate filter name and arguments. Additionally theextension interface in Jinja is fundamentally different from the Django onewhich means that your custom tags won’t work any longer.

Generally speaking you will use much less custom extensions as the Jinjatemplate system allows you to use a certain subset of Python expressionswhich can replace most Django extensions. For example instead of usingsomething like this:

{% load comments %}
{% get_latest_comments 10 as latest_comments %}
{% for comment in latest_comments %}
    ...
{% endfor %}

You will most likely provide an object with attributes to retrievecomments from the database:

{% for comment in models.comments.latest(10) %}
    ...
{% endfor %}

Or directly provide the model for quick testing:

{% for comment in Comment.objects.order_by('-pub_date')[:10] %}
    ...
{% endfor %}

Please keep in mind that even though you may put such things into templatesit still isn’t a good idea. Queries should go into the view code and notthe template!

Isn’t it a terrible idea to put Logic into Templates?

Without a doubt you should try to remove as much logic from templates aspossible. But templates without any logic mean that you have to do allthe processing in the code which is boring and stupid. A template enginethat does that is shipped with Python and called string.Template. Comeswithout loops and if conditions and is by far the fastest template engineyou can get for Python.

So some amount of logic is required in templates to keep everyone happy.And Jinja leaves it pretty much to you how much logic you want to put intotemplates. There are some restrictions in what you can do and what not.

Jinja2 neither allows you to put arbitrary Python code into templates nordoes it allow all Python expressions. The operators are limited to themost common ones and more advanced expressions such as list comprehensionsand generator expressions are not supported. This keeps the template engineeasier to maintain and templates more readable.

Why is Autoescaping not the Default?

There are multiple reasons why automatic escaping is not the default modeand also not the recommended one. While automatic escaping of variablesmeans that you will less likely have an XSS problem it also causes a hugeamount of extra processing in the template engine which can cause seriousperformance problems. As Python doesn’t provide a way to mark strings asunsafe Jinja has to hack around that limitation by providing a customstring class (the Markup string) that safely interacts with safeand unsafe strings.

With explicit escaping however the template engine doesn’t have to performany safety checks on variables. Also a human knows not to escape integersor strings that may never contain characters one has to escape or alreadyHTML markup. For example when iterating over a list over a table ofintegers and floats for a table of statistics the template designer canomit the escaping because he knows that integers or floats don’t containany unsafe parameters.

Additionally Jinja2 is a general purpose template engine and not only usedfor HTML/XML generation. For example you may generate LaTeX, emails,CSS, JavaScript, or configuration files.

Why is the Context immutable?

When writing a contextfunction() or something similar you may havenoticed that the context tries to stop you from modifying it. If you havemanaged to modify the context by using an internal context API you mayhave noticed that changes in the context don’t seem to be visible in thetemplate. The reason for this is that Jinja uses the context only asprimary data source for template variables for performance reasons.

If you want to modify the context write a function that returns a variableinstead that one can assign to a variable by using set:

{% set comments = get_latest_comments() %}

My tracebacks look weird. What’s happening?

If the debugsupport module is not compiled and you are using a Pythoninstallation without ctypes (Python 2.4 without ctypes, Jython or Google’sAppEngine) Jinja2 is unable to provide correct debugging information andthe traceback may be incomplete. There is currently no good workaroundfor Jython or the AppEngine as ctypes is unavailable there and it’s notpossible to use the debugsupport extension.

If you are working in the Google AppEngine development server you canwhitelist the ctypes module to restore the tracebacks. This however won’twork in production environments:

import os
if os.environ.get('SERVER_SOFTWARE', '').startswith('Dev'):
    from google.appengine.tools.devappserver2.python import sandbox
    sandbox._WHITE_LIST_C_MODULES += ['_ctypes', 'gestalt']

Credit for this snippet goes to Thomas Johansson

Why is there no Python 2.3/2.4/2.5/3.1/3.2 support?

Python 2.3 is missing a lot of features that are used heavily in Jinja2. Thisdecision was made as with the upcoming Python 2.6 and 3.0 versions it becomesharder to maintain the code for older Python versions. If you really needPython 2.3 support you either have to use Jinja 1 or other templatingengines that still support 2.3.

Python 2.4/2.5/3.1/3.2 support was removed when we switched to supportingPython 2 and 3 by the same sourcecode (without using 2to3). It was required todrop support because only Python 2.6/2.7 and >=3.3 support byte and unicodeliterals in a way compatible to each other version. If you really need supportfor older Python 2 (or 3) versions, you can just use Jinja2 2.6.

My Macros are overridden by something

In some situations the Jinja scoping appears arbitrary:

layout.tmpl:

{% macro foo() %}LAYOUT{% endmacro %}
{% block body %}{% endblock %}

child.tmpl:

{% extends 'layout.tmpl' %}
{% macro foo() %}CHILD{% endmacro %}
{% block body %}{{ foo() }}{% endblock %}

This will print LAYOUT in Jinja2. This is a side effect of havingthe parent template evaluated after the child one. This allows childtemplates passing information to the parent template. To avoid thisissue rename the macro or variable in the parent template to have anuncommon prefix.