Declaring project metadata#
PEP 621 specifies how to write a project’s
core metadata in a
pyproject.toml file for
packaging-related tools to consume. It defines the following
specification as the canonical source for the format used.
This is a technical, formal specification. For a gentle,
user-friendly guide to
Writing your pyproject.toml.
There are two kinds of metadata: static and dynamic. Static
metadata is specified in the
pyproject.toml file directly and
cannot be specified or changed by a tool (this includes data
referred to by the metadata, e.g. the contents of files referenced
by the metadata). Dynamic metadata is listed via the
(defined later in this specification) and represents metadata that a
tool will later provide.
The keys defined in this specification MUST be in a table named
pyproject.toml. No tools may add keys to this
table which are not defined by this specification. For tools wishing
to store their own settings in
pyproject.toml, they may use the
[tool] table as defined in the
build dependency declaration specification.
The lack of a
[project] table implicitly means the build backend
will dynamically provide all keys.
The only keys required to be statically defined are:
The keys which are required but may be specified either statically or listed as dynamic are:
All other keys are considered optional and may be specified statically, listed as dynamic, or left unspecified.
The complete list of keys allowed in the
[project] table are:
The name of the project.
Tools SHOULD normalize this name, as soon as it is read for internal consistency.
The version of the project, as defined in the Version specifier specification.
Users SHOULD prefer to specify already-normalized versions.
The summary description of the project.
TOML type: string or table
The full description of the project (i.e. the README).
The key accepts either a string or a table. If it is a string then
it is a path relative to
pyproject.toml to a text file containing
the full description. Tools MUST assume the file’s encoding is UTF-8.
If the file path ends in a case-insensitive
.md suffix, then tools
MUST assume the content-type is
text/markdown. If the file path
ends in a case-insensitive
.rst, then tools MUST assume the
text/x-rst. If a tool recognizes more extensions
than this PEP, they MAY infer the content-type for the user without
specifying this key as
dynamic. For all unrecognized suffixes
when a content-type is not provided, tools MUST raise an error.
readme key may also take a table. The
file key has a
string value representing a path relative to
pyproject.toml to a
file containing the full description. The
text key has a string
value which is the full description. These keys are
mutually-exclusive, thus tools MUST raise an error if the metadata
specifies both keys.
A table specified in the
readme key also has a
key which takes a string specifying the content-type of the full
description. A tool MUST raise an error if the metadata does not
specify this key in the table. If the metadata does not specify the
charset parameter, then it is assumed to be UTF-8. Tools MAY
support other encodings if they choose to. Tools MAY support
alternative content-types which they can transform to a content-type
as supported by the core metadata. Otherwise
tools MUST raise an error for unsupported content-types.
The Python version requirements of the project.
The table may have one of two keys. The
file key has a string
value that is a file path relative to
pyproject.toml to the file
which contains the license for the project. Tools MUST assume the
file’s encoding is UTF-8. The
text key has a string value which is
the license of the project. These keys are mutually exclusive, so a
tool MUST raise an error if the metadata specifies both keys.
The keywords for the project.
Trove classifiers which apply to the project.
A table of URLs where the key is the URL label and the value is the URL itself.
TOML type: table (
There are three tables related to entry points. The
[project.scripts] table corresponds to the
group in the entry points specification. The key
of the table is the name of the entry point and the value is the
[project.gui-scripts] table corresponds to the
group in the entry points specification. Its
format is the same as
[project.entry-points] table is a collection of tables. Each
sub-table’s name is an entry point group. The key and value semantics
are the same as
[project.scripts]. Users MUST NOT create
nested sub-tables but instead keep the entry point groups to only one
Build back-ends MUST raise an error if the metadata defines a
[project.entry-points.gui_scripts] table, as they would
be ambiguous in the face of
The (optional) dependencies of the project.
dependencies, it is a key whose value is an array of strings.
Each string represents a dependency of the project and MUST be
formatted as a valid PEP 508 string. Each string maps directly to
a Requires-Dist entry.
optional-dependencies, it is a table where each key specifies
an extra and whose value is an array of strings. The strings of the
arrays must be valid PEP 508 strings. The keys MUST be valid values
for Provides-Extra. Each value
in the array thus becomes a corresponding
Requires-Dist entry for the
Specifies which keys listed by this PEP were intentionally unspecified so another tool can/will provide such metadata dynamically. This clearly delineates which metadata is purposefully unspecified and expected to stay unspecified compared to being provided via tooling later on.
A build back-end MUST honour statically-specified metadata (which means the metadata did not list the key in
A build back-end MUST raise an error if the metadata specifies
If the core metadata specification lists a field as “Required”, then the metadata MUST specify the key statically or list it in
dynamic(build back-ends MUST raise an error otherwise, i.e. it should not be possible for a required key to not be listed somehow in the
If the core metadata specification lists a field as “Optional”, the metadata MAY list it in
dynamicif the expectation is a build back-end will provide the data for the key later.
Build back-ends MUST raise an error if the metadata specifies a key statically as well as being listed in
If the metadata does not list a key in
dynamic, then a build back-end CANNOT fill in the requisite metadata on behalf of the user (i.e.
dynamicis the only way to allow a tool to fill in metadata and the user must opt into the filling in).
Build back-ends MUST raise an error if the metadata specifies a key in
dynamicbut the build back-end was unable to determine the data for it (omitting the data, if determined to be the accurate value, is acceptable).