CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 566 – Metadata for Python Software Packages 2.1 | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0566/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 566 – Metadata for Python Software Packages 2.1 | peps.python.org'> <meta property="og:description" content="This PEP describes the changes between versions 1.2 and 2.1 of the core metadata specification for Python packages. Version 1.2 is specified in PEP 345."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0566/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP describes the changes between versions 1.2 and 2.1 of the core metadata specification for Python packages. Version 1.2 is specified in PEP 345."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</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"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</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"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <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"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</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"> <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> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 566</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> <span class="visually-hidden">Toggle light / dark / auto colour theme</span> </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 566 – Metadata for Python Software Packages 2.1</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Dustin Ingram <di at python.org></dd> <dt class="field-even">BDFL-Delegate<span class="colon">:</span></dt> <dd class="field-even">Daniel Holth</dd> <dt class="field-odd">Discussions-To<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="https://mail.python.org/archives/list/distutils-sig@python.org/">Distutils-SIG list</a></dd> <dt class="field-even">Status<span class="colon">:</span></dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Topic<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="../topic/packaging/">Packaging</a></dd> <dt class="field-odd">Created<span class="colon">:</span></dt> <dd class="field-odd">01-Dec-2017</dd> <dt class="field-even">Python-Version<span class="colon">:</span></dt> <dd class="field-even">3.x</dd> <dt class="field-odd">Post-History<span class="colon">:</span></dt> <dd class="field-odd"><p></p></dd> <dt class="field-even">Replaces<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="../pep-0345/">345</a></dd> <dt class="field-odd">Resolution<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="https://mail.python.org/pipermail/distutils-sig/2018-February/032014.html">Distutils-SIG message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#fields">Fields</a><ul> <li><a class="reference internal" href="#new-in-version-2-1">New in Version 2.1</a><ul> <li><a class="reference internal" href="#description-content-type-optional">Description-Content-Type (optional)</a></li> <li><a class="reference internal" href="#provides-extra-optional-multiple-use">Provides-Extra (optional, multiple use)</a></li> </ul> </li> <li><a class="reference internal" href="#changed-in-version-2-1">Changed in Version 2.1</a><ul> <li><a class="reference internal" href="#name">Name</a></li> <li><a class="reference internal" href="#description">Description</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#version-specifiers">Version Specifiers</a></li> <li><a class="reference internal" href="#environment-markers">Environment markers</a></li> <li><a class="reference internal" href="#json-compatible-metadata">JSON-compatible Metadata</a></li> <li><a class="reference internal" href="#summary-of-differences-from-pep-345">Summary of Differences From PEP 345</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> </ul> </details></section> <div class="pep-banner canonical-pypa-spec sticky-banner admonition attention"> <p class="admonition-title">Attention</p> <p>This PEP is a historical document. The up-to-date, canonical spec, <a class="reference external" href="https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata" title="(in Python Packaging User Guide)"><span>Core metadata specifications</span></a>, is maintained on the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/">PyPA specs page</a>.</p> <p class="close-button">×</p> <p>See the <a class="reference external" href="https://www.pypa.io/en/latest/specifications/#handling-fixes-and-other-minor-updates">PyPA specification update process</a> for how to propose changes.</p> </div> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> <p>This PEP describes the changes between versions 1.2 and 2.1 of the core metadata specification for Python packages. Version 1.2 is specified in <a class="pep reference internal" href="../pep-0345/" title="PEP 345 – Metadata for Python Software Packages 1.2">PEP 345</a>.</p> <p>It also changes to the canonical source for field specifications to the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core Metadata Specification</a> reference document, which includes specifics of the field names, and their semantics and usage.</p> </section> <section id="fields"> <h2><a class="toc-backref" href="#fields" role="doc-backlink">Fields</a></h2> <p>The canonical source for the names and semantics of each of the supported metadata fields is the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core Metadata Specification</a> document.</p> <p>Fields marked with “(Multiple use)” may be specified multiple times in a single PKG-INFO file. Other fields may only occur once in a PKG-INFO file. Fields marked with “(optional)” are not required to appear in a valid PKG-INFO file; all other fields must be present.</p> <section id="new-in-version-2-1"> <h3><a class="toc-backref" href="#new-in-version-2-1" role="doc-backlink">New in Version 2.1</a></h3> <section id="description-content-type-optional"> <h4><a class="toc-backref" href="#description-content-type-optional" role="doc-backlink">Description-Content-Type (optional)</a></h4> <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, tools like PyPI assume that a package’s description is formatted in <a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html">reStructuredText (reST)</a>, and fall back on plain text if the description is not valid reST.</p> <p>The introduction of this field allows PyPI to support additional types of markup syntax, and not need to make this assumption.</p> <p>The full specification for this field is defined in the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core Metadata Specification</a>.</p> </section> <section id="provides-extra-optional-multiple-use"> <h4><a class="toc-backref" href="#provides-extra-optional-multiple-use" role="doc-backlink">Provides-Extra (optional, multiple use)</a></h4> <p>A string containing the name of an optional feature. Must be a valid Python identifier. May be used to make a dependency conditional on whether the optional feature has been requested.</p> <p>This introduction of this field allows package installation tools (such as <code class="docutils literal notranslate"><span class="pre">pip</span></code>) to determine which extras are provided by a given package, and so that package publication tools (such as <code class="docutils literal notranslate"><span class="pre">twine</span></code>) can check for issues with environment markers which use extras.</p> <p>The full specification for this field is defined in the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core Metadata Specification</a>.</p> </section> </section> <section id="changed-in-version-2-1"> <h3><a class="toc-backref" href="#changed-in-version-2-1" role="doc-backlink">Changed in Version 2.1</a></h3> <section id="name"> <h4><a class="toc-backref" href="#name" role="doc-backlink">Name</a></h4> <p>The specification for the format of this field is now identical to the distribution name specification defined in <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>.</p> </section> <section id="description"> <h4><a class="toc-backref" href="#description" role="doc-backlink">Description</a></h4> <p>In addition to the <code class="docutils literal notranslate"><span class="pre">Description</span></code> header field, 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> </section> <section id="version-specifiers"> <h2><a class="toc-backref" href="#version-specifiers" role="doc-backlink">Version Specifiers</a></h2> <p>Version numbering requirements and the semantics for specifying comparisons between versions are defined in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a>. Direct references as defined in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> are also permitted as an alternative to version specifiers.</p> <p>Following <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>, version specifiers no longer need to be surrounded by parentheses in the fields Requires-Dist, Provides-Dist, Obsoletes-Dist or Requires-External, so e.g. <code class="docutils literal notranslate"><span class="pre">requests</span> <span class="pre">>=</span> <span class="pre">2.8.1</span></code> is now a valid value. The recommended format is without parentheses, but tools parsing metadata should also be able to handle version specifiers in parentheses. Further, public index servers MAY prohibit strict version matching clauses or direct references in these fields.</p> <p>Usage of version specifiers is otherwise unchanged from <a class="pep reference internal" href="../pep-0345/" title="PEP 345 – Metadata for Python Software Packages 1.2">PEP 345</a>.</p> </section> <section id="environment-markers"> <h2><a class="toc-backref" href="#environment-markers" role="doc-backlink">Environment markers</a></h2> <p>An <strong>environment marker</strong> is a marker that can be added at the end of a field after a semi-colon (“;”), to add a condition about the execution environment.</p> <p>The environment marker format used to declare such a condition is defined in the environment markers section of <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>.</p> <p>Usage of environment markers is otherwise unchanged from <a class="pep reference internal" href="../pep-0345/" title="PEP 345 – Metadata for Python Software Packages 1.2">PEP 345</a>.</p> </section> <section id="json-compatible-metadata"> <h2><a class="toc-backref" href="#json-compatible-metadata" role="doc-backlink">JSON-compatible Metadata</a></h2> <p>It may be necessary to store metadata in a data structure which does not allow for multiple repeated keys, such as JSON.</p> <p>The canonical method to transform metadata fields into such a data structure is as follows:</p> <ol class="arabic simple"> <li>The original key-value format should be read with <code class="docutils literal notranslate"><span class="pre">email.parser.HeaderParser</span></code>;</li> <li>All transformed keys should be reduced to lower case. Hyphens should be replaced with underscores, but otherwise should retain all other characters;</li> <li>The transformed value for any field marked with “(Multiple-use”) should be a single list containing all the original values for the given key;</li> <li>The <code class="docutils literal notranslate"><span class="pre">Keywords</span></code> field should be converted to a list by splitting the original value on commas;</li> <li>The message body, if present, should be set to the value of the <code class="docutils literal notranslate"><span class="pre">description</span></code> key.</li> <li>The result should be stored as a string-keyed dictionary.</li> </ol> </section> <section id="summary-of-differences-from-pep-345"> <h2><a class="toc-backref" href="#summary-of-differences-from-pep-345" role="doc-backlink">Summary of Differences From PEP 345</a></h2> <ul class="simple"> <li>Metadata-Version is now 2.1.</li> <li>Fields are now specified via the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core Metadata Specification</a>.</li> <li>Added two new fields: <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></li> <li>Acceptable values for the <code class="docutils literal notranslate"><span class="pre">Name</span></code> field are now specified as per <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>.</li> <li>Added canonical method of transformation into JSON-compatible data structure.</li> </ul> </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <p>This document specifies version 2.1 of the metadata format. Version 1.0 is specified in <a class="pep reference internal" href="../pep-0241/" title="PEP 241 – Metadata for Python Software Packages">PEP 241</a>. Version 1.1 is specified in <a class="pep reference internal" href="../pep-0314/" title="PEP 314 – Metadata for Python Software Packages 1.1">PEP 314</a>. Version 1.2 is specified in <a class="pep reference internal" href="../pep-0345/" title="PEP 345 – Metadata for Python Software Packages 1.2">PEP 345</a>. Version 2.0, while not formally accepted, was specified in <a class="pep reference internal" href="../pep-0426/" title="PEP 426 – Metadata for Python Software Packages 2.0">PEP 426</a>.</p> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> <p>This document has been placed in the public domain.</p> </section> <section id="acknowledgements"> <h2><a class="toc-backref" href="#acknowledgements" role="doc-backlink">Acknowledgements</a></h2> <p>Thanks to Alyssa Coghlan and Thomas Kluyver for contributing to this PEP.</p> </section> </section> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0566.rst">https://github.com/python/peps/blob/main/peps/pep-0566.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0566.rst">2023-10-11 12:05:51 GMT</a></p> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#fields">Fields</a><ul> <li><a class="reference internal" href="#new-in-version-2-1">New in Version 2.1</a><ul> <li><a class="reference internal" href="#description-content-type-optional">Description-Content-Type (optional)</a></li> <li><a class="reference internal" href="#provides-extra-optional-multiple-use">Provides-Extra (optional, multiple use)</a></li> </ul> </li> <li><a class="reference internal" href="#changed-in-version-2-1">Changed in Version 2.1</a><ul> <li><a class="reference internal" href="#name">Name</a></li> <li><a class="reference internal" href="#description">Description</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#version-specifiers">Version Specifiers</a></li> <li><a class="reference internal" href="#environment-markers">Environment markers</a></li> <li><a class="reference internal" href="#json-compatible-metadata">JSON-compatible Metadata</a></li> <li><a class="reference internal" href="#summary-of-differences-from-pep-345">Summary of Differences From PEP 345</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0566.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>