Jinja2

3.1.6 · active · verified Sat Mar 28

Jinja2 is a fast, expressive, extensible templating engine for Python. Special placeholders in templates allow writing code similar to Python syntax, which is then rendered against passed data to produce a final document. It supports template inheritance, macros, autoescaping, sandboxed execution, async rendering, and i18n via Babel. Current stable version is 3.1.6 (a security patch release); the 3.1.x branch receives active bugfix and security updates with no fixed cadence.

Warnings

breaking jinja2.Markup and jinja2.escape were removed in 3.1.0. Any code doing `from jinja2 import Markup` or `from jinja2 import escape` raises ImportError.
Fix: Replace with `from markupsafe import Markup, escape`. MarkupSafe is always installed as a dependency.
breaking contextfunction, contextfilter, environmentfunction, environmentfilter, evalcontextfunction, and evalcontextfilter decorators were removed in 3.0. Importing them raises ImportError.
Fix: Use pass_context, pass_environment, and pass_eval_context from jinja2 instead.
breaking Python 2.7 and 3.5 support was dropped in 3.0; Python 3.6 support was dropped in 3.1.0. Running on these versions will fail.
Fix: Use Python 3.7+. Pin to Jinja2<3.0 only if you must support Python 2.7 (EOL).
gotcha autoescape defaults to False in Environment. Rendering HTML with user input without enabling autoescape exposes the app to XSS attacks. Bandit (B701) and CodeQL flag this as high severity.
Fix: Always pass `autoescape=select_autoescape(['html', 'htm', 'xml'])` or `autoescape=True` when creating an Environment for HTML output.
gotcha Wrapping user-supplied strings in Markup() bypasses autoescaping entirely and causes XSS. Markup() signals a string is already safe; passing untrusted input to it is a common mistake.
Fix: Only pass developer-controlled or sanitized (e.g. via bleach) content to Markup(). Never do Markup(user_input).
gotcha Server-Side Template Injection (SSTI): passing user-controlled strings as the template source (e.g. env.from_string(user_input) or render_template_string(request.args['tmpl'])) allows arbitrary code execution.
Fix: Never use user input as the template string. Use pre-defined file-based templates. For sandboxed user templates use jinja2.sandbox.SandboxedEnvironment, which still does not guarantee full isolation.
gotcha Macros imported from another file do not have access to the calling template's context variables by default. Accessing outer-scope variables inside imported macros silently returns Undefined.
Fix: Pass all required values as explicit macro arguments. Use `{% import 'macros.html' as macros with context %}` only if you intentionally need the full context available (performance and caching implications apply).

Install

pip install Jinja2 Latest stable
pip install "Jinja2>=3.1.6" Pin to secure minimum

Imports

Environment
```
from jinja2 import Environment
```
Central object; always instantiate with a Loader and explicit autoescape setting
FileSystemLoader
```
from jinja2 import FileSystemLoader
```
Loads templates from the filesystem by search path
PackageLoader
```
from jinja2 import PackageLoader
```
Loads templates from inside a Python package's directory; no longer requires setuptools as of 3.0
select_autoescape
```
from jinja2 import select_autoescape
```
Recommended helper for configuring autoescape per file extension; pass to Environment(autoescape=...)
Markup
```
from markupsafe import Markup
```
jinja2.Markup and jinja2.escape were removed in 3.1.0; import both from markupsafe directly
escape
```
from markupsafe import escape
```
jinja2.escape was removed in 3.1.0; use markupsafe.escape
pass_context / pass_environment / pass_eval_context
```
from jinja2 import pass_context
```
contextfunction, contextfilter, environmentfunction, environmentfilter, evalcontextfunction, evalcontextfilter were all removed in 3.0; use pass_context, pass_environment, pass_eval_context decorators instead
SandboxedEnvironment
```
from jinja2.sandbox import SandboxedEnvironment
```
Required when rendering untrusted templates; not imported from jinja2 top-level
UndefinedError
```
from jinja2 import UndefinedError
```
Raised when a variable is accessed that is not defined and StrictUndefined or DebugUndefined is used

Quickstart

Basic Environment setup and template rendering, demonstrating safe autoescape configuration for HTML and plain-text contexts.

from jinja2 import Environment, FileSystemLoader, select_autoescape

# Always set autoescape explicitly; default is False which is a security risk for HTML output
env = Environment(
    loader=FileSystemLoader("."),
    autoescape=select_autoescape(["html", "htm", "xml"]),
)

# Render from a string (autoescape=False for non-HTML plain text)
text_env = Environment()
template = text_env.from_string("Hello, {{ name }}! You have {{ count }} message(s).")
result = template.render(name="World", count=3)
print(result)
# -> Hello, World! You have 3 message(s).

# Render an HTML template string safely
html_env = Environment(autoescape=True)
html_tmpl = html_env.from_string("<p>Hello, {{ name }}!</p>")
print(html_tmpl.render(name="<script>alert(1)</script>"))
# -> <p>Hello, &lt;script&gt;alert(1)&lt;/script&gt;!</p>

view raw JSON →