This is a technical, formal specification. For a gentle,
user-friendly guide to
Writing your pyproject.toml.
pyproject.toml file acts as a configuration file for packaging-related
tools (as well as other tools).
pyproject.toml file is written in TOML. Three
tables are currently specified, namely
[tool]. Other tables are reserved for future
use (tool-specific configuration should use the
Declaring build system dependencies: the
[build-system] table declares any Python level dependencies that
must be installed in order to run the project’s build system
[build-system] table is used to store build-related data.
Initially, only one key of the table is valid and is mandatory
for the table:
requires. This key must have a value of a list
of strings representing dependencies required to execute the
build system. The strings in this list follow the version specifier
[build-system] table for a project built with
# Minimum requirements for the build system to execute.
requires = ["setuptools"]
Build tools are expected to use the example configuration file above as
their default semantics when a
pyproject.toml file is not present.
Tools should not require the existence of the
pyproject.toml file may be used to store configuration details
other than build-related data and thus lack a
legitimately. If the file exists but is lacking the
table then the default values as specified above should be used.
If the table is specified but is missing required fields then the tool
should consider it an error.
To provide a type-specific representation of the resulting data from the TOML file for illustrative purposes only, the following JSON Schema would match the data format:
Declaring project metadata: the
[project] table specifies the project’s core metadata.
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 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).
Arbitrary tool configuration: the
[tool] table is where any tool related to your Python
project, not just build tools, can have users specify configuration
data as long as they use a sub-table within
[tool], e.g. the
flit tool would store its
A mechanism is needed to allocate names within the
namespace, to make sure that different projects do not attempt to use
the same sub-table and collide. Our rule is that a project can use
tool.$NAME if, and only if, they own the entry for
$NAME in the Cheeseshop/PyPI.