Configure Read the Docs Builds with .readthedocs.yml: Python Version, Dependencies, and Custom Commands

Why a .readthedocs.yml file matters

Read the Docs builds documentation in an isolated environment. Without explicit configuration it falls back to defaults: Python 3.8, no extra dependencies, and the standard sphinx-build -b html . _html command. If your project needs a newer Python version, additional packages, or a custom build step, you must commit a .readthedocs.yml file at the repository root. The file is read on every build and completely defines the environment.

Worked example: a typical Sphinx project

Assume a Sphinx project that requires Python 3.11, the sphinx-rtd-theme, and a custom extension listed in requirements.txt. The repository structure looks like this:

my-docs/
├── .readthedocs.yml
├── requirements.txt
├── conf.py
├── index.rst
└── ...

The .readthedocs.yml content

# .readthedocs.yml
version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

python:
  install:
    - requirements: requirements.txt

# Optional: override the default Sphinx command
# sphinx:
#   builder: html
#   configuration: conf.py
#   fail_on_warning: true

What each key does

• version: 2 – selects the v2 configuration schema (required).
• build.os – chooses the base image; ubuntu-22.04 is the current default and provides Python 3.11.
• build.tools.python – pins the Python interpreter version. Use a version available on the selected OS image.
• python.install – tells Read the Docs to run pip install -r requirements.txt inside the build virtual environment. You can also list multiple requirement files or direct package specifications.
• sphinx.* (commented) – optional overrides. Uncomment to change builder, configuration file, or treat warnings as errors.

The requirements.txt file

# requirements.txt
sphinx==7.2.6
sphinx-rtd-theme==2.0.0
sphinx-copybutton==0.5.2
# any other extensions your conf.py imports

How the build runs

When a build triggers, Read the Docs:

1. Clones the repository.
2. Creates a fresh virtual environment using the Python version declared in build.tools.python.
3. Executes pip install -r requirements.txt (or the equivalent for each entry under python.install).
4. Runs the build command. For Sphinx the default is sphinx-build -b html -d _build/doctrees . _build/html. If you added a sphinx: section, those options replace the defaults.
5. Uploads the generated HTML from _build/html (or the output directory you configured) to the hosting CDN.

Limits you must design around

Limit	Value	Implication
Maximum build time	120 minutes	Large projects with many extensions or heavy assets may time out. Consider splitting documentation or using incremental builds.
Disk quota per build	2 GB	Includes the cloned repo, virtual environment, and build artifacts. Avoid committing large binary files to the docs repository.
Supported builders	Sphinx, MkDocs, plain HTML	Custom scripts (e.g., running make or a custom Python script) must be expressed within the chosen builder or via the build.jobs hook (advanced).
Python versions	Only versions pre-installed on the selected OS image	Check the Read the Docs build tools reference for the current matrix. Requesting an unavailable version fails the build.

Common mistakes and how to avoid them

File not found or wrong location

The file must be named exactly .readthedocs.yml (lowercase, leading dot) and sit at the repository root—the same level as your .git directory. If it’s in a subdirectory or named readthedocs.yml without the dot, Read the Docs ignores it and uses defaults, often causing ModuleNotFoundError for missing extensions.

Unavailable Python version

Specifying python: "3.13" on an image that only provides up to 3.12 fails with a cryptic “tool not found” error. Always verify the version matrix for your chosen build.os before committing.

Using Poetry or Pipenv without installing them

If your requirements.txt is generated from poetry export or you rely on pipenv sync, you must add the package manager to the install step:

python:
  install:
    - method: pip
      packages: [poetry]
    - requirements: requirements.txt

Otherwise the build environment lacks poetry and the install step fails.

Forgetting to commit the file

Because the file lives in the repo, every contributor must push it. A missing file on a branch triggers a fallback build that may succeed locally but break on Read the Docs. Add a CI check (e.g., a GitHub Action) that validates the presence and syntax of .readthedocs.yml on pull requests.

Verifying the configuration works

1. Inspect the build log

In the Read the Docs dashboard, open the build detail page. The log shows:

• The Python version being activated (e.g., Using Python 3.11.9).
• The exact pip install command run, including the path to requirements.txt.
• The final sphinx-build invocation with all flags.

If the log shows a different Python version or missing packages, the YAML was not read—check file location and syntax.

2. Browse the generated output

After a successful build, visit the versioned URL (e.g., https://my-project.readthedocs.io/en/latest/). Confirm that:

• The theme matches sphinx-rtd-theme (or your chosen theme).
• Custom extensions like sphinx-copybutton render copy buttons on code blocks.
• No console errors appear in the browser developer tools.

3. Replicate locally

Run the same steps on your machine to catch discrepancies before pushing:

# In a clean directory
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
sphinx-build -b html -d _build/doctrees . _build/html

The local _build/html should be visually identical to the hosted version. Differences usually indicate a missing dependency or a version mismatch.

Next steps

• Add .readthedocs.yml to your repository root if it’s missing.
• Pin the Python version your project tests against.
• List every runtime dependency in requirements.txt (or multiple requirement files).
• Optionally override the Sphinx builder or enable fail_on_warning for stricter quality.
• Trigger a build and verify using the three checks above.

Once the file is committed and the build passes, future pushes—including pull request previews—will use the exact same environment, eliminating “works on my machine” surprises.