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 follow semantic versioning. However it will not be enforced and you remain free to follow another specification.

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
  • GPL-2.0+
  • GPL-3.0
  • GPL-3.0+
  • LGPL-2.1
  • LGPL-2.1+
  • LGPL-3.0
  • LGPL-3.0+
  • 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. This is a list of authors and should contain at least one author.

Authors must be in the form name <email>.

readme

The readme file of the package. Required

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 (max: 5) that the package is related to. Optional

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 = "mypackage" },
    { include = "extra_package/**/*.py" },
]

If your package is stored inside a "source" directory, you must specify it:

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

Note

Using packages disables the package auto-detection feature meaning you have to explicitly specify the "default" package.

For instance, if you have a package named my_package and you want to also include another package named extra_package, you will need to specify my_package explicitely:

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

Note

Poetry is clever enough to detect Python subpackages.

So, if you only have to specify the directory where you root package resides.

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"]
exclude = ["my_package/excluded.py"]

dependencies and dev-dependencies

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'

Note

Be aware that declaring the python version for which your package is compatible is mandatory:

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

scripts

This section describe the scripts or executable 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.

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"]

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

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

plugins

Poetry supports arbitrary plugins wich 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"