pyproject.toml specification#
Warning
This is a technical, formal specification. For a gentle,
user-friendly guide to pyproject.toml, see
Writing your pyproject.toml.
The pyproject.toml file acts as a configuration file for packaging-related
tools (as well as other tools).
The pyproject.toml file is written in TOML. Three
tables are currently specified, namely
[build-system],
[project] and
[tool]. Other tables are reserved for future
use (tool-specific configuration should use the [tool] table).
Declaring build system dependencies: the [build-system] table#
The [build-system] table declares any Python level dependencies that
must be installed in order to run the project’s build system
successfully.
The [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
specification.
An example [build-system] table for a project built with
setuptools is:
[build-system]
# 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 [build-system] table.
A pyproject.toml file may be used to store configuration details
other than build-related data and thus lack a [build-system] table
legitimately. If the file exists but is lacking the [build-system]
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:
{
"$schema": "http://json-schema.org/schema#",
"type": "object",
"additionalProperties": false,
"properties": {
"build-system": {
"type": "object",
"additionalProperties": false,
"properties": {
"requires": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["requires"]
},
"tool": {
"type": "object"
}
}
}
Declaring project metadata: the [project] table#
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 dynamic key
(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:
name
The keys which are required but may be specified either statically or listed as dynamic are:
version
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:
authorsclassifiersdependenciesdescriptiondynamicentry-pointsgui-scriptskeywordslicensemaintainersnameoptional-dependenciesreadmerequires-pythonscriptsurlsversion
name#
TOML type: string
Corresponding core metadata field: Name
The name of the project.
Tools SHOULD normalize this name, as soon as it is read for internal consistency.
version#
TOML type: string
Corresponding core metadata field: Version
The version of the project, as defined in the Version specifier specification.
Users SHOULD prefer to specify already-normalized versions.
description#
TOML type: string
Corresponding core metadata field: Summary
The summary description of the project in one line. Tools MAY error if this includes multiple lines.
readme#
TOML type: string or table
Corresponding core metadata field: Description and Description-Content-Type
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
content-type is 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.
The 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 content-type
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.
requires-python#
TOML type: string
Corresponding core metadata field: Requires-Python
The Python version requirements of the project.
license#
TOML type: table
Corresponding core metadata field: License
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.
keywords#
TOML type: array of strings
Corresponding core metadata field: Keywords
The keywords for the project.
classifiers#
TOML type: array of strings
Corresponding core metadata field: Classifier
Trove classifiers which apply to the project.
urls#
TOML type: table with keys and values of strings
Corresponding core metadata field: Project-URL
A table of URLs where the key is the URL label and the value is the URL itself.
Entry points#
TOML type: table (
[project.scripts],[project.gui-scripts], and[project.entry-points])
There are three tables related to entry points. The
[project.scripts] table corresponds to the console_scripts
group in the entry points specification. The key
of the table is the name of the entry point and the value is the
object reference.
The [project.gui-scripts] table corresponds to the gui_scripts
group in the entry points specification. Its
format is the same as [project.scripts].
The [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
level deep.
Build back-ends MUST raise an error if the metadata defines a
[project.entry-points.console_scripts] or
[project.entry-points.gui_scripts] table, as they would
be ambiguous in the face of [project.scripts] and
[project.gui-scripts], respectively.
dependencies/optional-dependencies#
TOML type: Array of PEP 508 strings (
dependencies), and a table with values of arrays of PEP 508 strings (optional-dependencies)Corresponding core metadata field: Requires-Dist and Provides-Extra
The (optional) dependencies of the project.
For 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.
For 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
matching Provides-Extra
metadata.
dynamic#
TOML type: array of string
Corresponding core metadata field: Dynamic
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
dynamic).A build back-end MUST raise an error if the metadata specifies
nameindynamic.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[project]table).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
dynamic.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#
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
configuration in [tool.flit].
A mechanism is needed to allocate names within the tool.*
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
the subtable tool.$NAME if, and only if, they own the entry for
$NAME in the Cheeseshop/PyPI.