Pin your Read the Docs build environment with .readthedocs.yaml

You merge a documentation pull request, the Read the Docs build passes, and the published site is still missing a page or theme that rendered fine on your laptop. The cause is usually environment drift, not Sphinx. Read the Docs runs builds in isolated containers—temporary environments that include only what your configuration declares. If your .readthedocs.yaml file does not pin the Python version, install documentation dependencies, or select the Sphinx builder, the container can assemble a different environment than your local machine.

You can prevent most of this drift with a single configuration file at your repository root. This post walks through a minimal setup, explains how Read the Docs treats branches and tags as documentation versions, and shows what to check in the build logs before you declare a build successful.

Why local and Read the Docs builds diverge

Read the Docs builds run in isolated containers, so system packages you have installed locally are not automatically available during the build. If your documentation needs a system library or a specific Python interpreter, and that dependency is not declared in the configuration, the build may fail or produce output that differs from your local preview.

Python version drift is another common source of mismatch. A project developed locally on Python 3.12 may be built on Read the Docs using a different default interpreter unless the configuration explicitly selects one.

A minimal .readthedocs.yaml configuration

Create .readthedocs.yaml in the repository root. This example pins Python 3.11, installs documentation dependencies from docs/requirements.txt, and tells Sphinx to use the dirhtml builder, which produces directory-based HTML output suited to clean URLs:

version: 2

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

sphinx:
  configuration: docs/source/conf.py
  builder: dirhtml
  fail_on_warning: true

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

The version: 2 key declares the Read the Docs configuration schema; it is not the documentation version. The configuration format changed between schema v1 and v2, so older projects may need migration. fail_on_warning: true is optional: it turns Sphinx warnings into build failures, which is useful for catching broken links or missing references early, but it can also fail builds on warnings you previously tolerated locally.

If your docs require system-level packages, declare them under build.apt or use a Conda environment under build.conda. Because the container is isolated, undeclared system packages will be missing at build time.

Branches, tags, and documentation versions

Read the Docs automatically detects branches and tags as separate documentation versions. The configuration can restrict which versions are built, which is useful for preventing old release branches from consuming build minutes. For example, you can list branches or tags to ignore in a versions section; verify the exact keys against the current Read the Docs documentation, because the schema has changed between versions.

Worked example: add the config and verify the build

1. In a local terminal at the repository root, create a branch. You need write permission to the repository:

git checkout -b add-rtd-config

1. Add .readthedocs.yaml using the example above, adjusting paths if your Sphinx configuration lives elsewhere.
2. Commit and push:

git add .readthedocs.yaml
git commit -m "Add Read the Docs build configuration"
git push origin add-rtd-config

1. In the Read the Docs dashboard, connect or sync the project, then trigger a build for the new branch.

Expected checks: open the build log and confirm that it detects Python 3.11, installs dependencies from docs/requirements.txt, runs the dirhtml builder, and completes without an error exit code. Compare the rendered output with your local build, for example:

python -m sphinx -b dirhtml docs/source _build/local

Risks: failed builds consume build minutes, and fail_on_warning: true can fail the build on pre-existing Sphinx warnings. Private repository support and build minute allowances depend on your Read the Docs plan and are not governed by the configuration file alone.

Limitations and rollback

This configuration controls the build environment, but it does not control plan-level limits such as private repository access or build minutes. System packages not declared in build.apt or build.conda will be unavailable in the isolated container.

Because adding and pushing this file changes repository state, you can roll back by reverting the commit or removing the file and pushing again:

git revert <commit-sha>
git push origin main

After rollback, trigger a new Read the Docs build to confirm the previous configuration is no longer applied.

Closing checklist

• Add .readthedocs.yaml with version: 2 and a pinned Python version.
• Declare documentation dependencies under python.install.
• Select the Sphinx builder and source/configuration directories that match your local setup.
• Trigger a build and inspect the log for the detected Python version, installed packages, and builder name.
• Compare the Read the Docs output with a local dirhtml build before announcing the change.