Sphinx version mismatch between local and Read the Docs builds causes inconsistent output

Direct Answer

p>To ensure identical output locally and on Read the Docs (RTD), you must explicitly pin the Sphinx version in your .readthedocs.yaml and lock all associated extensions in a requirements.txt file. You can then verify the environment by running the official RTD Docker image locally.

Configuration keys to pin Sphinx

Read the Docs uses specific Docker images that come with pre-installed versions of Sphinx. If you do not specify a version, the platform may use the latest compatible release, which often differs from your local environment. Use the following keys:

• build.tools.python: Sets the Python runtime version (e.g., "3.11").
• build.tools.sphinx: Overrides the image's default Sphinx version with a specific release.
• python.install.requirements: Points to your file containing pinned extensions.

build:
  tools:
    python: "3.11"
    sphinx: "7.2.6"
python:
  install:
    requirements: ["requirements.txt"]
    method: pip

Why output is still inconsistent

Even if Sphinx is pinned, extensions like sphinx-copybutton or myst-parser often have their own dependency cycles. If these are not pinned in requirements.txt, RTD will install the latest version at build time, leading to mismatched CSS classes or broken directives. Always use a strict requirements file:

# requirements.txt
sphinx==7.2.6
myst-parser==2.0.0
sinx-copybutton==0.5.2

How to verify locally without pushing

You can replicate the exact RTD environment by running the specific build image via Docker. If you are on Apple Silicon (M1/M2/M3), you must use the platform flag to ensure compatibility.

1. Identify the image from your RTD build logs (e.g., readthedocs/build:ubuntu-22.04).
2. Run the following command to build your docs locally:

   docker run --rm --platform linux/amd64 -v "$(pwd)":/docs readthedocs/build:ubuntu-22.04 bash -c "cd /docs && sphinx-build -b html -v _build/html"

3. Compare the output with your local build:

   diff -r local_build/html rtd_build/html | grep -v '^Only in' | head -50

Uncertainty and breaking changes

Sphinx 7.x introduced several breaking changes across point releases. Version 7.1 altered default HTML5 writer output, 7.2 changed how autodoc renders type hints, and 7.3 modified how myst-parser parses directives. Because RTD updates its base images periodically, a build that worked last month may break if the underlying image moves to a newer Sphinx point release.

To provide a more specific configuration, which Read the Docs build image and Python version are you currently using?