Sphinx "Could not import extension" build error in CI

Sphinx tried to load an extension named in extensions in conf.py and the import failed. Almost always the package that provides it was not installed in the CI environment.

What this error means

sphinx-build aborts at startup with "Could not import extension X (exception: No module named 'X')" before any page is rendered.

Extension error:
Could not import extension sphinx_rtd_theme (exception: No module named 'sphinx_rtd_theme')

Common causes

The extension package is not installed in CI

conf.py lists the extension in extensions, but the distribution that provides it is missing from the docs requirements the runner installed.

A different interpreter or venv than expected

CI installed the extension into one environment but runs sphinx-build from another, so the import path does not include it.

How to fix it

Install the extension in the docs environment

1. Match the import name in the error to its distribution name.
2. Add it to your docs requirements file.
3. Install that file in CI before running sphinx-build.

pip install -r docs/requirements.txt
sphinx-build -b html docs docs/_build/html

Pin docs dependencies in one file

Keep every extension your conf.py loads in a single requirements file so the runner installs them all.

# docs/requirements.txt
sphinx>=7
sphinx-rtd-theme
myst-parser

How to prevent it

• List every extension from conf.py in your docs requirements.
• Install docs requirements into the same interpreter that runs sphinx-build.
• Pin extension versions so behavior is reproducible.

Related guides