readthedocs build failed: pip install requirements timed out

Fix Read the Docs builds failing on pip install timeout

TL;DR

The RTD build installs your full requirements, including heavy runtime dependencies the docs never import, and the install step exceeds the build time limit. Split out a docs-only requirements file with just Sphinx, the theme, and extensions, pin the versions, and re-trigger the build. The install finishes in time because there is far less to download and compile.

The error

readthedocs.org build output:
Collecting torch==2.1.0
  Downloading torch-2.1.0-...whl (800 MB)
...
Build failed: pip install timed out after 3600 seconds

Steps

1. Open .readthedocs.yaml and find which file the build installs under python: install: requirements:.

Expected: you know the exact requirements file the RTD build uses.

1. Create a docs-only requirements file (e.g. docs/requirements.txt) containing only what the docs build imports: sphinx, sphinx-rtd-theme or your theme, sphinx.ext extensions, myst-parser if used. Drop ML frameworks, DB drivers, and other runtime deps the docs never touch.

Expected: the new file is a fraction of the size of the full requirements.

1. Pin every version (sphinx==7.2.6 style) so the resolver does not churn through candidates on each build.

Expected: a fresh pip install -r docs/requirements.txt locally is fast and deterministic.

1. Point .readthedocs.yaml at the docs-only file and re-trigger the build from the RTD dashboard.

Expected: the install step completes inside the time limit and the build proceeds to sphinx-build.

Use this when

• the RTD build log shows pip install timing out
• requirements include torch, tensorflow, or other hundred-megabyte wheels
• local docs builds pass but RTD builds die during install

Not for this skill when

• sphinx-build errors after install succeeds (a docs content problem, not an install problem)
• 'failed to import module' for a dependency the docs DO need (that one must stay in the file)
• timeouts in the sphinx-build step itself (slow build, different fix)

Variant phrasings

• readthedocs pip install timed out
• readthedocs build failed requirements install timeout
• rtd build exceeded time limit pip
• readthedocs docs requirements heavy dependencies

Why it happens

Read the Docs enforces a maximum build duration, and the pip install step counts against it. Projects commonly point RTD at the same requirements file used for the application, which drags in compiled wheels for frameworks the documentation build never imports - autodoc only needs the modules it documents plus their direct imports. Trimming the install to docs-only dependencies is the fix; everything else is just waiting on downloads the build does not need.

Edge cases

• If autodoc documents modules that import the heavy dependency, keep a lightweight stub or use autodocmockimports for it instead of installing the real wheel.
• RTD caches pip downloads between builds, but a cold cache plus unpinned versions still blows the limit; pinning keeps the cache effective.
• Watch for one dependency silently pulling a huge wheel (check pip download sizes); replacing that single line often fixes the timeout alone.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_b16XglYeVrm4sFKqK5W-6w