Read the Docs build failed installing requirements in CI

By Daniel Zoghalchali·Latchkey

Read the Docs installs the dependencies listed under python.install in .readthedocs.yaml. If that section is missing or points at the wrong file, the docs build later fails on missing extensions, themes, or modules.

What this error means

The RTD build fails in the install step or later with a missing Sphinx extension/theme, because the requirements file was not installed or pip raised on it.

Running Sphinx ... Could not import extension myst_parser (exception: No module named 'myst_parser')

Common causes

No python.install pointing at docs requirements

The config does not install your docs requirements file, so extensions and themes are absent at build time.

A pip failure on the requirements

A bad pin or unavailable package in the requirements file makes the install step itself fail.

How to fix it

Install docs requirements via python.install

1. Add a python.install entry pointing at your docs requirements file.
2. Include every Sphinx/MkDocs extension and theme there.
3. Re-trigger the build.

python:
  install:
    - requirements: docs/requirements.txt

Pin docs dependencies explicitly

List Sphinx, the theme, and all extensions with versions so the install is reproducible on RTD.

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

How to prevent it

• Always install docs requirements via python.install.
• Keep every extension and theme in the requirements file.
• Pin versions so RTD builds reproducibly.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation