{"id":5493,"library":"sphinx-jinja2-compat","title":"sphinx-jinja2-compat","description":"sphinx-jinja2-compat, current version 0.4.1, is a utility library designed to patch Jinja2 v3, restoring compatibility with earlier Sphinx versions. It also addresses issues to ensure some Sphinx versions function correctly on Python 3.10. This library primarily serves as a compatibility layer to bridge gaps between major versions of its dependencies, rather than providing new user-facing features. Releases are made on an as-needed basis to address specific compatibility challenges.","status":"active","version":"0.4.1","language":"en","source_language":"en","source_url":"https://github.com/sphinx-toolbox/sphinx-jinja2-compat","tags":["Sphinx","Jinja2","compatibility","patch","documentation"],"install":[{"cmd":"pip install sphinx-jinja2-compat","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"The template engine that sphinx-jinja2-compat patches for compatibility.","package":"Jinja2","optional":false},{"reason":"The documentation generator for which compatibility is restored.","package":"Sphinx","optional":false},{"reason":"A core dependency of Jinja2.","package":"MarkupSafe","optional":false}],"imports":[],"quickstart":{"code":"# Simply install the package. No direct code import or configuration in conf.py is typically needed.\n# The patch is applied automatically upon import of related modules within Sphinx.\n# To disable the patches, set the environment variable before running Sphinx:\nimport os\nos.environ['NO_SPHINX_JINJA2_COMPAT'] = '1'\n# Then run Sphinx as usual, e.g., via command line:\n# sphinx-build -b html source build\n\nprint(\"sphinx-jinja2-compat is active once installed, patching Jinja2 for Sphinx compatibility.\")","lang":"python","description":"Installation of `sphinx-jinja2-compat` is typically sufficient; it works by applying patches on import of relevant modules within Sphinx, rather than requiring explicit inclusion in `conf.py`'s `extensions` list. The primary effect is restoring compatibility for older Sphinx versions with Jinja2 v3 and ensuring Python 3.10 compatibility for certain Sphinx versions. The patches can be disabled by setting the environment variable `NO_SPHINX_JINJA2_COMPAT` to `1`."},"warnings":[{"fix":"No fix needed; this is its intended mode of operation. Do not attempt to import `sphinx_jinja2_compat` into your `conf.py` or Python code for direct functionality.","message":"This library operates as a low-level patch and does not expose direct user-facing Python imports or functions for common usage. Its effect is passive, modifying the behavior of Jinja2 within Sphinx.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Test your Sphinx build thoroughly after installation. If issues arise, consider temporarily disabling the patches by setting the environment variable `NO_SPHINX_JINJA2_COMPAT=1` to isolate the problem. Adjust custom code to be compatible with the patched Jinja2 behavior if necessary.","message":"If your Sphinx project or custom extensions rely on specific Jinja2 v3 behaviors that `sphinx-jinja2-compat` alters to restore compatibility, unintended side effects might occur. This is more likely for highly customized Sphinx setups.","severity":"breaking","affected_versions":"All versions (where Jinja2 v3 is used with older Sphinx versions)"},{"fix":"To disable the patches, ensure `os.environ['NO_SPHINX_JINJA2_COMPAT'] = '1'` is set in your build environment or a script wrapper before Sphinx execution. To re-enable, remove or unset the variable.","message":"The patches applied by `sphinx-jinja2-compat` can be disabled at runtime by setting the environment variable `NO_SPHINX_JINJA2_COMPAT` to `1` before running Sphinx. This might be useful for debugging or when the compatibility layer is not desired.","severity":"gotcha","affected_versions":"v0.2.0 and newer"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}