What's the difference between setup.py and setup.cfg in python projects

Question

Need to know what's the difference between setup.py and setup.cfg. Both are used prominently in openstack projects

Answer 1

Traditionally, setup.py has been used to build a Python package, i.e.,

python setup.py build

Like any old Python file, setup.py can contain lots of code. In most cases, however, it is purely declarative and simply lists package properties, e.g.,

from setuptools import setup

setup(
    name="foobar",
    version="0.1.0",
    author="John Doe",
    # ...
)

In fact, some consider it bad style to put much logic in setup.py. To reflect that, setup.cfg (which is declarative by design) has become more popular for packaging:

[metadata]
name = foobar
version = 0.1.0
author = John Doe
# ...

This has the advantage that the packaging software (e.g., setuptools) doesn't need to evaluate a Python file to get the meta data, but can simply parse a config file.

You can add a dummy setup.py to that,

from setuptools import setup

if __name__ == "__main__":
    setup()

or go full PEP 517/518 and instead add a pyproject.toml.

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

You can then build your projects using pypa-build (pip install build) with

python3 -m build --sdist --wheel .

Since 2020 pyproject.toml can contain metadata too, so you don't need setup.cfg anymore. The data layout looks more or less like setup.cfg but follows the standardized TOML format:

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

[project]
name = "foobar"
version = "0.1.0"
authors = [{name = "John Doe", email = "john@doe.com"}]
# [...]

One design goal is that multiple build systems will support it (setuptools, flit, Poetry, ...). As of 2022, setuptools will still give you an "experimental" warning when installing that package, but that might go away soon.

Answer 2

setup.py is the file with the actual instructions how to build your software. These instructions might have some configuration options, e.g. for unit tests you might be able to indicate whether test coverage should be computed or not, or the install prefix etc.

setup.cfg is a file which might be used to specify such options in addition to reading the command line when calling python setup.py <somecommand>.

The documentation for setup.cfg states:

Often, it’s not possible to write down everything needed to build a distribution a priori: you may need to get some information from the user, or from the user’s system, in order to proceed. As long as that information is fairly simple—a list of directories to search for C header files or libraries, for example—then providing a configuration file, setup.cfg, for users to edit is a cheap and easy way to solicit it. Configuration files also let you provide default values for any command option, which the installer can then override either on the command-line or by editing the config file.

Answer 3

setup.py is an integral part of a python package which includes details or information about the files that should be a package. This includes the required dependencies for installation and functioning of your Python package, entry points, license, etc.

setup.cfg on the other hand is more about the settings for any plug-ins or the type of distribution you wish to create. bdist/sdist and further classification of universal or core-python wheel. It can also be used to configure some meta-data of the setup.py.