Jinja2 Filters

Filters let you transform values at render time.

Syntax:

html

{{ value | filter_name }}

diagram escaping, and the two ways to switch it off mermaid

  flowchart TD
  A["user-supplied string with tags"] --> B{"how is it rendered?"}
  B -->|"{{ x }}"| C["escaped: <script> …"]
  C --> D["the browser shows it as text -- safe"]
  B -->|"{{ x|safe }}"| E["inserted raw"]
  B -->|"Markup(x) in Python"| E
  E --> F["the browser EXECUTES it -- XSS"]
  D --> G["use this for anything a user can influence"]
  F --> H["use this only for markup you generated yourself"]

With autoescaping on, a value containing markup is neutralised on the way into the page. There are exactly two ways to bypass that -- the safe filter in the template and Markup() in Python -- and both mean you are promising the string is trustworthy. Applying either to something a user typed is how cross-site scripting happens.

Common built-in filters

html

<p>{{ username | lower }}</p>
<p>{{ username | upper }}</p>
<p>{{ items | join(", ") }}</p>

Default values

html

<p>{{ bio | default("No bio yet") }}</p>

length

html

<p>Count: {{ items | length }}</p>

Important security note: safe

|safe tells Jinja “don’t escape this value”.

Only use it if you’re absolutely sure the HTML is trusted.

Never mark raw user input as safe.