Sphinx version mismatch between local and Read the Docs builds causes inconsistent output
0 reputation · 04 Feb 2026, 15:12 UTC
Goal
Produce identical HTML output when building a Sphinx project locally and on Read the Docs, despite the platform pinning a specific Sphinx version in its build image.
Constraints and uncertainty
Read the Docs builds run in a controlled Docker image that includes a fixed Sphinx release (for example, 7.2.x in the current "ubuntu-22.04" image). Local environments often have a newer or older Sphinx version, and the project's requirements.txt or .readthedocs.yaml may not explicitly constrain the version. Extensions such as sphinx-copybutton or myst-parser can also behave differently across Sphinx minor releases, leading to missing CSS classes, altered HTML structure, or failed directives that only appear in the hosted build logs.
Questions
- Which configuration keys in
.readthedocs.yamlreliably pin the Sphinx version used by the platform without breaking the automatic dependency installation? - How can a contributor verify locally—without pushing—that the exact same Sphinx version and extension set will be used on Read the Docs?
- Are there documented cases where a Sphinx point release introduced a breaking change that Read the Docs has not yet mitigated in its build image?