Build System Support

What is it?

Python packaging has come a long way.

The traditional setuptools way of packaging Python modules uses a setup() function within the script. Commands such as python bdist or python bdist_wheel generate a distribution bundle and python install installs the distribution. This interface makes it difficult to choose other packaging tools without an overhaul. Because scripts allowed for arbitrary execution, it proved difficult to provide a reliable user experience across environments and history.

PEP 517 therefore came to rescue and specified a new standard to package and distribute Python modules. Under PEP 517:

a pyproject.toml file is used to specify what program to use for generating distribution.

Then, two functions provided by the program, build_wheel(directory: str) and build_sdist(directory: str) create the distribution bundle at the specified directory. The program is free to use its own configuration script or extend the .toml file.

Lastly, pip install *.whl or pip install *.tar.gz does the actual installation. If *.whl is available, pip will go ahead and copy the files into site-packages directory. If not, pip will look at pyproject.toml and decide what program to use to ‘build from source’ (the default is setuptools)

With this standard, switching between packaging tools becomes a lot easier. build_meta implements setuptools’ build system support.

How to use it?

Starting with a package that you want to distribute. You will need your source scripts, a pyproject.toml file and a setup.cfg file:


The pyproject.toml file is required to specify the build system (i.e. what is being used to package your scripts and install from source). To use it with setuptools, the content would be:

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

The setuptools package implements the build_sdist command and the wheel package implements the build_wheel command; both are required to be compliant with PEP 517.

Use setuptoolsdeclarative config to specify the package information:

name = meowpkg
version = 0.0.1
description = a package that meows

packages = find:

Now generate the distribution. To build the package, use PyPA build:

$ pip install -q build
$ python -m build

And now it’s done! The .whl file and .tar.gz can then be distributed and installed:


$ pip install dist/meowpkg-0.0.1.whl


$ pip install dist/meowpkg-0.0.1.tar.gz