Python third-party tools configuration: pyproject.toml vs setup.cfg

A couple of years ago two PEPs have been proposed to fix some package building interface problems. Basically, in order to build a Python package we need to checkout source of the project, then install a build system and finally run it. PEP 517 defines the last step, including how to get the build system dynamically specify more dependencies that the build system requires to perform its job. The PEP 518 defines the second step, including a new configuration file pyproject.toml to be used by the building system.

As setuptools have been dominating in Python packaging field for a long time, many third-party tools adopted its configuration file setup.cfg too. Libraries for testing, static code analysis tools like linters or type checkers along with their custom configuration files often allow to use setup.cfg. After all, it’s INI-style configuration format, easy for humans to read and edit it, with no standard behind it though.

Moving tool settings to the setup.cfg as opposed to supporing a bunch of custom config files seems to be common practice. But now that we have the new PEPs, should we abandon setup.cfg in favour of the brand new pyproject.toml? Let’s see.


TOML is a great human-readable, machine-editable, strong typed, well-defined configuration format. Having Python- and setuptools-independent configuration file pyproject.toml is a great idea. Still, as the usage of pyproject.toml for non-package building context is not defined, we are in the xkcd how-standards-proliferate situation. Until consensus is finally set, it’s better off either use setup.cfg with an annoying exception for black, or stick to the tools custom config formats and files.