---
id: sphinx-jinja2-compat
version: "0.4.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# sphinx-jinja2-compat — Patches Jinja2 v3 to restore compatibility with earlier Sphinx versions.

License: permissive · Maintenance: active · Downloads: 658.7K/mo

## What it is and what it does

sphinx-jinja2-compat is a compatibility shim that automatically patches Jinja2 v3 when imported, allowing it to work with Sphinx versions that were built for earlier Jinja2 releases. It also addresses issues where some Sphinx versions fail to run correctly on Python 3.10. The patches are applied transparently at import time and can be disabled by setting the environment variable NO_SPHINX_JINJA2_COMPAT to 1.

The package depends on jinja2, markupsafe, and standard-imghdr, and is designed to integrate seamlessly into Sphinx documentation builds. It's classified as Alpha but is actively maintained and supports Python 3.6 through 3.13, including both CPython and PyPy implementations.

Use it for:

- Fix Sphinx documentation builds that fail after upgrading to Jinja2 v3
- Run Sphinx on Python 3.10 when using Sphinx versions that have compatibility issues
- Maintain documentation builds across multiple Sphinx versions without manual patching
- Ensure legacy Sphinx projects continue to work with modern Jinja2 releases

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Patches Jinja2 v3 to restore compatibility with earlier Sphinx versions and fixes some Sphinx versions on Python 3.10.

Yes, if you are using Sphinx with Jinja2 v3 and encounter compatibility errors, or if you need Sphinx to work on Python 3.10. The package is actively maintained, has no known vulnerabilities, and installs with low friction. Install only if you actually face the compatibility issues it addresses—it's a targeted fix, not a general dependency.

## Install

pip install sphinx-jinja2-compat
uv add sphinx-jinja2-compat
poetry add sphinx-jinja2-compat

## Installing sphinx-jinja2-compat

Before you install: Low install friction with a pure-Python wheel. Actively maintained as of 2026-07-06 with no known security vulnerabilities.

License in practice: MIT license permits commercial and private use with minimal restrictions—suitable for most projects.

Quickstart:

pip install sphinx-jinja2-compat

import sphinx_jinja2_compat

# Patches are applied automatically on import; disable with NO_SPHINX_JINJA2_COMPAT=1

Verify before relying:

- Which specific Sphinx versions benefit from the Jinja2 v3 compatibility patches
- Whether the Python 3.10 fix applies to all Sphinx versions or only specific ones
- Current test coverage and which Sphinx/Jinja2 version combinations are actively tested

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 658.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx jinja2 compatibility, jinja2 v3 sphinx patch, sphinx python 3.10 fix, jinja2 backward compatibility, sphinx documentation build fix, sphinx-plugin, compatibility-shim

[View on SkillFed](https://skillfed.io/packages/sphinx-jinja2-compat) · [View on PyPI](https://pypi.org/project/sphinx-jinja2-compat/)