The pyproject.toml file

The pyproject.toml file #

The tool.poetry section of the pyproject.toml file is composed of multiple sections.

name #

The name of the package. Required

version #

The version of the package. Required

This should be a valid PEP 440 string.

description #

A short description of the package. Required

license #

The license of the package.

The recommended notation for the most common licenses is (alphabetical):

• Apache-2.0
• BSD-2-Clause
• BSD-3-Clause
• BSD-4-Clause
• GPL-2.0-only
• GPL-2.0-or-later
• GPL-3.0-only
• GPL-3.0-or-later
• LGPL-2.1-only
• LGPL-2.1-or-later
• LGPL-3.0-only
• LGPL-3.0-or-later
• MIT

Optional, but it is highly recommended to supply this. More identifiers are listed at the SPDX Open Source License Registry.

authors #

The authors of the package. Required

This is a list of authors and should contain at least one author. Authors must be in the form name <email>.

maintainers #

The maintainers of the package. Optional

This is a list of maintainers and should be distinct from authors. Maintainers may contain an email and be in the form name <email>.

readme #

The readme file of the package. Optional

The file can be either README.rst or README.md.

homepage #

An URL to the website of the project. Optional

repository #

An URL to the repository of the project. Optional

documentation #

An URL to the documentation of the project. Optional

keywords #

A list of keywords that the package is related to. Optional

classifiers #

A list of PyPI trove classifiers that describe the project. Optional

[tool.poetry]
# ...
classifiers = [
    "Topic :: Software Development :: Build Tools",
    "Topic :: Software Development :: Libraries :: Python Modules"
]

packages #

A list of packages and modules to include in the final distribution.

If your project structure differs from the standard one supported by poetry, you can specify the packages you want to include in the final distribution.

[tool.poetry]
# ...
packages = [
    { include = "my_package" },
    { include = "extra_package/**/*.py" },
]

If your package is stored inside a “lib” directory, you must specify it:

[tool.poetry]
# ...
packages = [
    { include = "my_package", from = "lib" },
]

If you want to restrict a package to a specific build format you can specify it by using format:

[tool.poetry]
# ...
packages = [
    { include = "my_package" },
    { include = "my_other_package", format = "sdist" },
]

From now on, only the sdist build archive will include the my_other_package package.

packages = [
    { include = "my_package" },
    { include = "extra_package" },
]

include and exclude #

A list of patterns that will be included in the final package.

You can explicitly specify to Poetry that a set of globs should be ignored or included for the purposes of packaging. The globs specified in the exclude field identify a set of files that are not included when a package is built.

If a VCS is being used for a package, the exclude field will be seeded with the VCS’ ignore settings (.gitignore for git for example).

[tool.poetry]
# ...
include = ["CHANGELOG.md"]

You can also specify the formats for which these patterns have to be included, as shown here:

[tool.poetry]
# ...
include = [
    { path = "tests", format = "sdist" },
    { path = "for_wheel.txt", format = ["sdist", "wheel"] }
]

If no format is specified, it will default to include both sdist and wheel.

exclude = ["my_package/excluded.py"]

dependencies and dependency groups #

Poetry is configured to look for dependencies on PyPi by default. Only the name and a version string are required in this case.

[tool.poetry.dependencies]
requests = "^2.13.0"

If you want to use a private repository, you can add it to your pyproject.toml file, like so:

[[tool.poetry.source]]
name = "private"
url = "http://example.com/simple"

If you have multiple repositories configured, you can explicitly tell poetry where to look for a specific package:

[tool.poetry.dependencies]
requests = { version = "^2.13.0", source = "private" }

[tool.poetry.dependencies]
python = "^3.7"

You can organize your dependencies in groups to manage them in a more granular way.

[tool.poetry.group.test.dependencies]
pytest = "*"

[tool.poetry.group.docs.dependencies]
mkdocs = "*"

See Dependency groups for a more in-depth look at how to manage dependency groups.

scripts #

This section describes the scripts or executables that will be installed when installing the package

[tool.poetry.scripts]
poetry = 'poetry.console:run'

Here, we will have the poetry script installed which will execute console.run in the poetry package.

To specify a script that depends on an extra, you may provide an entry as an inline table:

[tool.poetry.scripts]
devtest = { callable = "mypackage:test.run_tests", extras = ["test"] }

extras #

Poetry supports extras to allow expression of:

• optional dependencies, which enhance a package, but are not required; and
• clusters of optional dependencies.

[tool.poetry]
name = "awesome"

[tool.poetry.dependencies]
# These packages are mandatory and form the core of this package’s distribution.
mandatory = "^1.0"

# A list of all of the optional dependencies, some of which are included in the
# below `extras`. They can be opted into by apps.
psycopg2 = { version = "^2.7", optional = true }
mysqlclient = { version = "^1.3", optional = true }

[tool.poetry.extras]
mysql = ["mysqlclient"]
pgsql = ["psycopg2"]
databases = ["mysqlclient", "psycopg2"]

When installing packages with Poetry, you can specify extras by using the -E|--extras option:

poetry install --extras "mysql pgsql"
poetry install -E mysql -E pgsql

When installing or specifying Poetry-built packages, the extras defined in this section can be activated as described in PEP 508.

For example, when installing the package using pip, the dependencies required by the databases extra can be installed as shown below.

pip install awesome[databases]

plugins #

Poetry supports arbitrary plugins which work similarly to setuptools entry points. To match the example in the setuptools documentation, you would use the following:

[tool.poetry.plugins] # Optional super table

[tool.poetry.plugins."blogtool.parsers"]
".rst" = "some_module:SomeClass"

urls #

In addition to the basic urls (homepage, repository and documentation), you can specify any custom url in the urls section.

[tool.poetry.urls]
"Bug Tracker" = "https://github.com/python-poetry/poetry/issues"

If you publish your package on PyPI, they will appear in the Project Links section.

Poetry and PEP-517 #

PEP-517 introduces a standard way to define alternative build systems to build a Python project.

Poetry is compliant with PEP-517, by providing a lightweight core library, so if you use Poetry to manage your Python project you should reference it in the build-system section of the pyproject.toml file like so:

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"