.readthedocs.yaml v2 Image and Interpreter Pinning When Older Tags Lack the Config File

Short answer

A tag that contains no .readthedocs.yaml does not inherit the pinned build.os and Python version from your default branch. Read the Docs evaluates configuration per checkout, so for that ref the build falls back to whatever the project can resolve without a config file — in practice, project-level defaults rather than the v2 pins. There is no supported way to pin an image or interpreter for a ref that cannot carry the file, short of rewriting the tag or adding the config to a new tag. The version warning banner and canonical URL logic live at the routing/serving layer and do not depend on which interpreter built the HTML.

What is confirmed vs. likely

Confirmed behavior: RTD reads the config from the commit being built. Refs without the file are built using fallback settings, and the build log records the config path (or its absence), the image, and the interpreter actually used. Hidden versions still build; they just don't appear in the flyout.

Likely, but verify on your project: whether the fallback for a config-less tag is the project's current web-UI build settings or a platform default assigned at project creation. Historically RTD has moved projects through default images (e.g., ubuntu-20.04 to ubuntu-22.04) and deprecated old Python versions, so the same tag can build on a different image today than it did a year ago. Treat any specific image/interpreter value as time-dependent, not a fixed fact.

Answering the three sub-questions

1. Web-UI settings or platform defaults? For legacy projects, the web dashboard exposes build options that act as the fallback when no config file exists; for projects where those options are absent or neutral, platform defaults apply. The only reliable way to know which is in effect for your tag is the build log — it prints the resolved image and Python version near the top of the environment-setup step.
2. Pinning without rewriting the tag? Not natively. The v2 schema is file-based and per-ref. Your practical options are: (a) create a new tag (e.g., v1.2.0.post1 or v1.2.0-docs) pointing at a commit that adds only the config file, and re-point the RTD version to it; (b) deactivate builds for the old tag and let stable track a newer ref; or (c) accept the fallback and verify the legacy docs still build. Rewriting an existing published tag is possible but breaks anyone who pinned to its hash — avoid it.
3. Banner and canonical URL with mixed interpreters? Neither assumes an interpreter. The version-warning banner is injected based on version type (e.g., tag vs. branch) and whether the version is the default; canonical URLs point at the project's default version. Both are decided at serve time from version metadata, independent of the build environment. Mixed interpreters across versions only matter if the generated HTML differs (e.g., an old Sphinx emitting markup your theme's banner injection doesn't expect).

Verification steps

1. Open the build log for the legacy tag and note the reported config path, image, and Python version.
2. Compare against a build of the default branch — any drift in image or interpreter is your exposure.
3. If the fallback looks wrong, check the project's dashboard build settings; if none are set, the value came from platform defaults and can change under you.
4. To make drift visible, trigger a rebuild of the old tag and diff the environment section of the log against the previous build.

Recommendation

For actively maintained projects, the cleanest fix is a docs-only tag carrying the same v2 config as the default branch, so every built ref resolves the same image and interpreter. If you must keep the original tag, capture the current fallback values from the build log now, and pin them at the project level if your dashboard allows — otherwise plan for the legacy build to break the next time platform defaults advance past what the old Sphinx/doc toolchain supports.