sphinx-jinja2-compat

Patches Jinja2 v3 to restore compatibility with earlier Sphinx versions.

sphinx-jinja2-compat v0.4.1 658.7K downloads/30d#5,468 on PyPI★ 1

Permissive license MIT Active released 2025-08-06

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 on this page — 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

sphinx-jinja2-compat on PyPI

pip

pip install sphinx-jinja2-compat

uv

uv add sphinx-jinja2-compat

poetry

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 the current Python release (>=3.6)
Install friction	low — pure-Python wheel
Runtime dependencies	3 — jinja2, markupsafe, standard-imghdr
Maintenance	actively maintained — 373 days since the last release
Last repo commit	2026-07-06
First released	2022-03-29
Downloads	658,656/month — #5,468 on PyPI (30-day window, as of 2026-08-14)
Known vulnerabilities	none known (OSV.dev, checked 2026-08-14)

Evidence: sphinx_jinja2_compat-0.4.1-py3-none-any.whl

Keywords: documentation, jinja2, sphinx

Development Status :: 3 - AlphaIntended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseOperating System :: OS IndependentProgramming Language :: PythonProgramming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.7Programming Language :: Python :: 3.8Programming Language :: Python :: 3.9Programming Language :: Python :: Implementation :: CPythonProgramming Language :: Python :: Implementation :: PyPyTopic :: DocumentationTopic :: Documentation :: SphinxTopic :: Software Development :: Documentation