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", it was designed to be written by humans first.

Then, it is important to know that in this context setuptools and Poetry take the role of what are called "build back-ends", and there are many such build back-ends available today, setuptools and Poetry (technically poetry-core) 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.

---

[project]

There is a standard specifying how a project's packaging metadata, including dependencies, should be laid out in the pyproject.toml file under a [project] table: "Declaring project metadata: the [project] table".

Here is a list of build back-ends I know of that follow this [project] standard:

• enscons
• flit_core (see flit)
• hatchling (see hatch)
• maturin
• meson-python
• pdm-backend (see pdm)
• scikit-build-core
• setuptools (experimental support since version 61.0.0)
• trampolim
• whey

I have a comparison table here.

For all [project]-compatible build back-ends, the dependencies should be written in the pyproject.toml file at the root of the project's source code directory like in the following example:

[project]
name = "Thing"
version = "1.2.3"
# ...
dependencies = [
    "SomeLibrary >= 2.2",
    "AnotherLibrary >= 4.5.6",
]

References:

• PyPA specification "Declaring project metadata"
• PEP 621 – Storing project metadata in pyproject.toml
• setuptools documentation: "Configuring setuptools using pyproject.toml files"

---

setuptools (before version 61.0.0)

In setuptools before version 61.0.0 there is no support for writing the project's packaging metadata in pyproject.toml. 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
    AnotherLibrary >= 4.5.6
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:

• Dependencies Management in Setuptools
• PEP 508 – Dependency specification for Python Software Packages
• PEP 440 – Version Identification and Dependency Specification

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 back-end:

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

---

Poetry

In Poetry everything is defined in pyproject.toml, but it uses Poetry-specific sections [tool.poetry] instead of the standardized [project] section. There are some plans to add support for this standard in Poetry 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'
AnotherLibrary >= '4.5.6'

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

References:

• Poetry documentation: "The pyproject.toml file"
• Poetry documentation: "Dependency specification"