Read the Docs Sphinx Extension

2.2.5 verified Mon Apr 27 auth: no python

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.

pip install readthedocs-sphinx-ext

Common errors

error ERROR: Could not find a version that satisfies the requirement readthedocs-sphinx-ext ↓

cause Python version mismatch or broken dependency resolution.

fix

Ensure you are using Python 3.7+ and pip is updated: pip install --upgrade pip

error ImportError: cannot import name 'ReadTheDocsBuilder' from 'readthedocs_ext' ↓

cause Incorrect import path. The builder is inside readthedocs_ext.readthedocs.

fix

Use: from readthedocs_ext.readthedocs import ReadTheDocsBuilder

Warnings

breaking The extension is automatically injected by Read the Docs when building. Manually adding it can cause conflicts if versions mismatch. ↓

fix Only add this extension manually if building locally and you need the exact same environment as on Read the Docs.

gotcha Do NOT add both 'readthedocs_ext.readthedocs' and 'sphinx_rtd_theme' in extensions. The former already includes theme overrides. ↓

fix Use only 'readthedocs_ext.readthedocs' in extensions and ensure readthedocs-sphinx-ext is installed.

deprecated The 'readthedocs' builder (classic) is deprecated in favor of 'readthedocs-sphinxsearch'. Check the docs for migration. ↓

fix Set builder = 'readthedocs-sphinxsearch' in conf.py or use the Read the Docs admin panel.

Imports

ReadTheDocsBuilder
```
from readthedocs_ext.readthedocs import ReadTheDocsBuilder
```
The core builder is in readthedocs_ext.readthedocs module.
RedocRole
```
from readthedocs_ext.readthedocs import RedocRole
```
Custom role is imported from the same module.

Quickstart

Add the extension to your Sphinx conf.py to enable Read the Docs specific builders and overrides.

# Add to conf.py:
extensions = ['readthedocs_ext.readthedocs']