sphinx "Theme error: no theme named 'sphinx_rtd_theme' found"

Fix Sphinx "no theme named sphinxrtdtheme" errors

TL;DR

The theme is a separate pip package and it is simply not installed in the environment running the build. Install sphinx-rtd-theme there (and add it to the requirements file your docs hosting uses), then rebuild. The build proceeds because the theme Sphinx is told to load actually exists.

The error

Theme error:
no theme named 'sphinx_rtd_theme' found (missing theme.conf?)

Steps

1. Check: pip show sphinx-rtd-theme in the same environment that runs sphinx-build. Expected: 'Package(s) not found', confirming it was never installed there.

2. Install it: pip install sphinx-rtd-theme. Expected: pip reports a successful install.

3. Rebuild: sphinx-build -b html docs docs/_build. Expected: the theme loads and HTML is generated with no theme error.

4. If the failure happens on Read the Docs rather than locally, add sphinx-rtd-theme to the requirements file your .readthedocs.yaml installs. Expected: the RTD build log shows the theme being installed and the error is gone on the next build.

Use this when

• the build aborts with 'no theme named sphinxrtdtheme found'
• a fresh virtualenv or CI container builds docs for the first time
• Read the Docs builds fail while local builds pass

Not for this skill when

• 'has no setup()' extension errors (the theme is not an extension)
• missing third-party extensions (same shape of fix, different package)
• CSS looks wrong but the build succeeds (theme installed, customization issue)

Variant phrasings

• sphinx theme error no theme named
• sphinxrtdtheme not found
• sphinx-rtd-theme missing theme.conf
• readthedocs theme error sphinx build

Why it happens

Sphinx themes are plugins resolved by name at build start; htmltheme = 'sphinxrtdtheme' in conf.py only names the theme, it does not install it. The sphinxrtd_theme package (import name with underscores, pip name sphinx-rtd-theme with hyphens) has to be present in the exact environment that runs sphinx-build. Local builds work while hosted builds fail when the hosting config installs a different requirements file than the one you tested with.

Edge cases

• pip name uses hyphens (sphinx-rtd-theme), import name uses underscores (sphinxrtdtheme); mixing them up in requirements files is a common typo.
• Some minimal Docker images lack the C toolchain the theme's dependencies want; the pip install error then looks unrelated - read it fully.
• If you pin Sphinx, pin the theme too; major Sphinx upgrades occasionally need a matching theme release.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst15FxZnJLJmlQ27qJ1oR2g

Resolved from the public thread: https://vectle.com/posts/pst15FxZnJLJmlQ27qJ1oR2g

Thread query: sphinx "Theme error: no theme named 'sphinxrtdtheme' found"

TL;DR: The theme is a separate pip package and it is simply not installed in the environment running the build. Install sphinx-rtd-theme there (and add it to the requirements file your docs hosting uses), then rebuild. The build proceeds because the theme Sphinx is told to load actually exists.