Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Jinja2 Custom Filters and Macros

Learn how to create custom filters and macros in Python Jinja2 templates. Includes syntax, practical examples, macro imports, and guidance on when to use each.

~4 min readPython
#Jinja2#Python#Custom Filters#Macros
Illustration of Jinja2 template with custom filter and macro symbols representing transformation and reusable components.

Jinja2 lets you extend templates with custom filters and macros. Filters transform values in expressions, while macros define reusable template fragments. This article covers the syntax, examples, and the cases where each tool works best.

What Filters and Macros Do in Jinja2

Jinja2 templates provide two extension points: filters and macros. Filters are Python functions that transform a value and are applied with the pipe character, as in {{ value | filter }}. Macros are template-defined functions that return a fragment of template output, invoked like {{ macro_name() }}. Both help keep templates readable and avoid repeated logic, but they serve different purposes.

Creating a Custom Filter in Python

A custom filter is a plain Python function that takes the filtered value as its first argument and returns the transformed value. To register it, assign the function to environment.filters under the name you want to use in templates.

python
from jinja2 import Environment def reverse_string(s): return s[::-1] env = Environment() env.filters['reverse'] = reverse_string

Now the template can use {{ 'hello' | reverse }} and get olleh. Filters can also accept additional arguments. The first argument is always the value on the left of the pipe, and any extra arguments are passed after the filter name.

python
def truncate_text(text, length=20, suffix='...'): if len(text) > length: return text[:length] + suffix return text env.filters['truncate'] = truncate_text

In the template: {{ long_text | truncate(30, '…') }}. The filter receives long_text as text, 30 as length, and '…' as suffix.

Using Custom Filters in Templates

Filters can be chained, and the output of one filter becomes the input of the next. This is useful for composing transformations.

jinja
{{ user_input | escape | truncate(50) }}

Here escape runs first, then truncate runs on the escaped string. Filters also work inside for loops and conditionals, so you can transform values as they are rendered.

jinja
{% for item in items %} {{ item.name | capitalize }} {% endfor %}

When you register a filter, it is available in every template rendered by that environment. That is convenient, but it also means you should choose filter names that do not collide with built-in filters.

Defining Macros in Templates

A macro is defined with the {% macro %} tag. It can take arguments and return a template fragment. Macros are useful for repeating UI components, such as form fields, buttons, or layout snippets.

jinja
{% macro render_input(name, type='text', placeholder='') %} <input type="{{ type }}" name="{{ name }}" placeholder="{{ placeholder }}"> {% endmacro %}

Call it with {{ render_input('username', placeholder='Username') }}. Macros can contain any Jinja2 syntax, including conditionals and loops, so they can generate complex HTML while keeping the template clean.

Macros are scoped to the template they are defined in. To reuse macros across templates, you need to import them.

Importing Macros from Other Templates

Jinja2 provides two import mechanisms. The import statement brings in the whole template as a namespace, and the from statement imports specific macros.

jinja
{% import 'macros.html' as ui %} {{ ui.render_input('email') }}
jinja
{% from 'macros.html' import render_input, render_button %} {{ render_input('password') }}

Jinja2 exposes the macros defined in the imported template. Keep macro templates focused on macro definitions, and avoid putting top-level markup in them if you plan to import them, because top-level output is not delivered to the importing template.

Filters vs Macros: Choosing the Right Tool

Filters and macros overlap in some areas, but they are not interchangeable. Filters transform a single value and return a single value. Macros generate template output and can contain HTML structure.

AspectFilterMacro
InputA value (and optional arguments)Arguments passed explicitly
OutputA transformed valueA rendered template fragment
Use caseString manipulation, formatting, data conversionReusable UI components, layout blocks
Defined inPython codeTemplate file
Invocation`{{ valuefilter(args) }}`

Use a filter when you need to change how a value is displayed, such as formatting a date or truncating text. Use a macro when you need to repeat a block of markup with different parameters. If you find yourself writing the same HTML structure multiple times, a macro is usually the right abstraction.

Common Pitfalls with Custom Filters and Macros

One common mistake is forgetting that the value being filtered is always the first argument. If you define a filter with an optional second argument, you must call it with the pipe syntax correctly.

Another pitfall is macro variable scoping. A macro does not automatically receive variables from the template where it is called. For example:

jinja
{% set user = 'alice' %} {{ render_greeting() }} {# render_greeting cannot see user #}

To pass user, you must pass it as an argument: {{ render_greeting(user) }}. If you import a macro from another template and need access to the current template variables, add with context to the import.

If autoescaping is enabled, a filter that returns HTML must be marked safe, otherwise Jinja2 will escape it. Use markupsafe.Markup or the |safe filter in the template.

python
from markupsafe import Markup def linkify(text): return Markup(f'<a href="{text}">{text}</a>')

Without this, the output would be escaped and displayed as literal text.

Organizing Custom Filters and Macros in a Project

For maintainability, keep custom filters in a dedicated Python module and register them in one place. A common pattern is to have a function that takes an Environment and registers all filters.

python
# filters.py from jinja2 import Environment def reverse_string(s): return s[::-1] def truncate_text(text, length=20, suffix='...'): if len(text) > length: return text[:length] + suffix return text def register_filters(env: Environment): env.filters['reverse'] = reverse_string env.filters['truncate'] = truncate_text

Then call register_filters(env) after creating the environment. This makes it easy to test filters independently and reuse them across projects.

Macros belong in separate template files, typically named _macros.html or macros.html. Group related macros together and import only what you need. Overloading a single template with dozens of macros makes it harder to navigate. Keep macros focused on one component or UI pattern.

When a macro grows too large, consider whether it should be a separate partial template included with {% include %} instead. Macros are best for parameterized functions; partials are better for static fragments that do not need arguments.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.