minijinja 3.0.0

[!IMPORTANT] The main branch contains development for MiniJinja 3. MiniJinja 2 maintenance and releases continue on the minijinja-2 branch. Pull requests for changes that apply to MiniJinja 2 should target that branch. Changes are merged forward from minijinja-2 into main, never in the other direction.

MiniJinja is a powerful but minimal dependency template engine which is based on the syntax and behavior of the Jinja2 template engine for Python.

It's implemented in Rust and Go and is also available via WASM for JavaScript, as a Python extension module, and as a command line utility.

It supports a range of features from Jinja2 including inheritance, filters and more. The goal is that it should be possible to use some templates in Rust programs without the fear of pulling in complex dependencies for a small problem. Additionally it tries not to re-invent something but stay in line with prior art to leverage an already existing ecosystem of editor integrations. The default build of MiniJinja is entirely free of dependencies, though some users might want to enable the serde dependency to enable the optional serde support.

$ cargo tree
minimal v0.1.0 (examples/minimal)
└── minijinja v3.0.0 (minijinja)

Additionally minijinja is also available as an (optionally pre-compiled) command line executable called minijinja-cli:

$ curl -sSfL https://github.com/mitsuhiko/minijinja/releases/latest/download/minijinja-cli-installer.sh | sh
$ echo "Hello {{ name }}" | minijinja-cli - -Dname=World
Hello World

You can play with MiniJinja online in the browser playground powered by a WASM build of MiniJinja.

Goals:

Well documented, compact API
Minimal dependencies, reasonable compile times and decent runtime performance
Stay as close as possible to Jinja2
Support for expression evaluation which allows the use as a DSL
Optional support for all serde compatible types through the serde feature
Well tested
Support for dynamic runtime objects with methods and dynamic attributes
Descriptive errors
Bindings for JavaScript, Python, and C
Also available for Go
Comes with a handy CLI
Compiles to WebAssembly

Example

Example Template:

{% extends "layout.html" %}
{% block body %}
  <p>Hello {{ name }}!</p>
{% endblock %}

Invoking from Rust:

use minijinja::{Environment, context};

fn main() {
    let mut env = Environment::new();
    env.add_template("hello.txt", "Hello {{ name }}!").unwrap();
    let template = env.get_template("hello.txt").unwrap();
    println!("{}", template.render(context! { name => "World" }).unwrap());
}

Getting Help

If you are stuck with MiniJinja, have suggestions or need help, you can use the GitHub Discussions.

Related Crates

minijinja-embed: provides utilities for embedding templates in a binary
minijinja-contrib: provides additional utilities too specific for the core
minijinja-py: makes MiniJinja available to Python
minijinja-js: makes MiniJinja available to JavaScript via WASM (for Node and Browser)
minijinja-go: a native Go implementation of MiniJinja
minijinja-cli: a command line utility.
minijinja-cabi: a C binding to MiniJinja.

Use Cases and Users

Here are some interesting Open Source users and use cases of MiniJinja. The examples link directly to where the engine is used so you can see how it's utilized:

AI and LLM Inference:
- NVIDIA Dynamo uses it to render LLM chat templates in its distributed inference serving framework
- Hugging Face Candle uses it to render LLM chat templates, including in the browser via WASM
- mistral.rs uses it to render LLM chat templates
- Shepherd Model Gateway uses it to render LLM chat templates in its LLM gateway
- LoRAX uses it to render LLM chat templates
- BoundaryML's BAML uses it to render LLM prompts
- Worktrunk uses it to render prompts for LLM generated commit messages
Data and Processing:
- dbt builds the Jinja support of its Rust rewrite (dbt v2.0 / Fusion engine) on a fork of MiniJinja
- Cube uses it for data modelling
- PRQL uses it to handle DBT style pipelines
- qsv uses it to render templates from CSV files, to construct payloads to post to web services and to infer Data Dictionaries, Descriptions & Tags or Chat with your data.
- fenic uses it to render Jinja templates over DataFrame columns
- Fluvio uses it to render connector configurations and resolve secrets
Web Frameworks and Documentation:
- Rocket supports it as a template engine for dynamic templates
- Litestar supports it via MiniJinja for Python as a template engine plugin
- Ultralytics uses MiniJinja for Python to render macros in its documentation
- sphinx-needs uses MiniJinja for Python to render templates in its Sphinx extension
Packaging and Build Tools:
- rattler-build uses it to evaluate conda package recipes
- pixi uses it to template task commands and arguments
- tract uses it to generate SIMD assembly kernels at build time
Developer Tools:
- Atuin uses it to template shell scripts
- HawkEye uses it to render license headers
- MITRE's Hipcheck uses it to render human readable reports
- Golem uses it to render application manifest templates in its CLI
Code Generation:
- OpenTelemetry's Weaver uses it to generate documentation, code and other outputs from the OTel specification.
- Maturin uses it to generate project structures
- cargo-dist uses it to generate CI and project configuration
SQL Generation:
- Spawn uses it to render database migration scripts and tests and for safe escaping of values.

Similar Projects

These are related template engines for Rust:

Askama: Jinja inspired, type-safe, requires template precompilation. Has significant divergence from Jinja syntax in parts.
Tera: Jinja inspired, dynamic, has divergences from Jinja.
Liquid: an implementation of Liquid templates for Rust. Liquid was inspired by Django from which Jinja took its inspiration.
TinyTemplate: minimal footprint template engine with syntax that takes lose inspiration from Jinja and handlebars.

Sponsor

If you like the project and find it useful you can become a sponsor.

AI Use Disclaimer

This codebase mostly predates LLM based code generation but some recent features have been built with support of AI.