VersionConflict in Read the Docs build images when project specifies newer Sphinx than image provides

Which Sphinx version is installed first?

During a standard Read the Docs build the install phase creates a Python virtual environment, then runs pip install -r requirements.txt. The Sphinx version declared in requirements.txt (or the latest available if none) is installed inside that virtualenv, and the sphinx-build command that runs later uses the sphinx executable from that environment. Therefore the version installed first is the one from the virtualenv, not the system‑installed package.

When does system‑installed Sphinx take precedence?

The system‑installed Sphinx from the base image is used only if the build skips the virtualenv step (e.g., the no virtualenv flag or a custom Dockerfile that runs pip install directly on the host filesystem). In that case the sphinx-build binary from the image’s /usr/bin is executed before any pip‑installed version.

.readthedocs.yaml image setting

The build.image directive selects the Docker base image (OS packages and default Python version) but does not change the order in which Sphinx is invoked. The precedence remains: virtualenv‑installed Sphinx first, then system‑installed Sphinx if the virtualenv step is omitted.

Enforcing a specific Sphinx version without a custom image

1. Pin the desired version in requirements.txt, for example sphinx==7.2.6.
2. Ensure the build uses the default virtualenv workflow (do not set NO_VIRTUALENV or a custom Dockerfile that bypasses pip install -r requirements.txt).
3. Verify the installation by checking the log line that runs pip install -r requirements.txt and confirming the reported version with pip show sphinx or sphinx-build --version.

Verification steps

• Inspect the build log for the line that executes pip install -r requirements.txt and note the Sphinx version reported by pip show sphinx.
• Confirm that sphinx-build runs inside an activated virtualenv by looking for VIRTUAL_ENV in the logs or by adding which sphinx-build before the build step.

Missing diagnostic detail

Do you use a custom Dockerfile that skips the virtualenv step (e.g., runs pip install directly or sets NO_VIRTUALENV)? This information determines whether the system‑installed Sphinx could be used first.