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="Version specifiers" href="../version-specifiers/" /><link rel="prev" title="Names and normalization" href="../name-normalization/" /> <link rel="shortcut icon" href="../../_static/py.png"/> <title>Core metadata specifications - Python Packaging User Guide</title> <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=a746c00c" /> <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?v=135e06be" /> <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=36a5483c" /> <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="/specifications/core-metadata/" /><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.5" 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.5" 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-half" viewBox="0 0 24 24"> <title>Auto light/dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow"> <path stroke="none" d="M0 0h24v24H0z" fill="none"/> <circle cx="12" cy="12" r="9" /> <path d="M13 12h5" /> <path d="M13 15h4" /> <path d="M13 18h1" /> <path d="M13 9h4" /> <path d="M13 6h1" /> </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> <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"><use href="#svg-sun-half"></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> </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 current has-children"><a class="reference internal" href="../">PyPA specifications</a><input checked="" 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 class="current"> <li class="toctree-l2 current has-children"><a class="reference internal" href="../section-distribution-metadata/">Package Distribution Metadata</a><input checked="" 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 class="current"> <li class="toctree-l3"><a class="reference internal" href="../name-normalization/">Names and normalization</a></li> <li class="toctree-l3 current current-page"><a class="current reference internal" href="#">Core metadata specifications</a></li> <li class="toctree-l3"><a class="reference internal" href="../version-specifiers/">Version specifiers</a></li> <li class="toctree-l3"><a class="reference internal" href="../dependency-specifiers/">Dependency specifiers</a></li> <li class="toctree-l3"><a class="reference internal" href="../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="../inline-script-metadata/">Inline script metadata</a></li> <li class="toctree-l3"><a class="reference internal" href="../platform-compatibility-tags/">Platform compatibility tags</a></li> <li class="toctree-l3"><a class="reference internal" href="../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="../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="../recording-installed-packages/">Recording installed projects</a></li> <li class="toctree-l3"><a class="reference internal" href="../entry-points/">Entry points specification</a></li> <li class="toctree-l3"><a class="reference internal" href="../direct-url/">Recording the Direct URL Origin of installed distributions</a></li> <li class="toctree-l3"><a class="reference internal" href="../direct-url-data-structure/">Direct URL Data Structure</a></li> <li class="toctree-l3"><a class="reference internal" href="../virtual-environments/">Python Virtual Environments</a></li> <li class="toctree-l3"><a class="reference internal" href="../externally-managed-environments/">Externally Managed Environments</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../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="../source-distribution-format/">Source distribution format</a></li> <li class="toctree-l3"><a class="reference internal" href="../binary-distribution-format/">Binary distribution format</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../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="../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="../simple-repository-api/">Simple repository API</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="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"><use href="#svg-sun-half"></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"> <section id="core-metadata-specifications"> <span id="core-metadata"></span><h1>Core metadata specifications<a class="headerlink" href="#core-metadata-specifications" title="Link to this heading">#</a></h1> <p>Fields defined in the following specification should be considered valid, complete and not subject to change. The required fields are:</p> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">Metadata-Version</span></code></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">Name</span></code></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">Version</span></code></p></li> </ul> <p>All the other fields are optional.</p> <p>The standard file format for metadata (including in <a class="reference internal" href="../binary-distribution-format/"><span class="doc">wheels</span></a> and <a class="reference internal" href="../recording-installed-packages/"><span class="doc">installed projects</span></a>) is based on the format of email headers. However, email formats have been revised several times, and exactly which email RFC applies to packaging metadata is not specified. In the absence of a precise definition, the practical standard is set by what the standard library <a class="reference external" href="https://docs.python.org/3/library/email.parser.html#module-email.parser" title="(in Python v3.13)"><code class="docutils literal notranslate"><span class="pre">email.parser</span></code></a> module can parse using the <a class="reference external" href="https://docs.python.org/3/library/email.policy.html#email.policy.compat32" title="(in Python v3.13)"><code class="xref py py-data docutils literal notranslate"><span class="pre">compat32</span></code></a> policy.</p> <p>Whenever metadata is serialised to a byte stream (for example, to save to a file), strings must be serialised using the UTF-8 encoding.</p> <p>Although <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0566/"><strong>PEP 566</strong></a> defined a way to transform metadata into a JSON-compatible dictionary, this is not yet used as a standard interchange format. The need for tools to work with years worth of existing packages makes it difficult to shift to a new format.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p><em>Interpreting old metadata:</em> In <span class="target" id="index-1"></span><a class="pep reference external" href="https://peps.python.org/pep-0566/"><strong>PEP 566</strong></a>, the version specifier field format specification was relaxed to accept the syntax used by popular publishing tools (namely to remove the requirement that version specifiers must be surrounded by parentheses). Metadata consumers may want to use the more relaxed formatting rules even for metadata files that are nominally less than version 2.1.</p> </div> <section id="metadata-version"> <span id="core-metadata-metadata-version"></span><h2>Metadata-Version<a class="headerlink" href="#metadata-version" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.0.</span></p> </div> <p>Version of the file format; legal values are “1.0”, “1.1”, “1.2”, “2.1”, “2.2”, “2.3”, and “2.4”.</p> <p>Automated tools consuming metadata SHOULD warn if <code class="docutils literal notranslate"><span class="pre">metadata_version</span></code> is greater than the highest version they support, and MUST fail if <code class="docutils literal notranslate"><span class="pre">metadata_version</span></code> has a greater major version than the highest version they support (as described in the <a class="reference internal" href="../version-specifiers/#version-specifiers"><span class="std std-ref">Version specifier specification</span></a>, the major version is the value before the first dot).</p> <p>For broader compatibility, build tools MAY choose to produce distribution metadata using the lowest metadata version that includes all of the needed fields.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Metadata-Version: 2.4 </pre></div> </div> </section> <section id="name"> <span id="core-metadata-name"></span><h2>Name<a class="headerlink" href="#name" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.0.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 2.1: </span>Added restrictions on format from the <a class="reference internal" href="../name-normalization/#name-format"><span class="std std-ref">name format</span></a>.</p> </div> <p>The name of the distribution. The name field is the primary identifier for a distribution. It must conform to the <a class="reference internal" href="../name-normalization/#name-format"><span class="std std-ref">name format specification</span></a>.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Name: BeagleVote </pre></div> </div> <p>For comparison purposes, the names should be <a class="reference internal" href="../name-normalization/#name-normalization"><span class="std std-ref">normalized</span></a> before comparing.</p> </section> <section id="version"> <span id="core-metadata-version"></span><h2>Version<a class="headerlink" href="#version" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.0.</span></p> </div> <p>A string containing the distribution’s version number. This field must be in the format specified in the <a class="reference internal" href="../version-specifiers/#version-specifiers"><span class="std std-ref">Version specifier specification</span></a>.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Version: 1.0a2 </pre></div> </div> </section> <section id="dynamic-multiple-use"> <span id="core-metadata-dynamic"></span><h2>Dynamic (multiple use)<a class="headerlink" href="#dynamic-multiple-use" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 2.2.</span></p> </div> <p>A string containing the name of another core metadata field. The field names <code class="docutils literal notranslate"><span class="pre">Name</span></code>, <code class="docutils literal notranslate"><span class="pre">Version</span></code>, and <code class="docutils literal notranslate"><span class="pre">Metadata-Version</span></code> may not be specified in this field.</p> <p>When found in the metadata of a source distribution, the following rules apply:</p> <ol class="arabic simple"> <li><p>If a field is <em>not</em> marked as <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code>, then the value of the field in any wheel built from the sdist MUST match the value in the sdist. If the field is not in the sdist, and not marked as <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code>, then it MUST NOT be present in the wheel.</p></li> <li><p>If a field is marked as <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code>, it may contain any valid value in a wheel built from the sdist (including not being present at all).</p></li> </ol> <p>If the sdist metadata version is older than version 2.2, then all fields should be treated as if they were specified with <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code> (i.e. there are no special restrictions on the metadata of wheels built from the sdist).</p> <p>In any context other than a source distribution, <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code> is for information only, and indicates that the field value was calculated at wheel build time, and may not be the same as the value in the sdist or in other wheels for the project.</p> <p>Full details of the semantics of <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code> are described in <span class="target" id="index-2"></span><a class="pep reference external" href="https://peps.python.org/pep-0643/"><strong>PEP 643</strong></a>.</p> </section> <section id="platform-multiple-use"> <span id="core-metadata-platform"></span><h2>Platform (multiple use)<a class="headerlink" href="#platform-multiple-use" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.0.</span></p> </div> <p>A Platform specification describing an operating system supported by the distribution which is not listed in the “Operating System” Trove classifiers. See “Classifier” below.</p> <p>Examples:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Platform: ObscureUnix Platform: RareDOS </pre></div> </div> </section> <section id="supported-platform-multiple-use"> <span id="core-metadata-supported-platform"></span><h2>Supported-Platform (multiple use)<a class="headerlink" href="#supported-platform-multiple-use" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.1.</span></p> </div> <p>Binary distributions containing a PKG-INFO file will use the Supported-Platform field in their metadata to specify the OS and CPU for which the binary distribution was compiled. The semantics of the Supported-Platform field are not specified in this PEP.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Supported-Platform: RedHat 7.2 Supported-Platform: i386-win32-2791 </pre></div> </div> </section> <section id="summary"> <span id="core-metadata-summary"></span><h2>Summary<a class="headerlink" href="#summary" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.0.</span></p> </div> <p>A one-line summary of what the distribution does.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Summary: A module for collecting votes from beagles. </pre></div> </div> </section> <section id="description"> <span id="core-metadata-description"></span><span id="description-optional"></span><h2>Description<a class="headerlink" href="#description" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.0.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 2.1: </span>This field may be specified in the message body instead.</p> </div> <p>A longer description of the distribution that can run to several paragraphs. Software that deals with metadata should not assume any maximum size for this field, though people shouldn’t include their instruction manual as the description.</p> <p>The contents of this field can be written using reStructuredText markup <a class="footnote-reference brackets" href="#id3" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>. For programs that work with the metadata, supporting markup is optional; programs can also display the contents of the field as-is. This means that authors should be conservative in the markup they use.</p> <p>To support empty lines and lines with indentation with respect to the RFC 822 format, any CRLF character has to be suffixed by 7 spaces followed by a pipe (“|”) char. As a result, the Description field is encoded into a folded field that can be interpreted by RFC822 parser <a class="footnote-reference brackets" href="#id4" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a>.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Description: This project provides powerful math functions |For example, you can use `sum()` to sum numbers: | |Example:: | | >>> sum(1, 2) | 3 | </pre></div> </div> <p>This encoding implies that any occurrences of a CRLF followed by 7 spaces and a pipe char have to be replaced by a single CRLF when the field is unfolded using a RFC822 reader.</p> <p>Alternatively, the distribution’s description may instead be provided in the message body (i.e., after a completely blank line following the headers, with no indentation or other special formatting necessary).</p> </section> <section id="description-content-type"> <span id="core-metadata-description-content-type"></span><span id="description-content-type-optional"></span><h2>Description-Content-Type<a class="headerlink" href="#description-content-type" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 2.1.</span></p> </div> <p>A string stating the markup syntax (if any) used in the distribution’s description, so that tools can intelligently render the description.</p> <p>Historically, PyPI supported descriptions in plain text and <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html">reStructuredText (reST)</a>, and could render reST into HTML. However, it is common for distribution authors to write the description in <a class="reference external" href="https://daringfireball.net/projects/markdown/">Markdown</a> (<span class="target" id="index-3"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc7763.html"><strong>RFC 7763</strong></a>) as many code hosting sites render Markdown READMEs, and authors would reuse the file for the description. PyPI didn’t recognize the format and so could not render the description correctly. This resulted in many packages on PyPI with poorly-rendered descriptions when Markdown is left as plain text, or worse, was attempted to be rendered as reST. This field allows the distribution author to specify the format of their description, opening up the possibility for PyPI and other tools to be able to render Markdown and other formats.</p> <p>The format of this field is the same as the <code class="docutils literal notranslate"><span class="pre">Content-Type</span></code> header in HTTP (i.e.: <a class="reference external" href="https://www.w3.org/Protocols/rfc1341/4_Content-Type.html">RFC 1341</a>). Briefly, this means that it has a <code class="docutils literal notranslate"><span class="pre">type/subtype</span></code> part and then it can optionally have a number of parameters:</p> <p>Format:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Description-Content-Type: <type>/<subtype>; charset=<charset>[; <param_name>=<param value> ...] </pre></div> </div> <p>The <code class="docutils literal notranslate"><span class="pre">type/subtype</span></code> part has only a few legal values:</p> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">text/plain</span></code></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">text/x-rst</span></code></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">text/markdown</span></code></p></li> </ul> <p>The <code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter can be used to specify the character encoding of the description. The only legal value is <code class="docutils literal notranslate"><span class="pre">UTF-8</span></code>. If omitted, it is assumed to be <code class="docutils literal notranslate"><span class="pre">UTF-8</span></code>.</p> <p>Other parameters might be specific to the chosen subtype. For example, for the <code class="docutils literal notranslate"><span class="pre">markdown</span></code> subtype, there is an optional <code class="docutils literal notranslate"><span class="pre">variant</span></code> parameter that allows specifying the variant of Markdown in use (defaults to <code class="docutils literal notranslate"><span class="pre">GFM</span></code> if not specified). Currently, two variants are recognized:</p> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">GFM</span></code> for <span class="target" id="index-4"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc7764.html#section-3.2"><strong>GitHub-flavored Markdown</strong></a></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">CommonMark</span></code> for <span class="target" id="index-5"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc7764.html#section-3.5"><strong>CommonMark</strong></a></p></li> </ul> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Description-Content-Type: text/plain; charset=UTF-8 </pre></div> </div> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Description-Content-Type: text/x-rst; charset=UTF-8 </pre></div> </div> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM </pre></div> </div> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Description-Content-Type: text/markdown </pre></div> </div> <p>If a <code class="docutils literal notranslate"><span class="pre">Description-Content-Type</span></code> is not specified, then applications should attempt to render it as <code class="docutils literal notranslate"><span class="pre">text/x-rst;</span> <span class="pre">charset=UTF-8</span></code> and fall back to <code class="docutils literal notranslate"><span class="pre">text/plain</span></code> if it is not valid rst.</p> <p>If a <code class="docutils literal notranslate"><span class="pre">Description-Content-Type</span></code> is an unrecognized value, then the assumed content type is <code class="docutils literal notranslate"><span class="pre">text/plain</span></code> (Although PyPI will probably reject anything with an unrecognized value).</p> <p>If the <code class="docutils literal notranslate"><span class="pre">Description-Content-Type</span></code> is <code class="docutils literal notranslate"><span class="pre">text/markdown</span></code> and <code class="docutils literal notranslate"><span class="pre">variant</span></code> is not specified or is set to an unrecognized value, then the assumed <code class="docutils literal notranslate"><span class="pre">variant</span></code> is <code class="docutils literal notranslate"><span class="pre">GFM</span></code>.</p> <p>So for the last example above, the <code class="docutils literal notranslate"><span class="pre">charset</span></code> defaults to <code class="docutils literal notranslate"><span class="pre">UTF-8</span></code> and the <code class="docutils literal notranslate"><span class="pre">variant</span></code> defaults to <code class="docutils literal notranslate"><span class="pre">GFM</span></code> and thus it is equivalent to the example before it.</p> </section> <section id="keywords"> <span id="core-metadata-keywords"></span><span id="keywords-optional"></span><h2>Keywords<a class="headerlink" href="#keywords" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.0.</span></p> </div> <p>A list of additional keywords, separated by commas, to be used to assist searching for the distribution in a larger catalog.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Keywords: dog,puppy,voting,election </pre></div> </div> <div class="admonition note"> <p class="admonition-title">Note</p> <p>The specification previously showed keywords separated by spaces, but distutils and setuptools implemented it with commas. These tools have been very widely used for many years, so it was easier to update the specification to match the de facto standard.</p> </div> </section> <section id="author"> <span id="core-metadata-author"></span><span id="author-optional"></span><h2>Author<a class="headerlink" href="#author" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.0.</span></p> </div> <p>A string containing the author’s name at a minimum; additional contact information may be provided.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Author: C. Schultz, Universal Features Syndicate, Los Angeles, CA <cschultz@peanuts.example.com> </pre></div> </div> </section> <section id="author-email"> <span id="core-metadata-author-email"></span><span id="author-email-optional"></span><h2>Author-email<a class="headerlink" href="#author-email" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.0.</span></p> </div> <p>A string containing the author’s e-mail address. It can contain a name and e-mail address in the legal forms for a RFC-822 <code class="docutils literal notranslate"><span class="pre">From:</span></code> header.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Author-email: "C. Schultz" <cschultz@example.com> </pre></div> </div> <p>Per RFC-822, this field may contain multiple comma-separated e-mail addresses:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Author-email: cschultz@example.com, snoopy@peanuts.com </pre></div> </div> </section> <section id="maintainer"> <span id="core-metadata-maintainer"></span><span id="maintainer-optional"></span><h2>Maintainer<a class="headerlink" href="#maintainer" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.2.</span></p> </div> <p>A string containing the maintainer’s name at a minimum; additional contact information may be provided.</p> <p>Note that this field is intended for use when a project is being maintained by someone other than the original author: it should be omitted if it is identical to <code class="docutils literal notranslate"><span class="pre">Author</span></code>.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Maintainer: C. Schultz, Universal Features Syndicate, Los Angeles, CA <cschultz@peanuts.example.com> </pre></div> </div> </section> <section id="maintainer-email"> <span id="core-metadata-maintainer-email"></span><span id="maintainer-email-optional"></span><h2>Maintainer-email<a class="headerlink" href="#maintainer-email" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.2.</span></p> </div> <p>A string containing the maintainer’s e-mail address. It can contain a name and e-mail address in the legal forms for a RFC-822 <code class="docutils literal notranslate"><span class="pre">From:</span></code> header.</p> <p>Note that this field is intended for use when a project is being maintained by someone other than the original author: it should be omitted if it is identical to <code class="docutils literal notranslate"><span class="pre">Author-email</span></code>.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Maintainer-email: "C. Schultz" <cschultz@example.com> </pre></div> </div> <p>Per RFC-822, this field may contain multiple comma-separated e-mail addresses:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Maintainer-email: cschultz@example.com, snoopy@peanuts.com </pre></div> </div> </section> <section id="license"> <span id="core-metadata-license"></span><span id="license-optional"></span><h2>License<a class="headerlink" href="#license" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.0.</span></p> </div> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 2.4: </span>in favour of <code class="docutils literal notranslate"><span class="pre">License-Expression</span></code>.</p> </div> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>As of Metadata 2.4, <code class="docutils literal notranslate"><span class="pre">License</span></code> and <code class="docutils literal notranslate"><span class="pre">License-Expression</span></code> are mutually exclusive. If both are specified, tools which parse metadata will disregard <code class="docutils literal notranslate"><span class="pre">License</span></code> and PyPI will reject uploads. See <a class="reference external" href="https://peps.python.org/pep-0639/#deprecate-license-field">PEP 639</a>.</p> </div> <p>Text indicating the license covering the distribution where the license is not a selection from the “License” Trove classifiers. See <a class="reference internal" href="#metadata-classifier"><span class="std std-ref">“Classifier”</span></a> below. This field may also be used to specify a particular version of a license which is named via the <code class="docutils literal notranslate"><span class="pre">Classifier</span></code> field, or to indicate a variation or exception to such a license.</p> <p>Examples:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>License: This software may only be obtained by sending the author a postcard, and then the user promises not to redistribute it. License: GPL version 3, excluding DRM provisions </pre></div> </div> </section> <section id="license-expression"> <span id="core-metadata-license-expression"></span><span id="license-expression-optional"></span><h2>License-Expression<a class="headerlink" href="#license-expression" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 2.4.</span></p> </div> <p>Text string that is a valid SPDX <a class="reference external" href="https://peps.python.org/pep-0639/#term-license-expression">license expression</a> as <a class="reference external" href="https://peps.python.org/pep-0639/#spdx">defined in PEP 639</a>.</p> <p>Examples:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>License-Expression: MIT License-Expression: BSD-3-Clause License-Expression: MIT AND (Apache-2.0 OR BSD-2-Clause) License-Expression: MIT OR GPL-2.0-or-later OR (FSFUL AND BSD-2-Clause) License-Expression: GPL-3.0-only WITH Classpath-Exception-2.0 OR BSD-3-Clause License-Expression: LicenseRef-Special-License OR CC0-1.0 OR Unlicense License-Expression: LicenseRef-Proprietary </pre></div> </div> </section> <section id="license-file-multiple-use"> <span id="core-metadata-license-file"></span><span id="license-file-optional"></span><h2>License-File (multiple use)<a class="headerlink" href="#license-file-multiple-use" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 2.4.</span></p> </div> <p>Each entry is a string representation of the path of a license-related file. The path is located within the project source tree, relative to the project root directory. For details see <span class="target" id="index-6"></span><a class="pep reference external" href="https://peps.python.org/pep-0639/"><strong>PEP 639</strong></a>.</p> <p>Examples:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>License-File: LICENSE License-File: AUTHORS License-File: LICENSE.txt License-File: licenses/LICENSE.MIT License-File: licenses/LICENSE.CC0 </pre></div> </div> </section> <section id="classifier-multiple-use"> <span id="core-metadata-classifier"></span><span id="metadata-classifier"></span><h2>Classifier (multiple use)<a class="headerlink" href="#classifier-multiple-use" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.1.</span></p> </div> <p>Each entry is a string giving a single classification value for the distribution. Classifiers are described in <span class="target" id="index-7"></span><a class="pep reference external" href="https://peps.python.org/pep-0301/"><strong>PEP 301</strong></a>, and the Python Package Index publishes a dynamic list of <a class="reference external" href="https://pypi.org/classifiers/">currently defined classifiers</a>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>The use of <code class="docutils literal notranslate"><span class="pre">License</span> <span class="pre">::</span></code> classifiers is deprecated as of Metadata 2.4, use <code class="docutils literal notranslate"><span class="pre">License-Expression</span></code> instead. See <a class="reference external" href="https://peps.python.org/pep-0639/#deprecate-license-classifiers">PEP 639</a>.</p> </div> <p>This field may be followed by an environment marker after a semicolon.</p> <p>Examples:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Classifier: Development Status :: 4 - Beta Classifier: Environment :: Console (Text Based) </pre></div> </div> </section> <section id="requires-dist-multiple-use"> <span id="core-metadata-requires-dist"></span><h2>Requires-Dist (multiple use)<a class="headerlink" href="#requires-dist-multiple-use" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.2.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 2.1: </span>The field format specification was relaxed to accept the syntax used by popular publishing tools.</p> </div> <p>Each entry contains a string naming some other distutils project required by this distribution.</p> <p>The format of a requirement string contains from one to four parts:</p> <ul class="simple"> <li><p>A project name, in the same format as the <code class="docutils literal notranslate"><span class="pre">Name:</span></code> field. The only mandatory part.</p></li> <li><p>A comma-separated list of ‘extra’ names. These are defined by the required project, referring to specific features which may need extra dependencies. The names MUST conform to the restrictions specified by the <code class="docutils literal notranslate"><span class="pre">Provides-Extra:</span></code> field.</p></li> <li><p>A version specifier. Tools parsing the format should accept optional parentheses around this, but tools generating it should not use parentheses.</p></li> <li><p>An environment marker after a semicolon. This means that the requirement is only needed in the specified conditions.</p></li> </ul> <p>See <span class="target" id="index-8"></span><a class="pep reference external" href="https://peps.python.org/pep-0508/"><strong>PEP 508</strong></a> for full details of the allowed format.</p> <p>The project names should correspond to names as found on the <a class="reference external" href="https://pypi.org/">Python Package Index</a>.</p> <p>Version specifiers must follow the rules described in <a class="reference internal" href="../version-specifiers/"><span class="doc">Version specifiers</span></a>.</p> <p>Examples:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Requires-Dist: pkginfo Requires-Dist: PasteDeploy Requires-Dist: zope.interface (>3.5.0) Requires-Dist: pywin32 >1.0; sys_platform == 'win32' </pre></div> </div> </section> <section id="requires-python"> <span id="core-metadata-requires-python"></span><h2>Requires-Python<a class="headerlink" href="#requires-python" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.2.</span></p> </div> <p>This field specifies the Python version(s) that the distribution is compatible with. Installation tools may look at this when picking which version of a project to install.</p> <p>The value must be in the format specified in <a class="reference internal" href="../version-specifiers/"><span class="doc">Version specifiers</span></a>.</p> <p>For example, if a distribution uses <a class="reference external" href="https://docs.python.org/3/whatsnew/3.6.html#whatsnew36-pep498" title="(in Python v3.13)"><span class="xref std std-ref">f-strings</span></a> then it may prevent installation on Python < 3.6 by specifying:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Requires-Python: >=3.6 </pre></div> </div> <p>This field cannot be followed by an environment marker.</p> </section> <section id="requires-external-multiple-use"> <span id="core-metadata-requires-external"></span><h2>Requires-External (multiple use)<a class="headerlink" href="#requires-external-multiple-use" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.2.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 2.1: </span>The field format specification was relaxed to accept the syntax used by popular publishing tools.</p> </div> <p>Each entry contains a string describing some dependency in the system that the distribution is to be used. This field is intended to serve as a hint to downstream project maintainers, and has no semantics which are meaningful to the <code class="docutils literal notranslate"><span class="pre">distutils</span></code> distribution.</p> <p>The format of a requirement string is a name of an external dependency, optionally followed by a version declaration within parentheses.</p> <p>This field may be followed by an environment marker after a semicolon.</p> <p>Because they refer to non-Python software releases, version numbers for this field are <strong>not</strong> required to conform to the format specified in the <a class="reference internal" href="../version-specifiers/#version-specifiers"><span class="std std-ref">Version specifier specification</span></a>: they should correspond to the version scheme used by the external dependency.</p> <p>Notice that there is no particular rule on the strings to be used.</p> <p>Examples:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Requires-External: C Requires-External: libpng (>=1.5) Requires-External: make; sys_platform != "win32" </pre></div> </div> </section> <section id="project-url-multiple-use"> <span id="core-metadata-project-url"></span><h2>Project-URL (multiple-use)<a class="headerlink" href="#project-url-multiple-use" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.2.</span></p> </div> <p>A string containing a browsable URL for the project and a label for it, separated by a comma.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Project-URL: Bug Tracker, http://bitbucket.org/tarek/distribute/issues/ </pre></div> </div> <p>The label is free text limited to 32 characters.</p> <p>Starting with <span class="target" id="index-9"></span><a class="pep reference external" href="https://peps.python.org/pep-0753/"><strong>PEP 753</strong></a>, project metadata consumers (such as the Python Package Index) can use a standard normalization process to discover “well-known” labels, which can then be given special presentations when being rendered for human consumption. See <a class="reference internal" href="../well-known-project-urls/#well-known-project-urls"><span class="std std-ref">Well-known Project URLs in Metadata</span></a>.</p> </section> <section id="provides-extra-multiple-use"> <span id="provides-extra-optional-multiple-use"></span><span id="core-metadata-provides-extra"></span><span id="metadata-provides-extra"></span><h2>Provides-Extra (multiple use)<a class="headerlink" href="#provides-extra-multiple-use" title="Link to this heading">#</a></h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 2.1.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 2.3: </span><span class="target" id="index-10"></span><a class="pep reference external" href="https://peps.python.org/pep-0685/"><strong>PEP 685</strong></a> restricted valid values to be unambiguous (i.e. no normalization required). For older metadata versions, value restrictions were brought into line with <code class="docutils literal notranslate"><span class="pre">Name:</span></code> and normalization rules were introduced.</p> </div> <p>A string containing the name of an optional feature. A valid name consists only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start and end with a letter or number. Hyphens cannot be followed by another hyphen. Names are limited to those which match the following regex (which guarantees unambiguity):</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>^[a-z0-9]+(-[a-z0-9]+)*$ </pre></div> </div> <p>The specified name may be used to make a dependency conditional on whether the optional feature has been requested.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Provides-Extra: pdf Requires-Dist: reportlab; extra == 'pdf' </pre></div> </div> <p>A second distribution requires an optional dependency by placing it inside square brackets, and can request multiple features by separating them with a comma (,). The requirements are evaluated for each requested feature and added to the set of requirements for the distribution.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Requires-Dist: beaglevote[pdf] Requires-Dist: libexample[test, doc] </pre></div> </div> <p>Two feature names <code class="docutils literal notranslate"><span class="pre">test</span></code> and <code class="docutils literal notranslate"><span class="pre">doc</span></code> are reserved to mark dependencies that are needed for running automated tests and generating documentation, respectively.</p> <p>It is legal to specify <code class="docutils literal notranslate"><span class="pre">Provides-Extra:</span></code> without referencing it in any <code class="docutils literal notranslate"><span class="pre">Requires-Dist:</span></code>.</p> <p>When writing data for older metadata versions, names MUST be normalized following the same rules used for the <code class="docutils literal notranslate"><span class="pre">Name:</span></code> field when performing comparisons. Tools writing metadata MUST raise an error if two <code class="docutils literal notranslate"><span class="pre">Provides-Extra:</span></code> entries would clash after being normalized.</p> <p>When reading data for older metadata versions, tools SHOULD warn when values for this field would be invalid under newer metadata versions. If a value would be invalid following the rules for <code class="docutils literal notranslate"><span class="pre">Name:</span></code> in any core metadata version, the user SHOULD be warned and the value ignored to avoid ambiguity. Tools MAY choose to raise an error when reading an invalid name for older metadata versions.</p> </section> <section id="rarely-used-fields"> <h2>Rarely Used Fields<a class="headerlink" href="#rarely-used-fields" title="Link to this heading">#</a></h2> <p>The fields in this section are currently rarely used, as their design was inspired by comparable mechanisms in Linux package management systems, and it isn’t at all clear how tools should interpret them in the context of an open index server such as <a class="reference external" href="https://pypi.org">PyPI</a>.</p> <p>As a result, popular installation tools ignore them completely, which in turn means there is little incentive for package publishers to set them appropriately. However, they’re retained in the metadata specification, as they’re still potentially useful for informational purposes, and can also be used for their originally intended purpose in combination with a curated package repository.</p> <section id="provides-dist-multiple-use"> <span id="core-metadata-provides-dist"></span><h3>Provides-Dist (multiple use)<a class="headerlink" href="#provides-dist-multiple-use" title="Link to this heading">#</a></h3> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.2.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 2.1: </span>The field format specification was relaxed to accept the syntax used by popular publishing tools.</p> </div> <p>Each entry contains a string naming a Distutils project which is contained within this distribution. This field <em>must</em> include the project identified in the <code class="docutils literal notranslate"><span class="pre">Name</span></code> field, followed by the version : Name (Version).</p> <p>A distribution may provide additional names, e.g. to indicate that multiple projects have been bundled together. For instance, source distributions of the <code class="docutils literal notranslate"><span class="pre">ZODB</span></code> project have historically included the <code class="docutils literal notranslate"><span class="pre">transaction</span></code> project, which is now available as a separate distribution. Installing such a source distribution satisfies requirements for both <code class="docutils literal notranslate"><span class="pre">ZODB</span></code> and <code class="docutils literal notranslate"><span class="pre">transaction</span></code>.</p> <p>A distribution may also provide a “virtual” project name, which does not correspond to any separately-distributed project: such a name might be used to indicate an abstract capability which could be supplied by one of multiple projects. E.g., multiple projects might supply RDBMS bindings for use by a given ORM: each project might declare that it provides <code class="docutils literal notranslate"><span class="pre">ORM-bindings</span></code>, allowing other projects to depend only on having at most one of them installed.</p> <p>A version declaration may be supplied and must follow the rules described in <a class="reference internal" href="../version-specifiers/"><span class="doc">Version specifiers</span></a>. The distribution’s version number will be implied if none is specified.</p> <p>This field may be followed by an environment marker after a semicolon.</p> <p>Examples:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Provides-Dist: OtherProject Provides-Dist: AnotherProject==3.4 Provides-Dist: virtual_package; python_version >= "3.4" </pre></div> </div> </section> <section id="obsoletes-dist-multiple-use"> <span id="core-metadata-obsoletes-dist"></span><h3>Obsoletes-Dist (multiple use)<a class="headerlink" href="#obsoletes-dist-multiple-use" title="Link to this heading">#</a></h3> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.2.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 2.1: </span>The field format specification was relaxed to accept the syntax used by popular publishing tools.</p> </div> <p>Each entry contains a string describing a distutils project’s distribution which this distribution renders obsolete, meaning that the two projects should not be installed at the same time.</p> <p>Version declarations can be supplied. Version numbers must be in the format specified in <a class="reference internal" href="../version-specifiers/"><span class="doc">Version specifiers</span></a>.</p> <p>This field may be followed by an environment marker after a semicolon.</p> <p>The most common use of this field will be in case a project name changes, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install Torqued Python, the Gorgon distribution should be removed.</p> <p>Examples:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Obsoletes-Dist: Gorgon Obsoletes-Dist: OtherProject (<3.0) Obsoletes-Dist: Foo; os_name == "posix" </pre></div> </div> </section> </section> <section id="deprecated-fields"> <h2>Deprecated Fields<a class="headerlink" href="#deprecated-fields" title="Link to this heading">#</a></h2> <section id="home-page"> <span id="core-metadata-home-page"></span><span id="home-page-optional"></span><h3>Home-page<a class="headerlink" href="#home-page" title="Link to this heading">#</a></h3> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.0.</span></p> </div> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 1.2: </span>Per <span class="target" id="index-11"></span><a class="pep reference external" href="https://peps.python.org/pep-0753/"><strong>PEP 753</strong></a>, use <a class="reference internal" href="#core-metadata-project-url"><span class="std std-ref">Project-URL (multiple-use)</span></a> instead.</p> </div> <p>A string containing the URL for the distribution’s home page.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Home-page: http://www.example.com/~cschultz/bvote/ </pre></div> </div> </section> <section id="download-url"> <span id="core-metadata-download-url"></span><h3>Download-URL<a class="headerlink" href="#download-url" title="Link to this heading">#</a></h3> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.1.</span></p> </div> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 1.2: </span>Per <span class="target" id="index-12"></span><a class="pep reference external" href="https://peps.python.org/pep-0753/"><strong>PEP 753</strong></a>, use <a class="reference internal" href="#core-metadata-project-url"><span class="std std-ref">Project-URL (multiple-use)</span></a> instead.</p> </div> <p>A string containing the URL from which this version of the distribution can be downloaded. (This means that the URL can’t be something like “<code class="docutils literal notranslate"><span class="pre">.../BeagleVote-latest.tgz</span></code>”, but instead must be “<code class="docutils literal notranslate"><span class="pre">.../BeagleVote-0.45.tgz</span></code>”.)</p> </section> <section id="requires"> <h3>Requires<a class="headerlink" href="#requires" title="Link to this heading">#</a></h3> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.1.</span></p> </div> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 1.2: </span>in favour of <code class="docutils literal notranslate"><span class="pre">Requires-Dist</span></code></p> </div> <p>Each entry contains a string describing some other module or package required by this package.</p> <p>The format of a requirement string is identical to that of a module or package name usable with the <code class="docutils literal notranslate"><span class="pre">import</span></code> statement, optionally followed by a version declaration within parentheses.</p> <p>A version declaration is a series of conditional operators and version numbers, separated by commas. Conditional operators must be one of “<”, “>”’, “<=”, “>=”, “==”, and “!=”. Version numbers must be in the format accepted by the <code class="docutils literal notranslate"><span class="pre">distutils.version.StrictVersion</span></code> class: two or three dot-separated numeric components, with an optional “pre-release” tag on the end consisting of the letter ‘a’ or ‘b’ followed by a number. Example version numbers are “1.0”, “2.3a2”, “1.3.99”,</p> <p>Any number of conditional operators can be specified, e.g. the string “>1.0, !=1.3.4, <2.0” is a legal version declaration.</p> <p>All of the following are possible requirement strings: “rfc822”, “zlib (>=1.1.4)”, “zope”.</p> <p>There’s no canonical list of what strings should be used; the Python community is left to choose its own standards.</p> <p>Examples:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Requires: re Requires: sys Requires: zlib Requires: xml.parsers.expat (>1.0) Requires: psycopg </pre></div> </div> </section> <section id="provides"> <h3>Provides<a class="headerlink" href="#provides" title="Link to this heading">#</a></h3> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.1.</span></p> </div> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 1.2: </span>in favour of <code class="docutils literal notranslate"><span class="pre">Provides-Dist</span></code></p> </div> <p>Each entry contains a string describing a package or module that will be provided by this package once it is installed. These strings should match the ones used in Requirements fields. A version declaration may be supplied (without a comparison operator); the package’s version number will be implied if none is specified.</p> <p>Examples:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Provides: xml Provides: xml.utils Provides: xml.utils.iso8601 Provides: xml.dom Provides: xmltools (1.3) </pre></div> </div> </section> <section id="obsoletes"> <h3>Obsoletes<a class="headerlink" href="#obsoletes" title="Link to this heading">#</a></h3> <div class="versionadded"> <p><span class="versionmodified added">New in version 1.1.</span></p> </div> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 1.2: </span>in favour of <code class="docutils literal notranslate"><span class="pre">Obsoletes-Dist</span></code></p> </div> <p>Each entry contains a string describing a package or module that this package renders obsolete, meaning that the two packages should not be installed at the same time. Version declarations can be supplied.</p> <p>The most common use of this field will be in case a package name changes, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install Torqued Python, the Gorgon package should be removed.</p> <p>Example:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Obsoletes: Gorgon </pre></div> </div> </section> </section> <section id="history"> <h2>History<a class="headerlink" href="#history" title="Link to this heading">#</a></h2> <ul class="simple"> <li><p>March 2001: Core metadata 1.0 was approved through <span class="target" id="index-13"></span><a class="pep reference external" href="https://peps.python.org/pep-0241/"><strong>PEP 241</strong></a>.</p></li> <li><p>April 2003: Core metadata 1.1 was approved through <span class="target" id="index-14"></span><a class="pep reference external" href="https://peps.python.org/pep-0314/"><strong>PEP 314</strong></a>:</p></li> <li><p>February 2010: Core metadata 1.2 was approved through <span class="target" id="index-15"></span><a class="pep reference external" href="https://peps.python.org/pep-0345/"><strong>PEP 345</strong></a>.</p></li> <li><p>February 2018: Core metadata 2.1 was approved through <span class="target" id="index-16"></span><a class="pep reference external" href="https://peps.python.org/pep-0566/"><strong>PEP 566</strong></a>.</p> <ul> <li><p>Added <code class="docutils literal notranslate"><span class="pre">Description-Content-Type</span></code> and <code class="docutils literal notranslate"><span class="pre">Provides-Extra</span></code>.</p></li> <li><p>Added canonical method for transforming metadata to JSON.</p></li> <li><p>Restricted the grammar of the <code class="docutils literal notranslate"><span class="pre">Name</span></code> field.</p></li> </ul> </li> <li><p>October 2020: Core metadata 2.2 was approved through <span class="target" id="index-17"></span><a class="pep reference external" href="https://peps.python.org/pep-0643/"><strong>PEP 643</strong></a>.</p> <ul> <li><p>Added the <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code> field.</p></li> </ul> </li> <li><p>March 2022: Core metadata 2.3 was approved through <span class="target" id="index-18"></span><a class="pep reference external" href="https://peps.python.org/pep-0685/"><strong>PEP 685</strong></a>.</p> <ul> <li><p>Restricted extra names to be normalized.</p></li> </ul> </li> <li><p>August 2024: Core metadata 2.4 was approved through <span class="target" id="index-19"></span><a class="pep reference external" href="https://peps.python.org/pep-0639/"><strong>PEP 639</strong></a>.</p> <ul> <li><p>Added the <code class="docutils literal notranslate"><span class="pre">License-Expression</span></code> field.</p></li> <li><p>Added the <code class="docutils literal notranslate"><span class="pre">License-File</span></code> field.</p></li> </ul> </li> </ul> <hr class="docutils" /> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id3" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span> <p>reStructuredText markup: <a class="reference external" href="https://docutils.sourceforge.io/">https://docutils.sourceforge.io/</a></p> </aside> </aside> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id4" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id2">2</a><span class="fn-bracket">]</span></span> <p>RFC 822 Long Header Fields: <span class="target" id="index-20"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc822.html#section-3.1.1"><strong>RFC 822#section-3.1.1</strong></a></p> </aside> </aside> </section> </section> </article> </div> <footer> <div class="related-pages"> <a class="next-page" href="../version-specifiers/"> <div class="page-info"> <div class="context"> <span>Next</span> </div> <div class="title">Version specifiers</div> </div> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> </a> <a class="prev-page" href="../name-normalization/"> <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">Names and normalization</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 Nov 24, 2024</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="#">Core metadata specifications</a><ul> <li><a class="reference internal" href="#metadata-version">Metadata-Version</a></li> <li><a class="reference internal" href="#name">Name</a></li> <li><a class="reference internal" href="#version">Version</a></li> <li><a class="reference internal" href="#dynamic-multiple-use">Dynamic (multiple use)</a></li> <li><a class="reference internal" href="#platform-multiple-use">Platform (multiple use)</a></li> <li><a class="reference internal" href="#supported-platform-multiple-use">Supported-Platform (multiple use)</a></li> <li><a class="reference internal" href="#summary">Summary</a></li> <li><a class="reference internal" href="#description">Description</a></li> <li><a class="reference internal" href="#description-content-type">Description-Content-Type</a></li> <li><a class="reference internal" href="#keywords">Keywords</a></li> <li><a class="reference internal" href="#author">Author</a></li> <li><a class="reference internal" href="#author-email">Author-email</a></li> <li><a class="reference internal" href="#maintainer">Maintainer</a></li> <li><a class="reference internal" href="#maintainer-email">Maintainer-email</a></li> <li><a class="reference internal" href="#license">License</a></li> <li><a class="reference internal" href="#license-expression">License-Expression</a></li> <li><a class="reference internal" href="#license-file-multiple-use">License-File (multiple use)</a></li> <li><a class="reference internal" href="#classifier-multiple-use">Classifier (multiple use)</a></li> <li><a class="reference internal" href="#requires-dist-multiple-use">Requires-Dist (multiple use)</a></li> <li><a class="reference internal" href="#requires-python">Requires-Python</a></li> <li><a class="reference internal" href="#requires-external-multiple-use">Requires-External (multiple use)</a></li> <li><a class="reference internal" href="#project-url-multiple-use">Project-URL (multiple-use)</a></li> <li><a class="reference internal" href="#provides-extra-multiple-use">Provides-Extra (multiple use)</a></li> <li><a class="reference internal" href="#rarely-used-fields">Rarely Used Fields</a><ul> <li><a class="reference internal" href="#provides-dist-multiple-use">Provides-Dist (multiple use)</a></li> <li><a class="reference internal" href="#obsoletes-dist-multiple-use">Obsoletes-Dist (multiple use)</a></li> </ul> </li> <li><a class="reference internal" href="#deprecated-fields">Deprecated Fields</a><ul> <li><a class="reference internal" href="#home-page">Home-page</a></li> <li><a class="reference internal" href="#download-url">Download-URL</a></li> <li><a class="reference internal" href="#requires">Requires</a></li> <li><a class="reference internal" href="#provides">Provides</a></li> <li><a class="reference internal" href="#obsoletes">Obsoletes</a></li> </ul> </li> <li><a class="reference internal" href="#history">History</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=32e29ea5"></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>