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="Tutorials" href="../tutorials/" /><link rel="prev" title="Overview of Python Packaging" href="../overview/" /> <link rel="shortcut icon" href="../_static/py.png"/> <title>The Packaging Flow - 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="/flow/" /><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 current current-page"><a class="current reference internal" href="#">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 has-children"><a class="reference internal" href="../discussions/">Discussions</a><input 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> <li class="toctree-l2"><a class="reference internal" href="../discussions/versioning/">Versioning</a></li> <li class="toctree-l2"><a class="reference internal" href="../discussions/deploying-python-applications/">Deploying Python applications</a></li> <li class="toctree-l2"><a class="reference internal" href="../discussions/pip-vs-easy-install/">pip vs easy_install</a></li> <li class="toctree-l2"><a class="reference internal" href="../discussions/install-requires-vs-requirements/">install_requires vs requirements files</a></li> <li class="toctree-l2"><a class="reference internal" href="../discussions/distribution-package-vs-import-package/">Distribution package vs. import package</a></li> <li class="toctree-l2"><a class="reference internal" href="../discussions/package-formats/">Package Formats</a></li> <li class="toctree-l2"><a class="reference internal" href="../discussions/src-layout-vs-flat-layout/">src layout vs flat layout</a></li> <li class="toctree-l2"><a class="reference internal" href="../discussions/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="../discussions/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/flow.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/flow.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="the-packaging-flow"> <h1>The Packaging Flow<a class="headerlink" href="#the-packaging-flow" title="Link to this heading">¶</a></h1> <p>The document aims to outline the flow involved in publishing/distributing a <a class="reference internal" href="../glossary/#term-Distribution-Package"><span class="xref std std-term">distribution package</span></a>, usually to the <a class="reference external" href="https://pypi.org/">Python Package Index (PyPI)</a>. It is written for package publishers, who are assumed to be the package author.</p> <p>While the <a class="reference internal" href="../tutorials/packaging-projects/"><span class="doc">tutorial</span></a> walks through the process of preparing a simple package for release, it does not fully enumerate what steps and files are required, and for what purpose.</p> <p>Publishing a package requires a flow from the author’s source code to an end user’s Python environment. The steps to achieve this are:</p> <ul class="simple"> <li><p>Have a source tree containing the package. This is typically a checkout from a version control system (VCS).</p></li> <li><p>Prepare a configuration file describing the package metadata (name, version and so forth) and how to create the build artifacts. For most packages, this will be a <code class="file docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file, maintained manually in the source tree.</p></li> <li><p>Create build artifacts to be sent to the package distribution service (usually PyPI); these will normally be a <a class="reference internal" href="../glossary/#term-Source-Distribution-or-sdist"><span class="xref std std-term">source distribution (“sdist”)</span></a> and one or more <a class="reference internal" href="../glossary/#term-Built-Distribution"><span class="xref std std-term">built distributions (“wheels”)</span></a>. These are made by a build tool using the configuration file from the previous step. Often there is just one generic wheel for a pure Python package.</p></li> <li><p>Upload the build artifacts to the package distribution service.</p></li> </ul> <p>At that point, the package is present on the package distribution service. To use the package, end users must:</p> <ul class="simple"> <li><p>Download one of the package’s build artifacts from the package distribution service.</p></li> <li><p>Install it in their Python environment, usually in its <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory. This step may involve a build/compile step which, if needed, must be described by the package metadata.</p></li> </ul> <p>These last 2 steps are typically performed by <a class="reference internal" href="../key_projects/#pip"><span class="std std-ref">pip</span></a> when an end user runs <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span></code>.</p> <p>The steps above are described in more detail below.</p> <section id="the-source-tree"> <h2>The source tree<a class="headerlink" href="#the-source-tree" title="Link to this heading">¶</a></h2> <p>The source tree contains the package source code, usually a checkout from a VCS. The particular version of the code used to create the build artifacts will typically be a checkout based on a tag associated with the version.</p> </section> <section id="the-configuration-file"> <h2>The configuration file<a class="headerlink" href="#the-configuration-file" title="Link to this heading">¶</a></h2> <p>The configuration file depends on the tool used to create the build artifacts. The standard practice is to use a <code class="file docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file in the <a class="reference external" href="https://github.com/toml-lang/toml">TOML format</a>.</p> <p>At a minimum, the <code class="file docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file needs a <code class="docutils literal notranslate"><span class="pre">[build-system]</span></code> table specifying your build tool. There are many build tools available, including but not limited to <a class="reference internal" href="../key_projects/#flit"><span class="std std-ref">flit</span></a>, <a class="reference internal" href="../key_projects/#hatch"><span class="std std-ref">hatch</span></a>, <a class="reference internal" href="../key_projects/#pdm"><span class="std std-ref">pdm</span></a>, <a class="reference internal" href="../key_projects/#poetry"><span class="std std-ref">poetry</span></a>, <a class="reference internal" href="../key_projects/#setuptools"><span class="std std-ref">Setuptools</span></a>, <a class="reference external" href="https://pypi.org/project/trampolim/">trampolim</a>, and <a class="reference external" href="https://pypi.org/project/whey/">whey</a>. Each tool’s documentation will show what to put in the <code class="docutils literal notranslate"><span class="pre">[build-system]</span></code> table.</p> <p>For example, here is a table for using <a class="reference internal" href="../key_projects/#hatch"><span class="std std-ref">hatch</span></a>:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[build-system]</span> <span class="n">requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s2">"hatchling"</span><span class="p">]</span> <span class="n">build-backend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"hatchling.build"</span> </pre></div> </div> <p>With such a table in the <code class="file docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file, a “<a class="reference internal" href="../glossary/#term-Build-Frontend"><span class="xref std std-term">frontend</span></a>” tool like <a class="reference internal" href="../key_projects/#build"><span class="std std-ref">build</span></a> can run your chosen build tool’s “<a class="reference internal" href="../glossary/#term-Build-Backend"><span class="xref std std-term">backend</span></a>” to create the build artifacts. Your build tool may also provide its own frontend. An install tool like <a class="reference internal" href="../key_projects/#pip"><span class="std std-ref">pip</span></a> also acts as a frontend when it runs your build tool’s backend to install from a source distribution.</p> <p>The particular build tool you choose dictates what additional information is required in the <code class="file docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file. For example, you might specify:</p> <ul class="simple"> <li><p>a <code class="docutils literal notranslate"><span class="pre">[project]</span></code> table containing project <a class="reference internal" href="../specifications/core-metadata/"><span class="doc">Core Metadata</span></a> (name, version, author and so forth),</p></li> <li><p>a <code class="docutils literal notranslate"><span class="pre">[tool]</span></code> table containing tool-specific configuration options.</p></li> </ul> <p>Refer to the <a class="reference internal" href="../guides/writing-pyproject-toml/#writing-pyproject-toml"><span class="std std-ref">pyproject.toml guide</span></a> for a complete guide to <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> configuration.</p> </section> <section id="build-artifacts"> <h2>Build artifacts<a class="headerlink" href="#build-artifacts" title="Link to this heading">¶</a></h2> <section id="the-source-distribution-sdist"> <h3>The source distribution (sdist)<a class="headerlink" href="#the-source-distribution-sdist" title="Link to this heading">¶</a></h3> <p>A source distribution contains enough to install the package from source in an end user’s Python environment. As such, it needs the package source, and may also include tests and documentation. These are useful for end users wanting to develop your sources, and for end user systems where some local compilation step is required (such as a C extension).</p> <p>The <a class="reference internal" href="../key_projects/#build"><span class="std std-ref">build</span></a> package knows how to invoke your build tool to create one of these:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python3<span class="w"> </span>-m<span class="w"> </span>build<span class="w"> </span>--sdist<span class="w"> </span>source-tree-directory </pre></div> </div> <p>Or, your build tool may provide its own interface for creating an sdist.</p> </section> <section id="the-built-distributions-wheels"> <h3>The built distributions (wheels)<a class="headerlink" href="#the-built-distributions-wheels" title="Link to this heading">¶</a></h3> <p>A built distribution contains only the files needed for an end user’s Python environment. No compilation steps are required during the install, and the wheel file can simply be unpacked into the <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory. This makes the install faster and more convenient for end users.</p> <p>A pure Python package typically needs only one “generic” wheel. A package with compiled binary extensions needs a wheel for each supported combination of Python interpreter, operating system, and CPU architecture that it supports. If a suitable wheel file is not available, tools like <a class="reference internal" href="../key_projects/#pip"><span class="std std-ref">pip</span></a> will fall back to installing the source distribution.</p> <p>The <a class="reference internal" href="../key_projects/#build"><span class="std std-ref">build</span></a> package knows how to invoke your build tool to create one of these:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python3<span class="w"> </span>-m<span class="w"> </span>build<span class="w"> </span>--wheel<span class="w"> </span>source-tree-directory </pre></div> </div> <p>Or, your build tool may provide its own interface for creating a wheel.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>The default behaviour of <a class="reference internal" href="../key_projects/#build"><span class="std std-ref">build</span></a> is to make both an sdist and a wheel from the source in the current directory; the above examples are deliberately specific.</p> </div> </section> </section> <section id="upload-to-the-package-distribution-service"> <h2>Upload to the package distribution service<a class="headerlink" href="#upload-to-the-package-distribution-service" title="Link to this heading">¶</a></h2> <p>The <a class="reference internal" href="../key_projects/#twine"><span class="std std-ref">twine</span></a> tool can upload build artifacts to PyPI for distribution, using a command like:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>twine<span class="w"> </span>upload<span class="w"> </span>dist/package-name-version.tar.gz<span class="w"> </span>dist/package-name-version-py3-none-any.whl </pre></div> </div> <p>Or, your build tool may provide its own interface for uploading.</p> </section> <section id="download-and-install"> <h2>Download and install<a class="headerlink" href="#download-and-install" title="Link to this heading">¶</a></h2> <p>Now that the package is published, end users can download and install the package into their Python environment. Typically this is done with <a class="reference internal" href="../key_projects/#pip"><span class="std std-ref">pip</span></a>, using a command like:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python3<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>package-name </pre></div> </div> <p>End users may also use other tools like <a class="reference internal" href="../key_projects/#pipenv"><span class="std std-ref">Pipenv</span></a>, <a class="reference internal" href="../key_projects/#poetry"><span class="std std-ref">poetry</span></a>, or <a class="reference internal" href="../key_projects/#pdm"><span class="std std-ref">pdm</span></a>.</p> </section> </section> </article> </div> <footer> <div class="related-pages"> <a class="next-page" href="../tutorials/"> <div class="page-info"> <div class="context"> <span>Next</span> </div> <div class="title">Tutorials</div> </div> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> </a> <a class="prev-page" href="../overview/"> <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">Overview of Python Packaging</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 19, 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="#">The Packaging Flow</a><ul> <li><a class="reference internal" href="#the-source-tree">The source tree</a></li> <li><a class="reference internal" href="#the-configuration-file">The configuration file</a></li> <li><a class="reference internal" href="#build-artifacts">Build artifacts</a><ul> <li><a class="reference internal" href="#the-source-distribution-sdist">The source distribution (sdist)</a></li> <li><a class="reference internal" href="#the-built-distributions-wheels">The built distributions (wheels)</a></li> </ul> </li> <li><a class="reference internal" href="#upload-to-the-package-distribution-service">Upload to the package distribution service</a></li> <li><a class="reference internal" href="#download-and-install">Download and install</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>