Text of packaging.python.org › en › latest › specifications › core-metadata as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Core metadata specifications - Python Packaging User Guide

Skip to content Back to top View this page Edit this page Core metadata specifications ¶ This page describes version 2.6, approved in May 2026. Fields defined in the following specification should be considered valid, complete and not subject to change. The required fields are: Metadata-Version Name Version All the other fields are optional. The standard file format for metadata (including in wheels and installed projects ) 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 email.parser module can parse using the compat32 policy. Whenever metadata is serialised to a byte stream (for example, to save to a file), strings must be serialised using the UTF-8 encoding.

Although PEP 566 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. Note Interpreting old metadata: In PEP 566 , 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. Metadata-Version ¶ Added in version 1.0. Version of the file format; legal values are “1.0”, “1.1”, “1.2”, “2.1”, “2.2”, “2.3”, “2.4”, “2.5”, and “2.6”. Automated tools consuming metadata SHOULD warn if metadata-version is greater than the highest version they support, and MUST fail if metadata-version has a greater major version than the highest version they support (as described in the Version specifier specification , the major version is the value before the first dot).

For broader compatibility, build tools MAY choose to produce distribution metadata using the lowest metadata version that includes all of the needed fields. Example: Metadata-Version: 2.4 Name ¶ Added in version 1.0. Changed in version 2.1: Added restrictions on format from the name format . The name of the distribution. The name field is the primary identifier for a distribution. It must conform to the name format specification .

Example: Name: BeagleVote For comparison purposes, the names should be normalized before comparing. Version ¶ Added in version 1.0. A string containing the distribution’s version number. This field must be in the format specified in the Version specifier specification . Example: Version: 1.0a2 Dynamic (multiple use) ¶ Added in version 2.2. Changed in version 2.6: A multiple use field that is present in the sdist and also marked Dynamic may only be appended to in a wheel built from the sdist.

Previously any field listed in Dynamic was ignored in an sdist. A string containing the name of another core metadata field. The field names Name , Version , and Metadata-Version may not be specified in this field. When found in the metadata of a source distribution, the following rules apply: If a field is not marked as Dynamic , 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 Dynamic , then it MUST NOT be present in the wheel. If a single-use field is marked as Dynamic , it may contain any valid value in a wheel built from the sdist (including not being present at all). If a multiple use field is present in the sdist and also marked Dynamic , then a wheel built from the sdist MUST include the value(s) present in the sdist. The wheel MAY add further values, but it MUST NOT remove, reorder, or modify the values present in the sdist.

If the sdist metadata version is older than version 2.2, then all fields should be treated as if they were specified with Dynamic (i.e. there are no special restrictions on the metadata of wheels built from the sdist). In any context other than a source distribution, Dynamic 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.

Note in particular that if you have obtained a prebuilt wheel, you cannot assume that a field which is not marked as Dynamic will have the same value in other wheels, as some wheels are not built directly from the sdist, but are modified from existing wheels (the auditwheel tool does this, for example, and it’s commonly used when building wheels for PyPI). Such modifications could include changing metadata (even non-dynamic metadata).

Similarly, if you have a sdist and a wheel which you didn’t build from that sdist, you cannot assume that the wheel’s metadata matches that of the sdist, even if the field is not marked as Dynamic . Full details of the semantics of Dynamic are described in PEP 643 . Platform (multiple use) ¶ Added in version 1.0. A Platform specification describing an operating system supported by the distribution which is not listed in the “Operating System” Trove classifiers.

See “Classifier” below. Examples: Platform: ObscureUnix Platform: RareDOS Supported-Platform (multiple use) ¶ Added in version 1.1. 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. Example: Supported-Platform: RedHat 7.2 Supported-Platform: i386-win32-2791 Summary ¶ Added in version 1.0.

A one-line summary of what the distribution does. Example: Summary: A module for collecting votes from beagles. Description ¶ Added in version 1.0. Changed in version 2.1: This field may be specified in the message body instead. 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.

The contents of this field can be written using reStructuredText markup [ 1 ] . 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. 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 [ 2 ] . Example: Description: This project provides powerful math functions |For example, you can use `sum()` to sum numbers: | |Example:: | | >>> sum(1, 2) | 3 | 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.

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). Description-Content-Type ¶ Added in version 2.1. A string stating the markup syntax (if any) used in the distribution’s description, so that tools can intelligently render the description. Historically, PyPI supported descriptions in plain text and reStructuredText (reST) , and could render reST into HTML.

However, it is common for distribution authors to write the description in Markdown ( RFC 7763 ) 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 r

The rest of this page is on the live site.