CINXE.COM

<!doctype html> <html class="no-js" lang="en" data-content_root="../../"> <head><meta charset="utf-8"/> <meta name="viewport" content="width=device-width,initial-scale=1"/> <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" /> <link rel="index" title="Index" href="../../genindex/" /><link rel="search" title="Search" href="../../search/" /><link rel="next" title="Deploying Python applications" href="../deploying-python-applications/" /><link rel="prev" title="Discussions" href="../" /> <link rel="shortcut icon" href="../../_static/py.png"/> <title>Versioning - Python Packaging User Guide</title> <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=8f2a1f02" /> <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?v=354aac6f" /> <link rel="stylesheet" type="text/css" href="../../_static/tabs.css?v=4c969af8" /> <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css?v=76b2166b" /> <link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?v=302659d7" /> <style> body { --color-code-background: #f8f8f8; --color-code-foreground: black; } @media not print { body[data-theme="dark"] { --color-code-background: #202020; --color-code-foreground: #d0d0d0; } @media (prefers-color-scheme: dark) { body:not([data-theme="light"]) { --color-code-background: #202020; --color-code-foreground: #d0d0d0; } } } </style><script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="python-packaging-user-guide" /><meta name="readthedocs-version-slug" content="latest" /><meta name="readthedocs-resolver-filename" content="/discussions/versioning/" /><meta name="readthedocs-http-status" content="200" /></head> <body> <script> document.body.dataset.theme = localStorage.getItem("theme") || "auto"; </script> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-toc" viewBox="0 0 24 24"> <title>Contents</title> <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024"> <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line> <line x1="3" y1="6" x2="21" y2="6"></line> <line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24"> <title>Light mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24"> <title>Dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon"> <path stroke="none" d="M0 0h24v24H0z" fill="none" /> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" /> </svg> </symbol> <symbol id="svg-sun-with-moon" viewBox="0 0 24 24"> <title>Auto light/dark, in light mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-custom-derived-from-feather-sun-and-tabler-moon"> <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/> <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/> <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/> <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/> <line x1="19" y1="14.05" x2="20.414" y2="15.464"/> <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/> <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/> <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/> <line x1="19" y1="5.05" x2="20.414" y2="3.636"/> <circle cx="14.5" cy="9.55" r="3.6"/> </svg> </symbol> <symbol id="svg-moon-with-sun" viewBox="0 0 24 24"> <title>Auto light/dark, in dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-custom-derived-from-feather-sun-and-tabler-moon"> <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/> <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/> <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/> <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/> <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/> <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/> <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/> <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/> <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/> <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/> </svg> </symbol> <symbol id="svg-pencil" viewBox="0 0 24 24"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code"> <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" /> <path d="M13.5 6.5l4 4" /> <path d="M20 21l2 -2l-2 -2" /> <path d="M17 17l-2 2l2 2" /> </svg> </symbol> <symbol id="svg-eye" viewBox="0 0 24 24"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code"> <path stroke="none" d="M0 0h24v24H0z" fill="none" /> <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" /> <path d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" /> <path d="M20 21l2 -2l-2 -2" /> <path d="M17 17l-2 2l2 2" /> </svg> </symbol> </svg> <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation"> <input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc"> <label class="overlay sidebar-overlay" for="__navigation"> <div class="visually-hidden">Hide navigation sidebar</div> </label> <label class="overlay toc-overlay" for="__toc"> <div class="visually-hidden">Hide table of contents sidebar</div> </label> <a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a> <div class="page"> <header class="mobile-header"> <div class="header-left"> <label class="nav-overlay-icon" for="__navigation"> <div class="visually-hidden">Toggle site navigation sidebar</div> <i class="icon"><svg><use href="#svg-menu"></use></svg></i> </label> </div> <div class="header-center"> <a href="../../"><div class="brand">Python Packaging User Guide</div></a> </div> <div class="header-right"> <div class="theme-toggle-container theme-toggle-header"> <button class="theme-toggle"> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> </button> </div> <label class="toc-overlay-icon toc-header-icon" for="__toc"> <div class="visually-hidden">Toggle table of contents sidebar</div> <i class="icon"><svg><use href="#svg-toc"></use></svg></i> </label> </div> </header> <aside class="sidebar-drawer"> <div class="sidebar-container"> <div class="sidebar-sticky"><a class="sidebar-brand" href="../../"> <span class="sidebar-brand-text">Python Packaging User Guide</span> </a><form class="sidebar-search-container" method="get" action="../../search/" role="search"> <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search"> <input type="hidden" name="check_keywords" value="yes"> <input type="hidden" name="area" value="default"> </form> <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree"> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="../../overview/">Overview of Python Packaging</a></li> <li class="toctree-l1"><a class="reference internal" href="../../flow/">The Packaging Flow</a></li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../tutorials/">Tutorials</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Tutorials</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../tutorials/installing-packages/">Installing Packages</a></li> <li class="toctree-l2"><a class="reference internal" href="../../tutorials/managing-dependencies/">Managing Application Dependencies</a></li> <li class="toctree-l2"><a class="reference internal" href="../../tutorials/packaging-projects/">Packaging Python Projects</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../guides/">Guides</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Guides</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2 has-children"><a class="reference internal" href="../../guides/section-install/">Installation</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle navigation of Installation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../guides/installing-using-pip-and-virtual-environments/">Install packages in a virtual environment using pip and venv</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/installing-using-virtualenv/">Installing packages using virtualenv</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/installing-stand-alone-command-line-tools/">Installing stand alone command line tools</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/installing-using-linux-tools/">Installing pip/setuptools/wheel with Linux Package Managers</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/installing-scientific-packages/">Installing scientific packages</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../guides/section-build-and-publish/">Building and Publishing</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" role="switch" type="checkbox"/><label for="toctree-checkbox-4"><div class="visually-hidden">Toggle navigation of Building and Publishing</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../guides/writing-pyproject-toml/">Writing your <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/distributing-packages-using-setuptools/">Packaging and distributing projects</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/dropping-older-python-versions/">Dropping support for older Python versions</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/packaging-binary-extensions/">Packaging binary extensions</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/packaging-namespace-packages/">Packaging namespace packages</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/creating-command-line-tools/">Creating and packaging command-line tools</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/creating-and-discovering-plugins/">Creating and discovering plugins</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/using-testpypi/">Using TestPyPI</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/making-a-pypi-friendly-readme/">Making a PyPI-friendly README</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/">Publishing package distribution releases using GitHub Actions CI/CD workflows</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/modernize-setup-py-project/">How to modernize a <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> based project?</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/licensing-examples-and-user-scenarios/">Licensing examples and user scenarios</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../guides/section-hosting/">Hosting</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" role="switch" type="checkbox"/><label for="toctree-checkbox-5"><div class="visually-hidden">Toggle navigation of Hosting</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../guides/index-mirrors-and-caches/">Package index mirrors and caches</a></li> <li class="toctree-l3"><a class="reference internal" href="../../guides/hosting-your-own-index/">Hosting your own simple repository</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="../../guides/tool-recommendations/">Tool recommendations</a></li> <li class="toctree-l2"><a class="reference internal" href="../../guides/analyzing-pypi-package-downloads/">Analyzing PyPI package downloads</a></li> </ul> </li> <li class="toctree-l1 current has-children"><a class="reference internal" href="../">Discussions</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" role="switch" type="checkbox"/><label for="toctree-checkbox-6"><div class="visually-hidden">Toggle navigation of Discussions</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current"> <li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Versioning</a></li> <li class="toctree-l2"><a class="reference internal" href="../deploying-python-applications/">Deploying Python applications</a></li> <li class="toctree-l2"><a class="reference internal" href="../pip-vs-easy-install/">pip vs easy_install</a></li> <li class="toctree-l2"><a class="reference internal" href="../install-requires-vs-requirements/">install_requires vs requirements files</a></li> <li class="toctree-l2"><a class="reference internal" href="../distribution-package-vs-import-package/">Distribution package vs. import package</a></li> <li class="toctree-l2"><a class="reference internal" href="../package-formats/">Package Formats</a></li> <li class="toctree-l2"><a class="reference internal" href="../src-layout-vs-flat-layout/">src layout vs flat layout</a></li> <li class="toctree-l2"><a class="reference internal" href="../setup-py-deprecated/">Is <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> deprecated?</a></li> <li class="toctree-l2"><a class="reference internal" href="../single-source-version/">Single-sourcing the Project Version</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../specifications/">PyPA specifications</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" role="switch" type="checkbox"/><label for="toctree-checkbox-7"><div class="visually-hidden">Toggle navigation of PyPA specifications</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2 has-children"><a class="reference internal" href="../../specifications/section-distribution-metadata/">Package Distribution Metadata</a><input class="toctree-checkbox" id="toctree-checkbox-8" name="toctree-checkbox-8" role="switch" type="checkbox"/><label for="toctree-checkbox-8"><div class="visually-hidden">Toggle navigation of Package Distribution Metadata</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../specifications/name-normalization/">Names and normalization</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/core-metadata/">Core metadata specifications</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/version-specifiers/">Version specifiers</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/dependency-specifiers/">Dependency specifiers</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/pyproject-toml/"><code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> specification</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/dependency-groups/">Dependency Groups</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/inline-script-metadata/">Inline script metadata</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/platform-compatibility-tags/">Platform compatibility tags</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/well-known-project-urls/">Well-known Project URLs in Metadata</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../specifications/section-installation-metadata/">Package Installation Metadata</a><input class="toctree-checkbox" id="toctree-checkbox-9" name="toctree-checkbox-9" role="switch" type="checkbox"/><label for="toctree-checkbox-9"><div class="visually-hidden">Toggle navigation of Package Installation Metadata</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../specifications/recording-installed-packages/">Recording installed projects</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/entry-points/">Entry points specification</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/direct-url/">Recording the Direct URL Origin of installed distributions</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/direct-url-data-structure/">Direct URL Data Structure</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/virtual-environments/">Python Virtual Environments</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/externally-managed-environments/">Externally Managed Environments</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../specifications/section-distribution-formats/">Package Distribution File Formats</a><input class="toctree-checkbox" id="toctree-checkbox-10" name="toctree-checkbox-10" role="switch" type="checkbox"/><label for="toctree-checkbox-10"><div class="visually-hidden">Toggle navigation of Package Distribution File Formats</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../specifications/source-distribution-format/">Source distribution format</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/binary-distribution-format/">Binary distribution format</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../specifications/section-package-indices/">Package Index Interfaces</a><input class="toctree-checkbox" id="toctree-checkbox-11" name="toctree-checkbox-11" role="switch" type="checkbox"/><label for="toctree-checkbox-11"><div class="visually-hidden">Toggle navigation of Package Index Interfaces</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../specifications/pypirc/">The <code class="file docutils literal notranslate"><span class="pre">.pypirc</span></code> file</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/simple-repository-api/">Simple repository API</a></li> <li class="toctree-l3"><a class="reference internal" href="../../specifications/index-hosted-attestations/">Index hosted attestations</a></li> </ul> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../../key_projects/">Project Summaries</a></li> <li class="toctree-l1"><a class="reference internal" href="../../glossary/">Glossary</a></li> <li class="toctree-l1"><a class="reference internal" href="../../support/">How to Get Support</a></li> <li class="toctree-l1"><a class="reference internal" href="../../contribute/">Contribute to this guide</a></li> <li class="toctree-l1"><a class="reference internal" href="../../news/">News</a></li> </ul> </div> </div> </div> </div> </aside> <div class="main"> <div class="content"> <div class="article-container"> <a href="#" class="back-to-top muted-link"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"> <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path> </svg> <span>Back to top</span> </a> <div class="content-icon-container"> <div class="view-this-page"> <a class="muted-link" href="https://github.com/pypa/packaging.python.org/blob/main/source/discussions/versioning.rst?plain=true" title="View this page"> <svg><use href="#svg-eye"></use></svg> <span class="visually-hidden">View this page</span> </a> </div><div class="edit-this-page"> <a class="muted-link" href="https://github.com/pypa/packaging.python.org/edit/main/source/discussions/versioning.rst" title="Edit this page"> <svg><use href="#svg-pencil"></use></svg> <span class="visually-hidden">Edit this page</span> </a> </div><div class="theme-toggle-container theme-toggle-content"> <button class="theme-toggle"> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> </button> </div> <label class="toc-overlay-icon toc-content-icon" for="__toc"> <div class="visually-hidden">Toggle table of contents sidebar</div> <i class="icon"><svg><use href="#svg-toc"></use></svg></i> </label> </div> <article role="main" id="furo-main-content"> <section id="choosing-a-versioning-scheme"> <span id="versioning"></span><span id="id1"></span><h1>Versioning<a class="headerlink" href="#choosing-a-versioning-scheme" title="Link to this heading">¶</a></h1> <p>This discussion covers all aspects of versioning Python packages.</p> <section id="valid-version-numbers"> <h2>Valid version numbers<a class="headerlink" href="#valid-version-numbers" title="Link to this heading">¶</a></h2> <p>Different Python projects may use different versioning schemes based on the needs of that particular project, but in order to be compatible with tools like <a class="reference internal" href="../../key_projects/#pip"><span class="std std-ref">pip</span></a>, all of them are required to comply with a flexible format for version identifiers, for which the authoritative reference is the <a class="reference internal" href="../../specifications/version-specifiers/#version-specifiers"><span class="std std-ref">specification of version specifiers</span></a>. Here are some examples of version numbers <a class="footnote-reference brackets" href="#version-examples" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>:</p> <ul class="simple"> <li><p>A simple version (final release): <code class="docutils literal notranslate"><span class="pre">1.2.0</span></code></p></li> <li><p>A development release: <code class="docutils literal notranslate"><span class="pre">1.2.0.dev1</span></code></p></li> <li><p>An alpha release: <code class="docutils literal notranslate"><span class="pre">1.2.0a1</span></code></p></li> <li><p>A beta release: <code class="docutils literal notranslate"><span class="pre">1.2.0b1</span></code></p></li> <li><p>A release candidate: <code class="docutils literal notranslate"><span class="pre">1.2.0rc1</span></code></p></li> <li><p>A post-release: <code class="docutils literal notranslate"><span class="pre">1.2.0.post1</span></code></p></li> <li><p>A post-release of an alpha release (possible, but discouraged): <code class="docutils literal notranslate"><span class="pre">1.2.0a1.post1</span></code></p></li> <li><p>A simple version with only two components: <code class="docutils literal notranslate"><span class="pre">23.12</span></code></p></li> <li><p>A simple version with just one component: <code class="docutils literal notranslate"><span class="pre">42</span></code></p></li> <li><p>A version with an epoch: <code class="docutils literal notranslate"><span class="pre">1!1.0</span></code></p></li> </ul> <p>Projects can use a cycle of pre-releases to support testing by their users before a final release. In order, the steps are: alpha releases, beta releases, release candidates, final release. Pip and other modern Python package installers ignore pre-releases by default when deciding which versions of dependencies to install, unless explicitly requested (e.g., with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">pkg==1.1a3</span></code> or <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">--pre</span> <span class="pre">pkg</span></code>).</p> <p>The purpose of development releases is to support releases made early during a development cycle, for example, a nightly build, or a build from the latest source in a Linux distribution.</p> <p>Post-releases are used to address minor errors in a final release that do not affect the distributed software, such as correcting an error in the release notes. They should not be used for bug fixes; these should be done with a new final release (e.g., incrementing the third component when using semantic versioning).</p> <p>Finally, epochs, a rarely used feature, serve to fix the sorting order when changing the versioning scheme. For example, if a project is using calendar versioning, with versions like 23.12, and switches to semantic versioning, with versions like 1.0, the comparison between 1.0 and 23.12 will go the wrong way. To correct this, the new version numbers should have an explicit epoch, as in “1!1.0”, in order to be treated as more recent than the old version numbers.</p> </section> <section id="semantic-versioning-vs-calendar-versioning"> <h2>Semantic versioning vs. calendar versioning<a class="headerlink" href="#semantic-versioning-vs-calendar-versioning" title="Link to this heading">¶</a></h2> <p>A versioning scheme is a formalized way to interpret the segments of a version number, and to decide which should be the next version number for a new release of a package. Two versioning schemes are commonly used for Python packages, semantic versioning and calendar versioning.</p> <div class="admonition caution"> <p class="admonition-title">Caution</p> <p>The decision which version number to choose is up to a project’s maintainer. This effectively means that version bumps reflect the maintainer’s view. That view may differ from the end-users’ perception of what said formalized versioning scheme promises them.</p> <p>There are known exceptions for selecting the next version number. The maintainers may consciously choose to break the assumption that the last version segment only contains backwards-compatible changes. One such case is when security vulnerability needs to be addressed. Security releases often come in patch versions but contain breaking changes inevitably.</p> </div> <section id="semantic-versioning"> <h3>Semantic versioning<a class="headerlink" href="#semantic-versioning" title="Link to this heading">¶</a></h3> <p>The idea of <em>semantic versioning</em> (or SemVer) is to use 3-part version numbers, <em>major.minor.patch</em>, where the project author increments:</p> <ul class="simple"> <li><p><em>major</em> when they make incompatible API changes,</p></li> <li><p><em>minor</em> when they add functionality in a backwards-compatible manner, and</p></li> <li><p><em>patch</em>, when they make backwards-compatible bug fixes.</p></li> </ul> <p>A majority of Python projects use a scheme that resembles semantic versioning. However, most projects, especially larger ones, do not strictly adhere to semantic versioning, since many changes are technically breaking changes but affect only a small fraction of users. Such projects tend to increment the major number when the incompatibility is high, or to signal a shift in the project, rather than for any tiny incompatibility <a class="footnote-reference brackets" href="#semver-strictness" id="id3" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a>. Conversely, a bump of the major version number is sometimes used to signal significant but backwards-compatible new features.</p> <p>For those projects that do use strict semantic versioning, this approach allows users to make use of <a class="reference internal" href="../../specifications/version-specifiers/#version-specifiers-compatible-release"><span class="std std-ref">compatible release version specifiers</span></a>, with the <code class="docutils literal notranslate"><span class="pre">~=</span></code> operator. For example, <code class="docutils literal notranslate"><span class="pre">name</span> <span class="pre">~=</span> <span class="pre">X.Y</span></code> is roughly equivalent to <code class="docutils literal notranslate"><span class="pre">name</span> <span class="pre">>=</span> <span class="pre">X.Y,</span> <span class="pre">==</span> <span class="pre">X.*</span></code>, i.e., it requires at least release X.Y, and allows any later release with greater Y as long as X is the same. Likewise, <code class="docutils literal notranslate"><span class="pre">name</span> <span class="pre">~=</span> <span class="pre">X.Y.Z</span></code> is roughly equivalent to <code class="docutils literal notranslate"><span class="pre">name</span> <span class="pre">>=</span> <span class="pre">X.Y.Z,</span> <span class="pre">==</span> <span class="pre">X.Y.*</span></code>, i.e., it requires at least X.Y.Z and allows a later release with same X and Y but higher Z.</p> <p>Python projects adopting semantic versioning should abide by clauses 1-8 of the <a class="reference external" href="https://semver.org">Semantic Versioning 2.0.0 specification</a>.</p> <p>The popular <a class="reference external" href="https://www.sphinx-doc.org/en/master/index.html" title="(in Sphinx v8.2.0)"><span class="xref std std-doc">Sphinx</span></a> documentation generator is an example project that uses strict semantic versioning (<a class="reference external" href="https://www.sphinx-doc.org/en/master/internals/release-process.html" title="(in Sphinx v8.2.0)"><span class="xref std std-doc">Sphinx versioning policy</span></a>). The famous <a class="reference external" href="https://numpy.org/doc/stable/index.html" title="(in NumPy v2.2)"><span class="xref std std-doc">NumPy</span></a> scientific computing package explicitly uses “loose” semantic versioning, where releases incrementing the minor version can contain backwards-incompatible API changes (<a class="reference external" href="https://numpy.org/doc/stable/dev/depending_on_numpy.html" title="(in NumPy v2.2)"><span class="xref std std-doc">NumPy versioning policy</span></a>).</p> </section> <section id="calendar-versioning"> <h3>Calendar versioning<a class="headerlink" href="#calendar-versioning" title="Link to this heading">¶</a></h3> <p>Semantic versioning is not a suitable choice for all projects, such as those with a regular time based release cadence and a deprecation process that provides warnings for a number of releases prior to removal of a feature.</p> <p>A key advantage of date-based versioning, or <a class="reference external" href="https://calver.org">calendar versioning</a> (CalVer), is that it is straightforward to tell how old the base feature set of a particular release is given just the version number.</p> <p>Calendar version numbers typically take the form <em>year.month</em> (for example, 23.12 for December 2023).</p> <p><a class="reference external" href="https://pip.pypa.io/en/latest/" title="(in pip v25.1)"><span class="xref std std-doc">Pip</span></a>, the standard Python package installer, uses calendar versioning.</p> </section> <section id="other-schemes"> <h3>Other schemes<a class="headerlink" href="#other-schemes" title="Link to this heading">¶</a></h3> <p>Serial versioning refers to the simplest possible versioning scheme, which consists of a single number incremented every release. While serial versioning is very easy to manage as a developer, it is the hardest to track as an end user, as serial version numbers convey little or no information regarding API backwards compatibility.</p> <p>Combinations of the above schemes are possible. For example, a project may combine date based versioning with serial versioning to create a <em>year.serial</em> numbering scheme that readily conveys the approximate age of a release, but doesn’t otherwise commit to a particular release cadence within the year.</p> </section> </section> <section id="local-version-identifiers"> <h2>Local version identifiers<a class="headerlink" href="#local-version-identifiers" title="Link to this heading">¶</a></h2> <p>Public version identifiers are designed to support distribution via <a class="reference internal" href="../../glossary/#term-Python-Package-Index-PyPI"><span class="xref std std-term">PyPI</span></a>. Python packaging tools also support the notion of a <a class="reference internal" href="../../specifications/version-specifiers/#local-version-identifiers"><span class="std std-ref">local version identifier</span></a>, which can be used to identify local development builds not intended for publication, or modified variants of a release maintained by a redistributor.</p> <p>A local version identifier takes the form of a public version identifier, followed by “+” and a local version label. For example, a package with Fedora-specific patches applied could have the version “1.2.1+fedora.4”. Another example is versions computed by <a class="reference external" href="https://setuptools-scm.readthedocs.io">setuptools-scm</a>, a setuptools plugin that reads the version from Git data. In a Git repository with some commits since the latest release, setuptools-scm generates a version like “0.5.dev1+gd00980f”, or if the repository has untracked changes, like “0.5.dev1+gd00980f.d20231217”.</p> </section> <section id="accessing-version-information-at-runtime"> <span id="runtime-version-access"></span><h2>Accessing version information at runtime<a class="headerlink" href="#accessing-version-information-at-runtime" title="Link to this heading">¶</a></h2> <p>Version information for all <a class="reference internal" href="../../glossary/#term-Distribution-Package"><span class="xref std std-term">distribution packages</span></a> that are locally available in the current environment can be obtained at runtime using the standard library’s <a class="reference external" href="https://docs.python.org/3/library/importlib.metadata.html#importlib.metadata.version" title="(in Python v3.13)"><code class="xref py py-func docutils literal notranslate"><span class="pre">importlib.metadata.version()</span></code></a> function:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">importlib</span><span class="o">.</span><span class="n">metadata</span><span class="o">.</span><span class="n">version</span><span class="p">(</span><span class="s2">"cryptography"</span><span class="p">)</span> <span class="go">'41.0.7'</span> </pre></div> </div> <p>Many projects also choose to version their top level <a class="reference internal" href="../../glossary/#term-Import-Package"><span class="xref std std-term">import packages</span></a> by providing a package level <code class="docutils literal notranslate"><span class="pre">__version__</span></code> attribute:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">cryptography</span> <span class="gp">>>> </span><span class="n">cryptography</span><span class="o">.</span><span class="n">__version__</span> <span class="go">'41.0.7'</span> </pre></div> </div> <p>This technique can be particularly valuable for CLI applications which want to ensure that version query invocations (such as <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">-V</span></code>) run as quickly as possible.</p> <p>Package publishers wishing to ensure their reported distribution package and import package versions are consistent with each other can review the <a class="reference internal" href="../single-source-version/#single-source-version"><span class="std std-ref">Single-sourcing the Project Version</span></a> discussion for potential approaches to doing so.</p> <p>As import packages and modules are not <em>required</em> to publish runtime version information in this way (see the withdrawn proposal in <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0396/"><strong>PEP 396</strong></a>), the <code class="docutils literal notranslate"><span class="pre">__version__</span></code> attribute should either only be queried with interfaces that are known to provide it (such as a project querying its own version or the version of one of its direct dependencies), or else the querying code should be designed to handle the case where the attribute is missing <a class="footnote-reference brackets" href="#fallback-to-dist-version" id="id4" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a>.</p> <p>Some projects may need to publish version information for external APIs that aren’t the version of the module itself. Such projects should define their own project-specific ways of obtaining the relevant information at runtime. For example, the standard library’s <a class="reference external" href="https://docs.python.org/3/library/ssl.html#module-ssl" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">ssl</span></code></a> module offers multiple ways to access the underlying OpenSSL library version:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ssl</span><span class="o">.</span><span class="n">OPENSSL_VERSION</span> <span class="go">'OpenSSL 3.2.2 4 Jun 2024'</span> <span class="gp">>>> </span><span class="n">ssl</span><span class="o">.</span><span class="n">OPENSSL_VERSION_INFO</span> <span class="go">(3, 2, 0, 2, 0)</span> <span class="gp">>>> </span><span class="nb">hex</span><span class="p">(</span><span class="n">ssl</span><span class="o">.</span><span class="n">OPENSSL_VERSION_NUMBER</span><span class="p">)</span> <span class="go">'0x30200020'</span> </pre></div> </div> <hr class="docutils" /> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="version-examples" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id2">1</a><span class="fn-bracket">]</span></span> <p>Some more examples of unusual version numbers are given in a <a class="reference external" href="https://sethmlarson.dev/pep-440">blog post</a> by Seth Larson.</p> </aside> <aside class="footnote brackets" id="semver-strictness" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id3">2</a><span class="fn-bracket">]</span></span> <p>For some personal viewpoints on this issue, see these blog posts: <a class="reference external" href="https://hynek.me/articles/semver-will-not-save-you/">by Hynek Schlawak</a>, <a class="reference external" href="https://caremad.io/posts/2016/02/versioning-software/">by Donald Stufft</a>, <a class="reference external" href="https://bernat.tech/posts/version-numbers/">by Bernát Gábor</a>, <a class="reference external" href="https://snarky.ca/why-i-dont-like-semver/">by Brett Cannon</a>. For a humoristic take, read about <a class="reference external" href="https://0ver.org">ZeroVer</a>.</p> </aside> <aside class="footnote brackets" id="fallback-to-dist-version" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id4">3</a><span class="fn-bracket">]</span></span> <p>A full list mapping the top level names available for import to the distribution packages that provide those import packages and modules may be obtained through the standard library’s <a class="reference external" href="https://docs.python.org/3/library/importlib.metadata.html#importlib.metadata.packages_distributions" title="(in Python v3.13)"><code class="xref py py-func docutils literal notranslate"><span class="pre">importlib.metadata.packages_distributions()</span></code></a> function. This means that even code that is attempting to infer a version to report for all importable top-level names has a means to fall back to reporting the distribution version information if no <code class="docutils literal notranslate"><span class="pre">__version__</span></code> attribute is defined. Only standard library modules, and modules added via means other than Python package installation would fail to have version information reported in that case.</p> </aside> </aside> </section> </section> </article> </div> <footer> <div class="related-pages"> <a class="next-page" href="../deploying-python-applications/"> <div class="page-info"> <div class="context"> <span>Next</span> </div> <div class="title">Deploying Python applications</div> </div> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> </a> <a class="prev-page" href="../"> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> <div class="page-info"> <div class="context"> <span>Previous</span> </div> <div class="title">Discussions</div> </div> </a> </div> <div class="bottom-of-page"> <div class="left-details"> <div class="copyright"> Copyright © 2013–2020, PyPA </div> Made with <a href="https://www.sphinx-doc.org/">Sphinx</a> and <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s <a href="https://github.com/pradyunsg/furo">Furo</a> <div class="last-updated"> Last updated on Feb 17, 2025</div> </div> <div class="right-details"> </div> </div> </footer> </div> <aside class="toc-drawer"> <div class="toc-sticky toc-scroll"> <div class="toc-title-container"> <span class="toc-title"> On this page </span> </div> <div class="toc-tree-container"> <div class="toc-tree"> <ul> <li><a class="reference internal" href="#">Versioning</a><ul> <li><a class="reference internal" href="#valid-version-numbers">Valid version numbers</a></li> <li><a class="reference internal" href="#semantic-versioning-vs-calendar-versioning">Semantic versioning vs. calendar versioning</a><ul> <li><a class="reference internal" href="#semantic-versioning">Semantic versioning</a></li> <li><a class="reference internal" href="#calendar-versioning">Calendar versioning</a></li> <li><a class="reference internal" href="#other-schemes">Other schemes</a></li> </ul> </li> <li><a class="reference internal" href="#local-version-identifiers">Local version identifiers</a></li> <li><a class="reference internal" href="#accessing-version-information-at-runtime">Accessing version information at runtime</a></li> </ul> </li> </ul> </div> </div> </div> </aside> </div> </div><script src="../../_static/documentation_options.js?v=187304be"></script> <script src="../../_static/doctools.js?v=888ff710"></script> <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../../_static/scripts/furo.js?v=5fa4622c"></script> <script src="../../_static/tabs.js?v=3ee01567"></script> <script src="../../_static/clipboard.min.js?v=a7894cd8"></script> <script src="../../_static/copybutton.js?v=cb5fb026"></script> <script data-domain="packaging.python.org" defer="defer" src="https://plausible.io/js/script.js"></script> </body> </html>