CINXE.COM

<!DOCTYPE html> <html class="writer-html5" lang="en" data-content_root="./"> <head> <meta charset="utf-8" /> <meta name="readthedocs-addons-api-version" content="1"><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta property="og:title" content="Versions" /> <meta property="og:type" content="website" /> <meta property="og:url" content="https://docs.readthedocs.com/platform/stable/versions.html" /> <meta property="og:site_name" content="Read the Docs Documentation" /> <meta property="og:description" content="Read the Docs supports publishing multiple versions of your documentation. This allows your users to read the exact documentation for the specific version of the project they are using. Versioning is useful for many reasons, but a few common use cases are: Shipping API client libraries that relea..." /> <meta property="og:image" content="https://docs.readthedocs.io/en/latest/_static/img/logo-opengraph.png" /> <meta property="og:image:alt" content="Read the Docs Documentation" /> <meta name="description" content="Read the Docs supports publishing multiple versions of your documentation. This allows your users to read the exact documentation for the specific version of the project they are using. Versioning is useful for many reasons, but a few common use cases are: Shipping API client libraries that relea..." /> <meta name="twitter:card" content="summary_large_image" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Versions — Read the Docs user documentation</title> <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" /> <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" /> <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" /> <link rel="stylesheet" type="text/css" href="_static/sphinx-design.min.css?v=95c83b7e" /> <link rel="stylesheet" type="text/css" href="_static/css/custom.css?v=da32ccdd" /> <link rel="stylesheet" type="text/css" href="_static/css/sphinx_prompt_css.css?v=351d85e3" /> <link rel="canonical" href="https://docs.readthedocs.com/platform/stable/versions.html" /> <script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/documentation_options.js?v=ef5a3e6d"></script> <script src="_static/doctools.js?v=9bcbadda"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/clipboard.min.js?v=a7894cd8"></script> <script src="_static/copybutton.js?v=f281be69"></script> <script src="_static/design-tabs.js?v=f930bc37"></script> <script src="_static/js/expand_tabs.js?v=1e151f68"></script> <script src="_static/js/theme.js"></script> <script src="_static/js/versions.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Subprojects" href="subprojects.html" /> <link rel="prev" title="Environment variable reference" href="reference/environment-variables.html" /> <script defer data-domain="docs.readthedocs.io" src="https://plausible.io/js/script.js"></script> <script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="docs" /><meta name="readthedocs-version-slug" content="stable" /><meta name="readthedocs-resolver-filename" content="/versions.html" /><meta name="readthedocs-http-status" content="200" /></head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="index.html"> <img src="_static/logo.svg" class="logo" alt="Logo"/> </a> <div class="switch-menus"> <div class="version-switch"></div> <div class="language-switch"></div> </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> <p class="caption" role="heading"><span class="caption-text">Getting started</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Tutorial</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/add-project.html">Adding a documentation project</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/doctools.html">Popular documentation tools</a></li> <li class="toctree-l1"><a class="reference internal" href="examples.html">Example projects</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Project setup and configuration</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="config-file/index.html">Configuration file overview</a></li> <li class="toctree-l1"><a class="reference internal" href="config-file/v2.html">Configuration file reference</a></li> <li class="toctree-l1"><a class="reference internal" href="addons.html">Read the Docs Addons</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/accounts.html">Account authentication methods</a></li> <li class="toctree-l1"><a class="reference internal" href="automation-rules.html">Automation rules</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/reproducible-builds.html">How to create reproducible builds</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Build process</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="builds.html">Build process overview</a></li> <li class="toctree-l1"><a class="reference internal" href="build-customization.html">Build process customization</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/git-integration.html">Git integration (GitHub, GitLab, Bitbucket)</a></li> <li class="toctree-l1"><a class="reference internal" href="pull-requests.html">Pull request previews</a></li> <li class="toctree-l1"><a class="reference internal" href="build-notifications.html">Build failure notifications</a></li> <li class="toctree-l1"><a class="reference internal" href="environment-variables.html">Environment variable overview</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/environment-variables.html">Environment variable reference</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Hosting documentation</span></p> <ul class="current"> <li class="toctree-l1 current"><a class="current reference internal" href="#">Versions</a><ul> <li class="toctree-l2"><a class="reference internal" href="#versions-are-git-tags-and-branches">Versions are Git tags and branches</a></li> <li class="toctree-l2"><a class="reference internal" href="#version-states">Version states</a></li> <li class="toctree-l2"><a class="reference internal" href="#version-syncing">Version syncing</a></li> <li class="toctree-l2"><a class="reference internal" href="#managing-your-versions">Managing your versions</a></li> <li class="toctree-l2"><a class="reference internal" href="#disabling-versioning-completely">Disabling versioning completely</a></li> <li class="toctree-l2"><a class="reference internal" href="#version-warning-notifications">Version warning notifications</a></li> <li class="toctree-l2"><a class="reference internal" href="#redirects-on-root-urls">Redirects on root URLs</a></li> <li class="toctree-l2"><a class="reference internal" href="#versioning-workflows">Versioning workflows</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="subprojects.html">Subprojects</a></li> <li class="toctree-l1"><a class="reference internal" href="localization.html">Localization and Internationalization</a></li> <li class="toctree-l1"><a class="reference internal" href="versioning-schemes.html">URL versioning schemes</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-domains.html">Custom domains</a></li> <li class="toctree-l1"><a class="reference internal" href="doc-notifications.html">Documentation notifications</a></li> <li class="toctree-l1"><a class="reference internal" href="canonical-urls.html">Canonical URLs</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/cdn.html">Content Delivery Network (CDN) and caching</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/sitemaps.html">Sitemap support</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/404-not-found.html"><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code> pages</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/robots.html"><code class="docutils literal notranslate"><span class="pre">robots.txt</span></code> support</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Reading documentation</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="downloadable-documentation.html">Offline formats (PDF, ePub, HTML)</a></li> <li class="toctree-l1"><a class="reference internal" href="visual-diff.html">Visual diff</a></li> <li class="toctree-l1"><a class="reference internal" href="link-previews.html">Link previews</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/embedding-content.html">How to embed content from your documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="server-side-search/index.html">Server side search</a></li> <li class="toctree-l1"><a class="reference internal" href="server-side-search/syntax.html">Search query syntax</a></li> <li class="toctree-l1"><a class="reference internal" href="flyout-menu.html">Flyout menu</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Maintaining projects</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="user-defined-redirects.html">Redirects</a></li> <li class="toctree-l1"><a class="reference internal" href="traffic-analytics.html">Traffic analytics</a></li> <li class="toctree-l1"><a class="reference internal" href="search-analytics.html">Search analytics</a></li> <li class="toctree-l1"><a class="reference internal" href="security-log.html">Security logs</a></li> <li class="toctree-l1"><a class="reference internal" href="badges.html">Status badges</a></li> <li class="toctree-l1"><a class="reference internal" href="explanation/documentation-structure.html">How to structure your documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/best-practice/links.html">Best practices for linking to your documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="security-implications.html">Security considerations for documentation pages</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Business features</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="commercial/index.html">Business hosting</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/organizations.html">Organizations</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/single-sign-on.html">Single Sign-On (SSO)</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/sharing.html">Sharing private documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/subscriptions.html">How to manage your subscription</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/privacy-level.html">Privacy levels</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">How-to guides</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="guides/setup/index.html">Project setup and configuration</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/build/index.html">Build process</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/maintenance/index.html">Upgrading and maintaining projects</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/content/index.html">Content, themes and SEO</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/access/index.html">Security and access</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/management/index.html">Account management</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/best-practice/index.html">Best practice</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/troubleshooting/index.html">Troubleshooting problems</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Reference</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="api/index.html">Public REST API</a></li> <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently asked questions</a></li> <li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li> <li class="toctree-l1"><a class="reference internal" href="about/index.html">About Read the Docs</a></li> <li class="toctree-l1"><a class="reference external" href="https://dev.readthedocs.io">Developer Documentation</a></li> <li class="toctree-l1"><a class="reference external" href="https://about.readthedocs.com">Read the Docs website</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="index.html">Read the Docs user documentation</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item active">Versions</li> <li class="wy-breadcrumbs-aside"> <a href="https://github.com/readthedocs/readthedocs.org/blob/main/docs/user/versions.rst" class="fa fa-github"> Edit on GitHub</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="versions"> <h1>Versions<a class="headerlink" href="#versions" title="Link to this heading"></a></h1> <p>Read the Docs supports publishing multiple versions of your documentation. This allows your users to read the exact documentation for the specific version of the project they are using.</p> <p>Versioning is useful for many reasons, but a few common use cases are:</p> <ul class="simple"> <li><p>Shipping API client libraries that release versions across time.</p></li> <li><p>Having a “stable” and “latest” branch so that users can see the current release and the upcoming changes.</p></li> <li><p>Having a private development branch and a public stable branch so that in development releases aren’t accidentally seen by users until they are released.</p></li> </ul> <section id="versions-are-git-tags-and-branches"> <h2>Versions are Git tags and branches<a class="headerlink" href="#versions-are-git-tags-and-branches" title="Link to this heading"></a></h2> <p>When you add a project to Read the Docs, all Git tags and branches are created as <strong>Inactive</strong> and <strong>Not Hidden</strong> versions by default. During initial setup, Read the Docs also creates a <code class="docutils literal notranslate"><span class="pre">latest</span></code> version that points to the default branch defined in your Git repository (usually <code class="docutils literal notranslate"><span class="pre">main</span></code>). This version should always exist and is the default version for your project.</p> <p>If your project has any tags or branches with a name following <a class="reference external" href="https://semver.org/">semantic versioning</a> (with or without a <code class="docutils literal notranslate"><span class="pre">v</span></code> prefix), we also create a <code class="docutils literal notranslate"><span class="pre">stable</span></code> version tracking your most recent release. If you want a custom <code class="docutils literal notranslate"><span class="pre">stable</span></code> version, create either a tag or branch in your project with that name.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>If you have at least one tag, tags will take preference over branches when selecting the stable version.</p> </div> <p>When you have <a class="reference internal" href="reference/git-integration.html"><span class="doc">Git integration (GitHub, GitLab, Bitbucket)</span></a> configured for your repository, we will automatically build each version when you push a commit.</p> </section> <section id="version-states"> <h2>Version states<a class="headerlink" href="#version-states" title="Link to this heading"></a></h2> <p>Each version of your documentation has a state that changes the visibility of it to other users.</p> <dl> <dt><strong>Active</strong> or <strong>Inactive</strong></dt><dd><ul class="simple"> <li><p><strong>Active</strong> docs are visible, and builds can be triggered for the documentation.</p></li> <li><p><strong>Inactive</strong> versions <em>have their documentation content deleted</em> and builds cannot be triggered.</p></li> </ul> </dd> <dt><strong>Hidden</strong> or <strong>Not hidden</strong></dt><dd><ul class="simple"> <li><p><strong>Not hidden</strong> docs are listed on the <a class="reference internal" href="glossary.html#term-flyout-menu"><span class="xref std std-term">flyout menu</span></a> on the docs site and are shown in search results.</p></li> <li><p><strong>Hidden</strong> docs are not listed on the <a class="reference internal" href="glossary.html#term-flyout-menu"><span class="xref std std-term">flyout menu</span></a> on the docs site and are not shown in search results.</p></li> </ul> <p>Hiding a version doesn’t make it private, any user with a link to its docs can still see it. This is useful when:</p> <ul class="simple"> <li><p>You no longer support a version, but you don’t want to remove its docs.</p></li> <li><p>You have a work in progress version and don’t want to publish its docs just yet.</p></li> </ul> <p>Hidden versions are listed as <code class="docutils literal notranslate"><span class="pre">Disallow:</span> <span class="pre">/path/to/version/</span></code> in the default <a class="reference internal" href="reference/robots.html"><span class="doc">robots.txt support</span></a> created by Read the Docs.</p> </dd> <dt><strong>Public</strong> or <strong>Private</strong> (only available on on <a class="reference internal" href="commercial/index.html"><span class="doc">Business hosting</span></a>)</dt><dd><ul> <li><p><strong>Public</strong> versions are visible to everyone, and are browsable by unauthenticated users.</p></li> <li><p><strong>Private</strong> versions are available only to people who have permissions to see them. They will return a <code class="xref py py-obj docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code> when visited by people without viewing permissions. If you want to share your docs temporarily, see <a class="reference internal" href="commercial/sharing.html"><span class="doc">Sharing private documentation</span></a>.</p> <p>If you want unauthenticated people to be able to view the build page of your public versions, you’ll need to the set the <a class="reference internal" href="commercial/privacy-level.html"><span class="doc">privacy level of your project</span></a> to public.</p> </li> </ul> </dd> </dl> </section> <section id="version-syncing"> <h2>Version syncing<a class="headerlink" href="#version-syncing" title="Link to this heading"></a></h2> <p>Versions are automatically synced when the following events happen:</p> <ul class="simple"> <li><p>A commit is pushed to your Git repository and you have a <a class="reference internal" href="reference/git-integration.html"><span class="doc">Git integration</span></a> configured.</p></li> <li><p>A build for any of your version is triggered.</p></li> </ul> <p>If you find that your versions are out of date, triggering a build is the best approach to ensuring they are synced again.</p> </section> <section id="managing-your-versions"> <h2>Managing your versions<a class="headerlink" href="#managing-your-versions" title="Link to this heading"></a></h2> <p>When you activate a version, a <a class="reference internal" href="builds.html"><span class="doc">build</span></a> will be triggered to automatically deploy your documentation.</p> <p>When you deactivate a version, all of the artifacts of your version will be deleted and a <code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code> page will be served for it.</p> <p>You can change the state for each version of your documentation in the <span class="guilabel">Versions</span> tab of your project.</p> </section> <section id="disabling-versioning-completely"> <h2>Disabling versioning completely<a class="headerlink" href="#disabling-versioning-completely" title="Link to this heading"></a></h2> <p>You can <a class="reference internal" href="versioning-schemes.html"><span class="doc">configure a single version project</span></a>, and the version will be hidden from the URL.</p> </section> <section id="version-warning-notifications"> <h2>Version warning notifications<a class="headerlink" href="#version-warning-notifications" title="Link to this heading"></a></h2> <p>As part of <a class="reference internal" href="addons.html"><span class="doc">Read the Docs Addons</span></a>, Read the Docs displays notifications in the following situations:</p> <dl> <dt>Non-stable notification</dt><dd><p>A notification on all non-stable versions is shown to clearly communicate to readers they may be reading an outdated version of the documentation.</p> <p>Specifically, when a version is being shown that is not the <code class="docutils literal notranslate"><span class="pre">stable</span></code> version, and there is a <code class="docutils literal notranslate"><span class="pre">stable</span></code> version available.</p> </dd> <dt>Latest version notification</dt><dd><p>A notification shown on the latest version tells readers they are reading the latest/development version of the documentation that may include features not yet deployed.</p> <p>Specifically, when the <code class="docutils literal notranslate"><span class="pre">latest</span></code> version is being shown, and there’s also an active <code class="docutils literal notranslate"><span class="pre">stable</span></code> version that is not hidden.</p> </dd> </dl> <p>Each of these notifications can be configured by project admins in <a class="reference internal" href="addons.html#configuring-read-the-docs-addons"><span class="std std-ref">Configuring Read the Docs Addons</span></a>.</p> </section> <section id="redirects-on-root-urls"> <h2>Redirects on root URLs<a class="headerlink" href="#redirects-on-root-urls" title="Link to this heading"></a></h2> <p>When a user hits the root URL for your documentation, for example <code class="docutils literal notranslate"><span class="pre">https://pip.readthedocs.io/</span></code>, they will be redirected to the <strong>Default version</strong>. This defaults to <strong>latest</strong>, but another common configuration is setting it to your <strong>stable</strong> version.</p> </section> <section id="versioning-workflows"> <h2>Versioning workflows<a class="headerlink" href="#versioning-workflows" title="Link to this heading"></a></h2> <p>Read the Docs makes certain assumptions about your documentation version defaults, all of which can be reconfigured if necessary:</p> <ul> <li><p>The <code class="docutils literal notranslate"><span class="pre">latest</span></code> version points to the most up to date development code. If you develop on a branch that is different than the default for your version control system, set the <strong>Default Branch</strong> to the branch you use.</p></li> <li><p><strong>Tags</strong> are semantic versioning compatible (according to <a class="reference external" href="https://www.python.org/dev/peps/pep-0440/">PEP 440</a>) snapshots of your documentation. The most recent semantic tag maps to the <code class="docutils literal notranslate"><span class="pre">stable</span></code> version.</p> <p>Semantic versioning allows “normal” version numbers like <code class="docutils literal notranslate"><span class="pre">1.4.2</span></code>, as well as pre-releases like this: <code class="docutils literal notranslate"><span class="pre">2.0a1</span></code>. The <code class="docutils literal notranslate"><span class="pre">stable</span></code> version of your documentation never includes a pre-release. An optional <code class="docutils literal notranslate"><span class="pre">v</span></code> prefix like <code class="docutils literal notranslate"><span class="pre">v1.4.2</span></code> or <code class="docutils literal notranslate"><span class="pre">v2.0a1</span></code> is also allowed.</p> </li> <li><p>Branches are assumed to be <strong>long-lived branches</strong>, This is most useful for <strong>release branches</strong>, which are maintained over time for a specific release. An example would be a <code class="docutils literal notranslate"><span class="pre">2.1</span></code> branch that is kept up to date with the latest <code class="docutils literal notranslate"><span class="pre">2.1.x</span></code> release.</p></li> </ul> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="reference/environment-variables.html" class="btn btn-neutral float-left" title="Environment variable reference" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="subprojects.html" class="btn btn-neutral float-right" title="Subprojects" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> </div> <hr/> <div role="contentinfo"> <p>© Copyright Read the Docs, Inc & contributors.</p> </div> Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>