How to write a minimally working pyproject.toml file that can install packages?

Question

Pip supports the pyproject.toml file but so far all practical usage of the new schema requires a 3rd party tool that auto-generates these files (e.g., poetry and pip). Unlike setup.py which is already human-writeable, pyproject.toml is not (yet).

From setuptools docs,

[build-system]
requires = [
  "setuptools >= 40.9.0",
  "wheel",
]
build-backend = "setuptools.build_meta"

However, this file does not include package dependencies (as outlined in PEP 621). Pip does support installing packages using pyproject.toml but nowhere does pep specify how to write package dependencies in pyproject.toml for the official build system setuptools.

How do I write package dependencies in pyproject.toml?

---

Related StackOverflow Questions:

• How to init the pyproject.toml file

  This question asks for a method to auto-generate pyproject.toml, my question differ because I ask for a human-written pyproject.toml.

Answer 1

my question differ because I ask for a human-written pyproject.toml

First, the pyproject.toml file is always "human-writable".

Then, it is important to know that in this context setuptools and Poetry take the role of what are called "PEP 517 build back-ends", and there are many such back-ends available today, setuptools and Poetry are just two examples of them.

As of today, it seems like most (if not all) of the build back-ends I know of expect their configuration (including dependencies) to be written in pyproject.toml.

---

PEP 621

There is a standard called PEP 621 that specifies how a project's metadata, including dependencies, should be laid out in the pyproject.toml file.

Here is a list of build back-ends I know of that have support for PEP 621:

• enscons
• flit_core (see flit)
• hatchling (see hatch)
• pdm-pep517 (see pdm)
• setuptools (experimental support since version 61.0.0)
• trampolim
• whey

For all PEP 621 compatible build back-ends, the dependencies should be written in pyproject.toml file like in the following:

[project]
name = "Thing"
version = "1.2.3"
# ...
dependencies = [
    "SomeLibrary ~= 2.2",
]

References:

• https://peps.python.org/pep-0621/
• https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html (experimental support for PEP 621 has been added to setuptools version 61.0.0, released 2022-03-24)

---

setuptools (before version 61.0.0)

In setuptools before version 61.0.0 there is no support for writing the configuration in pyproject.toml (in other words: no PEP 621 support). You have to either write a setup.cfg, or a setup.py, or a combination of both.

My recommendation is to write as much as possible in setup.cfg. Such a setup.cfg could look like this:

[metadata]
name = Thing
version = 1.2.3

[options]
install_requires =
    SomeLibrary ~= 2.2
packages = find:

and in most cases the setup.py can be omitted completely or it can be as short as:

import setuptools
setuptools.setup()

References about the dependencies specifically:

• https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html
• https://www.python.org/dev/peps/pep-0508/
• https://www.python.org/dev/peps/pep-0440/

Again, note that in most cases it is possible to omit the setup.py file entirely, one of the conditions is that the setup.cfg file and a pyproject.toml file are present and contain all the necessary information. Here is an example of pyproject.toml that works well for a setuptools build backend:

[build-system]
build-backend = 'setuptools.build_meta'
requires = [
    'setuptools >= 43.0.0',
]

---

poetry

In poetry everything is defined in pyproject.toml, but it uses poetry-specific sections. In other words, Poetry does not currently use the PEP 621 standard, but there are some plans to move to this standard in the future.

This file can be hand-written. As far as I can tell, there is no strict need to ever explicitly install poetry itself (commands such as pip install and pip wheel can get you far enough).

The pyproject.toml file can be as simple as:

[tool.poetry]
name = 'Thing'
version = '1.2.3'

[tool.poetry.dependencies]
python = '^3.6'
SomeLibrary = '~2.2'

[build-system]
requires = ['poetry-core~=1.0']
build-backend = 'poetry.core.masonry.api'

References:

• https://python-poetry.org/docs/pyproject/
• https://python-poetry.org/docs/dependency-specification/