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 241 – Metadata for Python Software Packages | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0241/"> <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 241 – Metadata for Python Software Packages | peps.python.org'> <meta property="og:description" content="This PEP describes a mechanism for adding metadata to Python packages. It includes specifics of the field names, and their semantics and usage."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0241/"> <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 a mechanism for adding metadata to Python packages. It includes specifics of the field names, and their semantics and usage."> <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 241</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 241 – Metadata for Python Software Packages</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">A.M. Kuchling <amk at amk.ca></dd> <dt class="field-even">Discussions-To<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="https://mail.python.org/archives/list/distutils-sig@python.org/">Distutils-SIG list</a></dd> <dt class="field-odd">Status<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Replaced by another succeeding PEP">Superseded</abbr></dd> <dt class="field-even">Type<span class="colon">:</span></dt> <dd class="field-even"><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-odd">Topic<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="../topic/packaging/">Packaging</a></dd> <dt class="field-even">Created<span class="colon">:</span></dt> <dd class="field-even">12-Mar-2001</dd> <dt class="field-odd">Post-History<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="https://mail.python.org/archives/list/distutils-sig@python.org/thread/46XPDHQHI3XAAJHEZAMAMKZYAI6K7NB6/" title="Distutils-SIG thread">19-Mar-2001</a></dd> <dt class="field-even">Superseded-By<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="../pep-0314/">314</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#introduction">Introduction</a></li> <li><a class="reference internal" href="#including-metadata-in-packages">Including Metadata in Packages</a></li> <li><a class="reference internal" href="#fields">Fields</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="#platform-multiple-use">Platform (multiple use)</a></li> <li><a class="reference internal" href="#summary">Summary</a></li> <li><a class="reference internal" href="#description-optional">Description (optional)</a></li> <li><a class="reference internal" href="#keywords-optional">Keywords (optional)</a></li> <li><a class="reference internal" href="#home-page-optional">Home-page (optional)</a></li> <li><a class="reference internal" href="#author-optional">Author (optional)</a></li> <li><a class="reference internal" href="#author-email">Author-email</a></li> <li><a class="reference internal" href="#license">License</a></li> </ul> </li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> <li><a class="reference internal" href="#copyright">Copyright</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="introduction"> <h2><a class="toc-backref" href="#introduction" role="doc-backlink">Introduction</a></h2> <p>This PEP describes a mechanism for adding metadata to Python packages. It includes specifics of the field names, and their semantics and usage.</p> </section> <section id="including-metadata-in-packages"> <h2><a class="toc-backref" href="#including-metadata-in-packages" role="doc-backlink">Including Metadata in Packages</a></h2> <p>The Distutils ‘sdist’ command will be modified to extract the metadata fields from the arguments and write them to a file in the generated zipfile or tarball. This file will be named PKG-INFO and will be placed in the top directory of the source distribution (where the README, INSTALL, and other files usually go).</p> <p>Developers may not provide their own PKG-INFO file. The “sdist” command will, if it detects an existing PKG-INFO file, terminate with an appropriate error message. This should prevent confusion caused by the PKG-INFO and setup.py files being out of sync.</p> <p>The PKG-INFO file format is a single set of <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc822.html"><strong>RFC 822</strong></a> headers parseable by the rfc822.py module. The field names listed in the following section are used as the header names. There’s no extension mechanism in this simple format; the Catalog and Distutils SIGs will aim at getting a more flexible format ready for Python 2.2.</p> </section> <section id="fields"> <h2><a class="toc-backref" href="#fields" role="doc-backlink">Fields</a></h2> <p>This section specifies the names and semantics of each of the supported metadata fields.</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="metadata-version"> <h3><a class="toc-backref" href="#metadata-version" role="doc-backlink">Metadata-Version</a></h3> <p>Version of the file format; currently “1.0” is the only legal value here.</p> <p>Example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Metadata</span><span class="o">-</span><span class="n">Version</span><span class="p">:</span> <span class="mf">1.0</span> </pre></div> </div> </section> <section id="name"> <h3><a class="toc-backref" href="#name" role="doc-backlink">Name</a></h3> <p>The name of the package.</p> <p>Example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Name</span><span class="p">:</span> <span class="n">BeagleVote</span> </pre></div> </div> </section> <section id="version"> <h3><a class="toc-backref" href="#version" role="doc-backlink">Version</a></h3> <p>A string containing the package’s version number. This field should be parseable by one of the Version classes (StrictVersion or LooseVersion) in the distutils.version module.</p> <p>Example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Version</span><span class="p">:</span> <span class="mf">1.0</span><span class="n">a2</span> </pre></div> </div> </section> <section id="platform-multiple-use"> <h3><a class="toc-backref" href="#platform-multiple-use" role="doc-backlink">Platform (multiple use)</a></h3> <p>A comma-separated list of platform specifications, summarizing the operating systems supported by the package. The major supported platforms are listed below, but this list is necessarily incomplete.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">POSIX</span><span class="p">,</span> <span class="n">MacOS</span><span class="p">,</span> <span class="n">Windows</span><span class="p">,</span> <span class="n">BeOS</span><span class="p">,</span> <span class="n">Palm</span> <span class="n">OS</span><span class="o">.</span> </pre></div> </div> <p>Binary distributions will use the Supported-Platform field in their metadata to specify the OS and CPU for which the binary package was compiled. The semantics of the Supported-Platform are not specified in this PEP.</p> <p>Example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Platform</span><span class="p">:</span> <span class="n">POSIX</span><span class="p">,</span> <span class="n">Windows</span> </pre></div> </div> </section> <section id="summary"> <h3><a class="toc-backref" href="#summary" role="doc-backlink">Summary</a></h3> <p>A one-line summary of what the package does.</p> <p>Example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Summary</span><span class="p">:</span> <span class="n">A</span> <span class="n">module</span> <span class="k">for</span> <span class="n">collecting</span> <span class="n">votes</span> <span class="kn">from</span> <span class="nn">beagles.</span> </pre></div> </div> </section> <section id="description-optional"> <h3><a class="toc-backref" href="#description-optional" role="doc-backlink">Description (optional)</a></h3> <p>A longer description of the package that can run to several paragraphs. (Software that deals with metadata should not assume any maximum size for this field, though one hopes that people won’t include their instruction manual as the long-description.)</p> <p>Example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Description</span><span class="p">:</span> <span class="n">This</span> <span class="n">module</span> <span class="n">collects</span> <span class="n">votes</span> <span class="kn">from</span> <span class="nn">beagles</span> <span class="ow">in</span> <span class="n">order</span> <span class="n">to</span> <span class="n">determine</span> <span class="n">their</span> <span class="n">electoral</span> <span class="n">wishes</span><span class="o">.</span> <span class="n">Do</span> <span class="n">NOT</span> <span class="k">try</span> <span class="n">to</span> <span class="n">use</span> <span class="n">this</span> <span class="n">module</span> <span class="k">with</span> <span class="n">basset</span> <span class="n">hounds</span><span class="p">;</span> <span class="n">it</span> <span class="n">makes</span> <span class="n">them</span> <span class="n">grumpy</span><span class="o">.</span> </pre></div> </div> </section> <section id="keywords-optional"> <h3><a class="toc-backref" href="#keywords-optional" role="doc-backlink">Keywords (optional)</a></h3> <p>A list of additional keywords to be used to assist searching for the package in a larger catalog.</p> <p>Example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Keywords</span><span class="p">:</span> <span class="n">dog</span> <span class="n">puppy</span> <span class="n">voting</span> <span class="n">election</span> </pre></div> </div> </section> <section id="home-page-optional"> <h3><a class="toc-backref" href="#home-page-optional" role="doc-backlink">Home-page (optional)</a></h3> <p>A string containing the URL for the package’s home page.</p> <p>Example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Home</span><span class="o">-</span><span class="n">page</span><span class="p">:</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/~</span><span class="n">cschultz</span><span class="o">/</span><span class="n">bvote</span><span class="o">/</span> </pre></div> </div> </section> <section id="author-optional"> <h3><a class="toc-backref" href="#author-optional" role="doc-backlink">Author (optional)</a></h3> <p>A string containing at a minimum the author’s name. Contact information can also be added, separating each line with newlines.</p> <p>Example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Author</span><span class="p">:</span> <span class="n">C</span><span class="o">.</span> <span class="n">Schultz</span> <span class="n">Universal</span> <span class="n">Features</span> <span class="n">Syndicate</span> <span class="n">Los</span> <span class="n">Angeles</span><span class="p">,</span> <span class="n">CA</span> </pre></div> </div> </section> <section id="author-email"> <h3><a class="toc-backref" href="#author-email" role="doc-backlink">Author-email</a></h3> <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 <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc822.html"><strong>RFC 822</strong></a> ‘From:’ header. It’s not optional because cataloging systems can use the e-mail portion of this field as a unique key representing the author. A catalog might provide authors the ability to store their GPG key, personal home page, and other additional metadata <em>about the author</em>, and optionally the ability to associate several e-mail addresses with the same person. Author-related metadata fields are not covered by this PEP.</p> <p>Example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Author</span><span class="o">-</span><span class="n">email</span><span class="p">:</span> <span class="s2">"C. Schultz"</span> <span class="o"><</span><span class="n">cschultz</span><span class="nd">@example</span><span class="o">.</span><span class="n">com</span><span class="o">></span> </pre></div> </div> </section> <section id="license"> <h3><a class="toc-backref" href="#license" role="doc-backlink">License</a></h3> <p>A string selected from a short list of choices, specifying the license covering the package. Some licenses result in the software being freely redistributable, so packagers and resellers can automatically know that they’re free to redistribute the software. Other licenses will require a careful reading by a human to determine how the software can be repackaged and resold.</p> <p>The choices are:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Artistic</span><span class="p">,</span> <span class="n">BSD</span><span class="p">,</span> <span class="n">DFSG</span><span class="p">,</span> <span class="n">GNU</span> <span class="n">GPL</span><span class="p">,</span> <span class="n">GNU</span> <span class="n">LGPL</span><span class="p">,</span> <span class="s2">"MIT"</span><span class="p">,</span> <span class="n">Mozilla</span> <span class="n">PL</span><span class="p">,</span> <span class="s2">"public domain"</span><span class="p">,</span> <span class="n">Python</span><span class="p">,</span> <span class="n">Qt</span> <span class="n">PL</span><span class="p">,</span> <span class="n">Zope</span> <span class="n">PL</span><span class="p">,</span> <span class="n">unknown</span><span class="p">,</span> <span class="n">nocommercial</span><span class="p">,</span> <span class="n">nosell</span><span class="p">,</span> <span class="n">nosource</span><span class="p">,</span> <span class="n">shareware</span><span class="p">,</span> <span class="n">other</span> </pre></div> </div> <p>Definitions of some of the licenses are:</p> <table class="docutils align-default"> <tbody> <tr class="row-odd"><td>DFSG</td> <td>The license conforms to the Debian Free Software Guidelines, but does not use one of the other DFSG conforming licenses listed here. More information is available at: <a class="reference external" href="http://www.debian.org/social_contract#guidelines">http://www.debian.org/social_contract#guidelines</a></td> </tr> <tr class="row-even"><td>Python</td> <td>Python 1.6 or higher license. Version 1.5.2 and earlier are under the MIT license.</td> </tr> <tr class="row-odd"><td>public domain</td> <td>Software is public domain, not copyrighted.</td> </tr> <tr class="row-even"><td>unknown</td> <td>Status is not known</td> </tr> <tr class="row-odd"><td>nocommercial</td> <td>Free private use but commercial use not permitted</td> </tr> <tr class="row-even"><td>nosell</td> <td>Free use but distribution for profit by arrangement</td> </tr> <tr class="row-odd"><td>nosource</td> <td>Freely distributable but no source code</td> </tr> <tr class="row-even"><td>shareware</td> <td>Payment is requested if software is used</td> </tr> <tr class="row-odd"><td>other</td> <td>General category for other non-DFSG licenses</td> </tr> </tbody> </table> <p>Some of these licenses can be interpreted to mean the software is freely redistributable. The list of redistributable licenses is:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Artistic</span><span class="p">,</span> <span class="n">BSD</span><span class="p">,</span> <span class="n">DFSG</span><span class="p">,</span> <span class="n">GNU</span> <span class="n">GPL</span><span class="p">,</span> <span class="n">GNU</span> <span class="n">LGPL</span><span class="p">,</span> <span class="s2">"MIT"</span><span class="p">,</span> <span class="n">Mozilla</span> <span class="n">PL</span><span class="p">,</span> <span class="s2">"public domain"</span><span class="p">,</span> <span class="n">Python</span><span class="p">,</span> <span class="n">Qt</span> <span class="n">PL</span><span class="p">,</span> <span class="n">Zope</span> <span class="n">PL</span><span class="p">,</span> <span class="n">nosource</span><span class="p">,</span> <span class="n">shareware</span> </pre></div> </div> <p>Note that being redistributable does not mean a package qualifies as free software, ‘nosource’ and ‘shareware’ being examples.</p> <p>Example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">License</span><span class="p">:</span> <span class="n">MIT</span> </pre></div> </div> </section> </section> <section id="acknowledgements"> <h2><a class="toc-backref" href="#acknowledgements" role="doc-backlink">Acknowledgements</a></h2> <p>Many changes and rewrites to this document were suggested by the readers of the Distutils SIG. In particular, Sean Reifschneider often contributed actual text for inclusion in this PEP.</p> <p>The list of licenses was compiled using the SourceForge license list and the CTAN license list compiled by Graham Williams; Carey Evans also offered several useful suggestions on this list.</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> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0241.rst">https://github.com/python/peps/blob/main/peps/pep-0241.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0241.rst">2024-10-06 16:27:00 GMT</a></p> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#introduction">Introduction</a></li> <li><a class="reference internal" href="#including-metadata-in-packages">Including Metadata in Packages</a></li> <li><a class="reference internal" href="#fields">Fields</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="#platform-multiple-use">Platform (multiple use)</a></li> <li><a class="reference internal" href="#summary">Summary</a></li> <li><a class="reference internal" href="#description-optional">Description (optional)</a></li> <li><a class="reference internal" href="#keywords-optional">Keywords (optional)</a></li> <li><a class="reference internal" href="#home-page-optional">Home-page (optional)</a></li> <li><a class="reference internal" href="#author-optional">Author (optional)</a></li> <li><a class="reference internal" href="#author-email">Author-email</a></li> <li><a class="reference internal" href="#license">License</a></li> </ul> </li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0241.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>