starlette templateing: jinja2: pass kwargs for environment

The Fix

Upgrade to version 0.18.0 or later.

Based on closed Kludex/starlette issue #427 · PR/commit linked

Open PR/Commit

@@ -64,6 +64,20 @@ def test_homepage():
 ```
 
+## Customizing Jinja2 Environment
+
+`Jinja2Templates` accepts all options supported by Jinja2 `Environment`.

fix.md

Option A — Upgrade to fixed release\nUpgrade to version 0.18.0 or later.\nWhen NOT to use: Do not use this fix if backward compatibility with existing templates is a concern.\n\n

Why This Fix Works in Production

Trigger: While you can change the env afterwards, it would allow Jinja2 to validate e.g. `enable_async`, and call `load_extensions` etc.
Mechanism: The Jinja2Templates class did not allow passing additional options to the Jinja2 Environment
Why the fix works: Allows `Jinja2Templates` to accept additional options for the Jinja2 `Environment`, enhancing customization capabilities. (first fixed release: 0.18.0).

Why This Breaks in Prod

The Jinja2Templates class did not allow passing additional options to the Jinja2 Environment
Production symptom (often without a traceback): While you can change the env afterwards, it would allow Jinja2 to validate e.g. `enable_async`, and call `load_extensions` etc.

Proof / Evidence

GitHub issue: #427
Fix PR: https://github.com/kludex/starlette/pull/1401
First fixed release: 0.18.0
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.69

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“Yup I'm up for this. We'll want to autoescape and loader be overridable there too. Related to this is configuring env.globals. We *could* just use…”

@lovelydinosaur · 2019-03-08 · source

“+1 as well, since as currently stands it's not possible to change common fields such as auto_reload, enable_async when loading the environment, especially when deploying…”

@liquiddandruff · 2021-06-04 · source

“I think it should just allow more easily to set the env altogether”

@blueyed · 2019-05-01 · source

Failure Signature (Search String)

While you can change the env afterwards, it would allow Jinja2 to validate e.g. `enable_async`, and call `load_extensions` etc.
+1 as well, since as currently stands it's not possible to change common fields such as `auto_reload`, `enable_async` when loading the environment, especially when deploying

Copy-friendly signature

signature.txt

Failure Signature
-----------------
While you can change the env afterwards, it would allow Jinja2 to validate e.g. `enable_async`, and call `load_extensions` etc.
+1 as well, since as currently stands it's not possible to change common fields such as `auto_reload`, `enable_async` when loading the environment, especially when deploying through a docker environment.

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
While you can change the env afterwards, it would allow Jinja2 to validate e.g. `enable_async`, and call `load_extensions` etc.
+1 as well, since as currently stands it's not possible to change common fields such as `auto_reload`, `enable_async` when loading the environment, especially when deploying through a docker environment.

What Broke

Users were unable to customize Jinja2 environment settings like auto_reload and enable_async.

Why It Broke

The Jinja2Templates class did not allow passing additional options to the Jinja2 Environment

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

Upgrade to version 0.18.0 or later.

When NOT to use: Do not use this fix if backward compatibility with existing templates is a concern.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/kludex/starlette/pull/1401

First fixed release: 0.18.0

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

Do not use this fix if backward compatibility with existing templates is a concern.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
Pin production dependencies and upgrade only with a reproducible test that hits the failing path.

Version Compatibility Table

Version	Status
0.18.0	Fixed

Related Issues

No related fixes found.

Cluster: starlette:other All hubs All clusters

Related clusters: Configuration error Data consistency SSL handshake

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

starlette templateing: jinja2: pass kwargs for environment (Fix)