readthedocs.yaml config version 2 vs. RTD build fleet: default image and interpreter resolution when build.os and build.tools.python are omitted

Answer

When build.os and build.tools.python are omitted in a config-version-2 readthedocs.yaml, Read the Docs (RTD) applies an internal, version-specific mapping to choose a container image and Python interpreter. The exact mapping is not published as a stable, versioned API, and it can change as RTD retires old images. The resolved values are observable in build logs and, in many cases, through build environment variables.

Confirmed behavior

• RTD maintains an internal mapping tied to config version, so v2 defaults are separate from v1 defaults.
• When omitted, the build fleet selects a default Ubuntu image and a matching Python interpreter automatically.
• The mapping is not exposed through a public versioned table; build logs are the authoritative source for the resolved environment.
• Defaults may differ between readthedocs.org and readthedocs.com, and the paid tier may offer additional overrides through its web UI.

Likely defaults, subject to change

Based on RTD's build-fleet history, the current default for config v2 is typically Ubuntu 22.04 LTS, with the interpreter set to the latest stable Python 3 release available on that image (often Python 3.10 or 3.11). These are operational observations, not contractual guarantees, and RTD may update them without notice.

Detecting the resolved environment during a build

You can confirm the resolved image and interpreter by inspecting the first lines of a build log. Within the build, you can also print environment variables that RTD sets, if present:

echo $READTHEDOCS_OS
echo $READTHEDOCS_PYTHON

If those variables are absent, parse the log for the image tag and Python version string.

Verification steps

1. Create or edit readthedocs.yaml so it omits build.os and build.tools.python.
2. Trigger a build on RTD.
3. Open the build log and locate the line identifying the image and Python version.
4. Optionally add echo $READTHEDOCS_OS $READTHEDOCS_PYTHON to a build step or documentation script to print the resolved values.
5. If you use both readthedocs.org and readthedocs.com, compare the logs to detect tier-specific differences.

Missing diagnostic detail

Are you building on the free readthedocs.org tier or on a paid readthedocs.com account? This determines whether tier-specific default images apply and whether web UI overrides are available.

Recommendation

If your documentation build depends on a specific Python version or OS behavior, explicitly pin build.os and build.tools.python in readthedocs.yaml. Relying on defaults risks silent breakage when RTD updates its build fleet.