4 This is the documentation for the Jinja2 general purpose templating language.
5 Jinja2 is a library for Python 2.4 and onwards that is designed to be flexible,
8 If you have any exposure to other text-based template languages, such as Smarty or
9 Django, you should feel right at home with Jinja2. It's both designer and
10 developer friendly by sticking to Python's principles and adding functionality
11 useful for templating environments.
13 The key-features are...
15 - ... **configurable syntax**. If you are generating LaTeX or other formats
16 with Jinja2 you can change the delimiters to something that integrates better
17 into the LaTeX markup.
19 - ... **fast**. While performance is not the primarily target of Jinja2 it's
20 surprisingly fast. The overhead compared to regular Python code was reduced
23 - ... **easy to debug**. Jinja2 integrates directly into the python traceback
24 system which allows you to debug Jinja2 templates with regular python
27 - ... **secure**. It's possible to evaluate untrusted template code if the
28 optional sandbox is enabled. This allows Jinja2 to be used as templating
29 language for applications where users may modify the template design.
35 Jinja2 needs at least **Python 2.4** to run. Additionally a working C-compiler
36 that can create python extensions should be installed for the debugger. If no
37 C-compiler is available and you are using Python 2.4 the `ctypes`_ module
40 If you don't have a working C-compiler and you are trying to install the source
41 release with the speedups you will get a compiler error. This however can be
42 circumvented by passing the ``--without-speedups`` command line argument to the
45 $ python setup.py --with-speedups install
47 (As of Jinja 2.2, the speedups are disabled by default and can be enabled
48 with ``--with-speedups``. See :ref:`enable-speedups`)
50 .. _ctypes: http://python.net/crew/theller/ctypes/
56 You have multiple ways to install Jinja2. If you are unsure what to do, go
57 with the Python egg or tarball.
59 As a Python egg (via easy_install)
60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62 You can install the most recent Jinja2 version using `easy_install`_ or `pip`_::
67 This will install a Jinja2 egg in your Python installation's site-packages
70 (If you are installing from the windows command line omit the `sudo` and make
71 sure to run the command as user with administrator rights)
73 From the tarball release
74 ~~~~~~~~~~~~~~~~~~~~~~~~~
76 1. Download the most recent tarball from the `download page`_
78 3. ``sudo python setup.py install``
80 Note that the last command will automatically download and install
81 `setuptools`_ if you don't already have it installed. This requires a working
84 This will install Jinja2 into your Python installation's site-packages directory.
86 Installing the development version
87 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
89 1. Install `mercurial`_
90 2. ``hg clone http://dev.pocoo.org/hg/jinja2-main jinja2``
92 4. ``ln -s jinja2 /usr/lib/python2.X/site-packages``
94 As an alternative to steps 4 you can also do ``python setup.py develop``
95 which will install the package via setuptools in development mode. This also
96 has the advantage that the C extensions are compiled.
98 Alternative you can use `easy_install`_ to install the current development
101 sudo easy_install Jinja2==dev
103 Or the new `pip`_ command::
105 sudo pip install Jinja2==dev
107 .. _download page: http://pypi.python.org/pypi/Jinja2
108 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
109 .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
110 .. _pip: http://pypi.python.org/pypi/pip
111 .. _mercurial: http://www.selenic.com/mercurial/
115 Enable the speedups Module
116 ~~~~~~~~~~~~~~~~~~~~~~~~~~
118 By default Jinja2 will not compile the speedups module. Enabling this
119 will fail if you don't have the Python headers or a working compiler. This
120 is often the case if you are installing Jinja2 from a windows machine.
122 You can enable the speedups extension when installing using the
123 ``--with-speedups`` flag::
125 sudo python setup.py --with-speedups install
132 This section gives you a brief introduction to the Python API for Jinja2
135 The most basic way to create a template and render it is through
136 :class:`~jinja2.Template`. This however is not the recommended way to
137 work with it if your templates are not loaded from strings but the file
138 system or another data source:
140 >>> from jinja2 import Template
141 >>> template = Template('Hello {{ name }}!')
142 >>> template.render(name='John Doe')
145 By creating an instance of :class:`~jinja2.Template` you get back a new template
146 object that provides a method called :meth:`~jinja2.Template.render` which when
147 called with a dict or keyword arguments expands the template. The dict
148 or keywords arguments passed to the template are the so-called "context"
151 What you can see here is that Jinja2 is using unicode internally and the
152 return value is an unicode string. So make sure that your application is
153 indeed using unicode internally.