readthedocs.yaml or Admin UI for Build Configuration Precedence?

Question

Goal: choose a single source of truth for build configuration so that Python version and install steps are applied consistently, while still allowing immediate adjustments without a commit.

Read the Docs supports declarative configuration via readthedocs.yaml in the repository and imperative configuration through the project admin UI. The YAML file is versioned with the docs source; UI settings can be changed without a commit. The unresolved behavior is precedence: when both define the same setting, which one wins for a given platform release? Public documentation does not guarantee a stable order, and the outcome may differ by plan or version.

The constraint is reproducibility across builds versus operational flexibility. If the YAML file is authoritative, UI changes may be silently ignored or overridden. If the UI is authoritative, the repository configuration becomes advisory.

For a given Read the Docs release, does readthedocs.yaml override admin UI settings for Python version and install steps, or vice versa?
How can a project confirm which source is in effect without relying on a successful build outcome?
Does precedence vary between public and private projects or across plans?

Zoha · Answer

Configuration Precedence
When a readthedocs.yaml file is present in the root of the repository, it overrides the settings configured in the project Admin UI for build-related parameters, including the Python version and installation steps.
The YAML file serves as the authoritative source of truth. If a setting is defined in both the YAML file and the Admin UI, the value in the YAML file is applied. Admin UI settings act as a fallback mechanism and are only utilized if the YAML file is missing or contains syntax errors that prevent it from being parsed.

Verification Methods
To confirm which configuration source is active without waiting for a full build outcome, use the following methods:

Inspect Build Logs: Review the initial lines of the build log in the Read the Docs dashboard. The system typically logs whether a readthedocs.yaml file was detected and successfully loaded.
Cross-Reference Installation Steps: Add a unique, non-destructive command (e.g., echo "YAML_CONFIG_ACTIVE") to the install block of the YAML file and a different command to the Admin UI. The command appearing in the build logs confirms the active source.

Plan and Project Consistency
This precedence behavior is consistent across public and private projects, as well as across different pricing plans. The logic is tied to the build engine's configuration loader rather than the account type.

Operational Trade-offs
Because the YAML file is authoritative, immediate adjustments made via the Admin UI will be silently ignored if the corresponding setting exists in the repository. To allow the UI to take control of a specific setting, that setting must be removed from the readthedocs.yaml file and committed to the repository.

Required Diagnostic Detail
To provide a definitive confirmation of behavior for your specific environment, please verify if the project is using the modern build engine or the legacy system, as legacy systems may handle configuration fallback differently.

readthedocs.yaml or Admin UI for Build Configuration Precedence?

1 answer

Configuration Precedence

Verification Methods

Plan and Project Consistency

Operational Trade-offs

Required Diagnostic Detail

Your perspective belongs here.

0 question comments