{"id":21866,"library":"readthedocs-sphinx-ext","title":"Read the Docs Sphinx Extension","description":"Sphinx extension that provides custom directives and configurations used by Read the Docs builds, including the `readthedocs` and `readthedocs-sphinxsearch` builders, custom roles, and overrides for analytics, PDF, and EPub generation. Version 2.2.5 is the latest stable release, with a maintenance cadence aligned with Read the Docs platform updates.","status":"active","version":"2.2.5","language":"python","source_language":"en","source_url":"https://github.com/readthedocs/readthedocs-sphinx-ext","tags":["sphinx","readthedocs","documentation","build"],"install":[{"cmd":"pip install readthedocs-sphinx-ext","lang":"bash","label":"Standard pip install"}],"dependencies":[],"imports":[{"note":"The core builder is in readthedocs_ext.readthedocs module.","wrong":"","symbol":"ReadTheDocsBuilder","correct":"from readthedocs_ext.readthedocs import ReadTheDocsBuilder"},{"note":"Custom role is imported from the same module.","wrong":"","symbol":"RedocRole","correct":"from readthedocs_ext.readthedocs import RedocRole"}],"quickstart":{"code":"# Add to conf.py:\nextensions = ['readthedocs_ext.readthedocs']","lang":"python","description":"Add the extension to your Sphinx conf.py to enable Read the Docs specific builders and overrides."},"warnings":[{"fix":"Only add this extension manually if building locally and you need the exact same environment as on Read the Docs.","message":"The extension is automatically injected by Read the Docs when building. Manually adding it can cause conflicts if versions mismatch.","severity":"breaking","affected_versions":"all"},{"fix":"Use only 'readthedocs_ext.readthedocs' in extensions and ensure readthedocs-sphinx-ext is installed.","message":"Do NOT add both 'readthedocs_ext.readthedocs' and 'sphinx_rtd_theme' in extensions. The former already includes theme overrides.","severity":"gotcha","affected_versions":"all"},{"fix":"Set builder = 'readthedocs-sphinxsearch' in conf.py or use the Read the Docs admin panel.","message":"The 'readthedocs' builder (classic) is deprecated in favor of 'readthedocs-sphinxsearch'. Check the docs for migration.","severity":"deprecated","affected_versions":">=2.2.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Ensure you are using Python 3.7+ and pip is updated: pip install --upgrade pip","cause":"Python version mismatch or broken dependency resolution.","error":"ERROR: Could not find a version that satisfies the requirement readthedocs-sphinx-ext"},{"fix":"Use: from readthedocs_ext.readthedocs import ReadTheDocsBuilder","cause":"Incorrect import path. The builder is inside readthedocs_ext.readthedocs.","error":"ImportError: cannot import name 'ReadTheDocsBuilder' from 'readthedocs_ext'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}