What is the build-system table for?

The build-system table follows PEP 517 and tells pip which backend to use to turn your source into a wheel. requires lists the build tools (such as hatchling) and build-backend names the import path pip calls, so a clean environment can build your package without you installing anything globally.

What goes in optional-dependencies?

optional-dependencies defines named extras, like a dev group with pytest, ruff and mypy. Users install them with pip install package[dev]. It keeps test and lint tools out of the default install while still declaring them in one place.

How do console-script entry points work?

An entry under project.scripts maps a command name to a module:function target, for example mypkg = mypkg.__main__:main. When the package is installed, pip creates an executable that imports that module and calls the function, so users can run your tool by name.

Which build backend should I pick?

Hatchling is a fast modern default with good defaults. setuptools is the most widely supported and needed for C extensions. Flit is minimal for pure-Python packages, and Poetry core suits projects already using Poetry. All four produce standard wheels pip can install.

How is the package name normalised?

PyPI distribution names are case-insensitive and treat runs of dots, hyphens and underscores as equivalent. The tool lowercases the name and replaces invalid characters with hyphens, then derives the import module name by converting hyphens to underscores.

pyproject.toml Builder

The pyproject.toml Builder generates a modern, PEP 621 compliant project file — the single configuration file that replaces setup.py, setup.cfg and requirements.txt for packaging. Enter your metadata and dependencies and the tool emits a complete [build-system] and [project] block plus extras, a script entry point and basic tool config.

How it works

Two tables do the core work. [build-system] (PEP 517) names the backend pip uses to build a wheel — Hatchling, setuptools, Flit or Poetry core — so a fresh environment can build your package with nothing installed globally. [project] (PEP 621) holds the metadata PyPI displays: name, version, description, requires-python, license, authors and the dependencies list.

The tool also adds [project.optional-dependencies] with a dev extra (pytest, ruff, mypy), an optional [project.scripts] console entry point, project URLs, and starter [tool.ruff] / [tool.mypy] sections. The package name is normalised to a valid PyPI distribution name, and the import module name is derived by replacing hyphens with underscores.

Example workflow

Once you have a pyproject.toml and a source package, build and install like this:

python -m build              # produces dist/*.whl and *.tar.gz
pip install -e ".[dev]"      # editable install with the dev extra

Tips and notes

A console script such as mypkg = mypkg.__main__:main requires a __main__.py that defines a main() function — the generated entry point assumes that layout. Keep runtime dependencies lean in dependencies and push test or build tooling into extras, so end users do not pull in your whole toolchain. For reproducible builds, pair this with a lock file from uv, pip-tools or Poetry.

pyproject.toml Builder

Email me this result

How it works

Example workflow

Tips and notes