Single Version or Multiple Versions on Read the Docs: A Decision Guide

Every Read the Docs project eventually hits the same question: should the site publish only the current documentation, or keep a browsable copy of every release? The answer affects build time, storage, navigation, and how easily users on older releases can find accurate docs. This guide lays out the constraints, compares the two supported approaches, and shows a working configuration you can validate in the dashboard.

The decision and its constraints

Read the Docs treats each activated branch or tag as a separate version. A version gets its own build, its own URL path (for example /en/stable/ or /en/v2.3.0/), and its own entry in the flyout version selector. Before choosing, weigh these constraints:

• Build time: each version builds independently, and builds are subject to a per-build time limit (commonly around 50 minutes on the community platform). Ten active versions means ten builds whenever you re-trigger them.
• Storage: public projects have a storage quota (commonly around 1 GB). HTML, PDF, and EPUB artifacts for every active version count against it. Exact limits can change, so check your project's dashboard rather than relying on these figures.
• Versioning scheme: multiple-version publishing only works well if your repository has a predictable tag or branch naming scheme (for example semantic-version tags like v2.3.0) that maps cleanly to URL slugs.
• Audience: libraries with users pinned to older releases need historical docs; internal tools and fast-moving services usually do not.

Comparing the two approaches

Factor	Single version (latest only)	Multiple versions (tags/branches)
Build time consumed	One build per commit	One build per active version
Storage usage	Minimal	Grows with each kept version and format
Historical docs	Lost; users on old releases see current docs	Preserved per tag or branch
Navigation	Simplest; no selector needed	Version selector in the flyout menu
Maintenance	Nothing extra	Activating/deactivating versions, pruning old ones
Best fit	Fast-moving apps, internal tools, single deployed release	Libraries and SDKs with semantic versioning and infrequent releases

Trade-offs in practice

A single version keeps you comfortably inside build and storage limits and removes ambiguity for readers — there is one URL and it is always current. The cost shows up when a user on release 1.x reads documentation for 2.x and files a confused bug report.

Multiple versions solve that problem but introduce two failure modes. First, quota pressure: keeping every tag plus PDF/EPUB formats can exhaust storage, and re-building many versions can hit time limits. Second, slug hygiene: version names become URL path segments, so tags with unusual characters may be sanitized into unexpected slugs, breaking external links you have already published.

A common middle ground for libraries is stable plus latest: activate only the stable branch (pointing at the newest release tag) and latest (the development branch), and activate older tags only when users genuinely need them. This preserves the most-requested historical docs without multiplying builds for every patch release.

Configuration example

The build itself is defined in .readthedocs.yaml at your repository root. Version activation is a separate step done in the Read the Docs dashboard (under Versions) or via automation rules — the YAML file controls how each version builds, not which versions exist.

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

sphinx:
  configuration: docs/conf.py

# Keep formats minimal to control storage usage.
# Drop pdf/epub if you are watching the storage quota.
formats:
  - htmlzip

python:
  install:
    - requirements: docs/requirements.txt
    - method: pip
      path: .

Commit this file to the branches and tags you intend to publish — each version builds from its own copy of the file, so a tag cut before the file existed will fail to build until you add it there or deactivate that version.

Then, in the Read the Docs dashboard:

1. Open your project and go to Versions.
2. Activate the tags or branches you want published (for example stable and v2.3.0); leave the rest inactive or hidden.
3. Under Settings, set the default version (commonly stable) so the root URL lands on released documentation rather than development docs.
4. Trigger a build and wait for each active version to finish.

Verifying the result

Two checks confirm the setup works:

• Dashboard: under Versions, every expected tag or branch appears as an active version, shows a passing build, and the default-version badge matches your setting.
• Built site: open the documentation, use the version selector in the flyout (usually bottom-left), and switch between versions. The URL should change to include the version slug (for example /en/stable/ versus /en/v2.3.0/) and the content should reflect that release — check a page you know differs between releases.

If a version is missing from the selector, confirm it is marked active (not hidden) in the dashboard and that its most recent build succeeded. If a build failed, the build log on the version's page is the first place to look — missing .readthedocs.yaml on old tags and exceeded time or storage limits are the usual causes.

Limitations to keep in mind

Build-time and storage quotas are platform settings that can change; treat the figures here as typical, not guaranteed, and confirm against your project's dashboard. Deactivating a version removes its hosted docs, which breaks any external links to that slug — prefer hiding over deleting for versions users may still reference. Finally, the version selector's appearance depends on your Sphinx theme; the standard Read the Docs theme shows it by default, but custom themes may need configuration.