Skip to content

pyproject.toml is a standardized file (PEP 518, PEP 621) used to configure Python packaging, building, and tools.

1
2
3
4
5
6
my_package/
├── pyproject.toml
├── README.md
└── my_package/
    ├── __init__.py
    └── main.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

[project]
name = "myproject"
version = "0.1.0"
description = ""
readme = "README.md"
requires-python = ">=3.8"

build-system

Defines how your project is built. This tells Python which tools to use when running pip install or python -m build. setuptools is the classic standard and widely use

other build tools

  • Poetry
  • Hatch
  • flit

python build

How to turn your source code into an installable package

1
pip install build
usage
1
2
3
python -m build

# create wheel in `dist` folder

Tip

use --no-isolation flag to disabled creating isolated virtual environment during build

project metadata (PEP 621)

The [project] section in pyproject.toml that describes your Python package:

  • name
  • version
  • dependencies
  • dependencies
  • entry points
  • requires-python
  • and more

version

Set manual 

1
version = "0.1.0"

or dynamic using tools like setuptools-scm. 

1
dynamic = ["version"]

dependencies

1
2
3
4
dependencies = [
    "requests>=2.28",
    "numpy",
]

more project settings

1
2
3
4
5
6
7
8
9
[project.optional-dependencies]
dev = ["pytest", "black", "flake8"]

[project.urls]
Homepage = "https://github.com/alice/coolapp"
Docs = "https://coolapp.readthedocs.io"

[project.scripts]
coolapp = "my_package:main"
  • [project.optional-dependencies]: install optional package pip install my_package[dev]
  • [project.scripts]: entry point/CLI command run coolapp to run application after install

Build Your First Python Package with pyproject.toml

From wheel to deb

Tool Uses .install Easy Policy-correct Best for
dpkg-deb ❌ ⭐⭐⭐⭐ ❌ quick hacks
dpkg-buildpackage ✅ ⭐⭐ ✅ real Debian
debuild ✅ ⭐⭐ ✅ same as above
stdeb ⚠️ ⭐⭐⭐ ⚠️ Python-only

From source to debain using debuild

From source to debain using dpkg-deb