django-rust-templates

A drop-in replacement for Django's template engine, written in Rust.

It re-implements the Django template language natively: the lexer, parser, node tree, renderer, and the built-in tags and filters. It produces byte-identical output to stock Django and passes 100% of Django's own template test suite on Django 5.2 and 6.1. On the benchmark below it renders ~15× faster and compiles templates ~12× faster than stock Django.

TEMPLATES = [
    {
        "BACKEND": "django_rust_templates.RustTemplates",  # was django.template.backends.django.DjangoTemplates
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {"context_processors": [...]},  # same options as DjangoTemplates
    },
]

Status: early (0.1). Correctness is gated on Django's own test suite, but the project hasn't had wide production use yet.

Contents

• Installation
• Usage
• Compatibility
• Performance
• Testing
• How it works
• Development
• License

Installation

pip install django-rust-templates

Prebuilt wheels are published for CPython 3.12, 3.13 and 3.14 on Linux x86_64 and aarch64 (manylinux glibc ≥ 2.28 and musllinux). It requires Django ≥ 5.2.

Building from source

On other platforms pip falls back to the source distribution, or you can build from git. Either way you need a Rust toolchain (rustup; the pinned version in rust-toolchain.toml is installed automatically) and Python ≥ 3.12.

pip install git+https://github.com/MasonLyons/rust-django-template-engine.git

Or from a checkout:

git clone https://github.com/MasonLyons/rust-django-template-engine.git
cd rust-django-template-engine
pip install .

Usage

As a Django backend

Swap the BACKEND in TEMPLATES (see above). RustTemplates accepts the same DIRS, APP_DIRS and OPTIONS as DjangoTemplates: context_processors, debug, loaders, string_if_invalid, file_charset, libraries, builtins and autoescape. render(), render_to_string(), template loaders, {% load %} and your custom tag libraries work unchanged.

Forms

Django renders forms and widgets ({{ form }}, {{ field }}, form.as_div) through FORM_RENDERER, whose default builds its own stock template engine, so form HTML doesn't touch TEMPLATES at all. To render it natively too:

FORM_RENDERER = "django_rust_templates.forms.RustFormRenderer"

It loads the same built-in form templates as Django's default DjangoTemplates renderer (and each app's templates directory), so output is identical. Rendering an 8-field form is about 2.6× faster; the rest of the time is Django's own form and widget code.

Standalone

Engine mirrors django.template.Engine (Django settings must be configured, as with the stock engine):

from django.template import Context
from django_rust_templates import Engine

engine = Engine(dirs=["templates"], libraries={"mytags": "myapp.templatetags.mytags"})
template = engine.from_string("Hello {{ user.name|title }}!")
template.render(Context({"user": {"name": "ada lovelace"}}))  # 'Hello Ada Lovelace!'

Compatibility

• Output parity. Rendered output, error types and error messages (including line numbers and the Django 6.1 Template: name, prefix) match stock Django exactly. Any difference is a bug, so please open an issue.
• Built-in tags and filters run natively, including extends/block, include, for, if, with, cycle, url, csrf_token, Django 6.1 partialdef/partial, {% translate "literal" %}, {% blocktranslate %}, {% static %}, and filters such as date, floatformat, urlize, join and striptags, plus humanize's intcomma on integers and naturaltime.
• Custom and third-party tag libraries keep working. simple_tag and inclusion_tag run on native helper nodes. Other tags (custom compile functions, simple_block_tag) are bridged to their Python implementation, so their own code runs at Python speed while the rest of the template stays native. When a bridged block tag (e.g. {% localtime %}, {% cache %}, simple_block_tag) calls parser.parse(), its body compiles on the Rust parser and renders natively.
• The Python node API (template.nodelist, get_nodes_by_type, render_annotated) is exposed through stock-compatible adapter nodes, so tooling that inspects compiled templates keeps working.

Performance

Microseconds per operation; lower is better. × is the speedup over stock Django.

Linux x86_64 (AMD EPYC 7601), Python 3.13.15, Django 6.1.2, release build.

Methodology. benchmarks/bench.py first renders every scenario on both engines and aborts unless the output is byte-identical, because a speedup on wrong output is worthless. It then times each engine in its own subprocess (so neither inherits the other's allocator or GC state), pinned to one CPU core, and reports the minimum of 7 timeit repeats. "Compile" is one template parse. In cached_extends and realistic_page (cached loader) it is a cache-hit get_template(), the per-request cost in production.

Reading the numbers.

• realistic_page is the closest to a real view: {% extends %} with block.super, an {% include %} per row, model-like objects with attributes, methods and properties, and the date, floatformat, urlize and join filters, all through the cached loader.
• The weakest rows are simple_var (4.5×, dominated by fixed per-render overhead) and inclusion_tag (6.9×: the tag function is Python, and each call builds a fresh Context for the included template).
• This measures template time only. A view's database queries and middleware are unaffected, so whole-request gains depend on how much of each request is spent rendering.
• benchmarks/realworld.py renders a full page through the backend with a request: context processors, {% static %}, {% url %}, i18n tags, messages, a form and humanize filters. Python code that the page calls (context processors, form and widget classes, translation catalog lookups, bridged tags) runs at the same speed on both engines, so this page is about 3.5× faster rather than 14×.

HTML escaping and the lexer's tag scanner use portable SIMD: fearless_simd picks SSE2 on x86_64 and NEON on aarch64, and memchr picks the best instruction set at runtime.

Compared with Jinja2

Django also ships a Jinja2 backend, and Jinja2 is the usual choice when DTL is too slow. benchmarks/jinja2_bench.py runs the same scenarios through all three engines. Each scenario has a hand-written Jinja2 template that does the same work in idiomatic Jinja2 (loop.cycle, super(), p.full()), and the script aborts unless all three outputs match byte for byte. The one exception is how the entities are spelled: markupsafe writes ' where Django writes '.

Same machine as above; Jinja2 3.1.6. Over the same rows, Jinja2 renders 3.45× faster than stock Django and this engine renders 16.00× faster.

• Compile. Jinja2 compiles every template to Python bytecode. A fresh parse takes about 9× longer than stock Django and 153× longer than this engine (geomean). A cache-hit get_template() is 2.6× faster here than in Jinja2.
• Where Jinja2 keeps up. if_branch (0.98×) is a loop of integer comparisons. Jinja2 turns n > 90 into a Python > on the raw value, which is as fast as the native comparison here. Rows made of plain loops and lookups (nested_table, index_none_lookup, with_if_scopes) are also close to even.
• Where it doesn't. Jinja2 has no date, floatformat, urlize, intcomma or Django-style truncatewords. Django projects register Django's own filter functions in Jinja2 (as django-jinja does), and the benchmark does too, so those rows run Python code at stock speed. Here they are native, which is why realistic_page, urlize, date_filter and aware_dates are 9–35× faster than Jinja2.
• Setup. autoescape=True, ChainableUndefined (missing lookups render as empty, as in DTL), auto_reload=False, and the i18n extension wired to Django's gettext. Because Jinja2 always caches compiled templates, the Django engines use the cached loader in every loader-based row, so the stock include and extends rows are not comparable with the table above.
• Skipped. spaceless_table, inclusion_tag and value_types are left out. Jinja2 has no spaceless and no inclusion tags, and it prints str(value) where DTL localizes dates and numbers.

Run the benchmarks yourself:

maturin develop --release
python benchmarks/bench.py                   # full table
python benchmarks/bench.py --only realistic  # filter scenarios
python benchmarks/realworld.py               # end-to-end page via the backend
python benchmarks/jinja2_bench.py            # stock vs Jinja2 vs Rust (pip install jinja2)
cargo bench --bench compile_bench            # Rust-only lexer micro-benchmarks

The CI workflow can also be run by hand (Actions → CI → Run workflow). It then runs the benchmark on both x86_64 and arm64 runners and uploads the tables as artifacts. Shared CI runners are noisy, so treat those numbers as indicative only.

Testing

Correctness is checked at three levels, all run in CI on both Django versions and both CPU architectures.

1. Django's own template test suite. The real template_tests and template_loader suites from Django's repository run with the engine swapped in (about 5,900 renders per run). A small patch to Django's runtests.py replaces Engine, Template and the DjangoTemplates backend; see scripts/. Results: 100% on 5.2 and 6.1.

   python scripts/run_django_test_suite.py --branch stable/6.1.x
   python scripts/run_django_test_suite.py --branch stable/5.2.x
   

   The script shallow-clones the matching Django branch into .django-cache/ on first run. scripts/known_failures-*.txt lists accepted failures; at the moment it holds only one, which depends on the environment and fails only when run as root.
2. Parity tests. pytest renders every case through stock Django and the Rust engine and asserts identical output or identical errors. Cases cover tags, filters, escaping edge cases at SIMD block boundaries and in UTF-8, lexer edge cases, loaders, inheritance, partials, custom tag libraries, the Python nodelist API and the backend. It also includes a Hypothesis differential fuzzer that generates random nested templates and contexts.

   pytest
   DTL_FUZZ_ITERS=20000 pytest tests/test_fuzz.py  # longer fuzz run
   

3. Rust unit tests for the lexer, the variable/filter parser and the SIMD routines, checked against reference implementations:

   cargo test --release
   

With Docker

Every service rebuilds the extension from your working tree before it runs:

make test      # pytest on Django 5.2 and 6.1
make suite     # Django's own template suite on 5.2 and 6.1
make fuzz      # long fuzz run (DTL_FUZZ_ITERS=20000 make fuzz)
make bench     # release-build benchmarks

How it works

template source ──► lexer ──► parser ──► Rust node tree ──► renderer ──► str
   (src/lexer.rs)   (SIMD tag scan)  (src/parser.rs,      (src/render/)
                                      src/tags/, src/filters/)

• Lexer (src/lexer.rs): an exact port of Django's tag_re splitting and verbatim handling, scanning for tags with memchr.
• Parser (src/parser.rs, src/tags/, src/varparse.rs): builds a native node tree. Variables and filter expressions are parsed once, with lookup keys interned.
• Renderer (src/render/): walks the tree against a Rust context stack that mirrors Context's layering. Python values are resolved through PyO3, using type-slot checks and exception-free misses on hot paths. Strings and integers take native fast paths, and dates, decimals and lazy objects go through native ports of Django's localisation and escaping.
• Bridge (src/bridge.rs): tags without a native implementation are compiled by their Python compile function against a token stream that mirrors stock Django's, then rendered as Python nodes inside the native tree.
• Python layer (python/django_rust_templates/): the RustTemplates backend, stock-compatible adapter nodes for template.nodelist, and traceback-depth shims so error reporting matches stock Django.

Development

python -m venv .venv && . .venv/bin/activate
pip install maturin pytest hypothesis "Django==6.1.*"
maturin develop            # debug build; use --release before benchmarking
pytest && cargo test

src/               Rust engine (lexer, parser, tags, filters, renderer, bridge)
python/            Python package: backend, adapter nodes, exceptions
tests/             pytest parity suite + Hypothesis fuzzer
scripts/           Django test-suite runner, runtests.py patches, known failures
benchmarks/        bench.py (engine vs stock Django), jinja2_bench.py, realworld.py
benches/           criterion micro-benchmarks
docker/            development image used by docker-compose.yml / Makefile

See CONTRIBUTING.md for guidelines.

License

BSD-3-Clause, the same license as Django. See LICENSE. Large parts of this project are ports of Django's template engine; Django is © the Django Software Foundation and individual contributors.