Note
New in 30.3.0 (8 Dec 2016).
Important
If compatibility with legacy builds (i.e. those not using the 517
build API) is desired, a setup.py
file containing a setup()
function call is still required even if your configuration resides in setup.cfg
.
Setuptools
allows using configuration files (usually setup.cfg
) to define a package’s metadata and other options that are normally supplied to the setup()
function (declarative config).
This approach not only allows automation scenarios but also reduces boilerplate code in some cases.
[metadata]
name = my_package
version = attr: my_package.VERSION
description = My package description
long_description = file: README.rst, CHANGELOG.rst, LICENSE.rst
keywords = one, two
license = BSD 3-Clause License
classifiers =
Framework :: Django
Programming Language :: Python :: 3
[options]
zip_safe = False
include_package_data = True
packages = find:
install_requires =
requests
importlib-metadata; python_version<"3.8"
[options.package_data]
* = *.txt, *.rst
hello = *.msg
[options.entry_points]
console_scripts =
executable-name = my_package.module:function
[options.extras_require]
pdf = ReportLab>=1.2; RXP
rest = docutils>=0.3; pack ==1.1, ==1.3
[options.packages.find]
exclude =
examples*
tools*
docs*
my_package.tests*
Metadata and options are set in the config sections of the same name.
- Keys are the same as the keyword arguments one provides to the
setup()
function. Complex values can be written comma-separated or placed one per line in dangling config values. The following are equivalent:
[metadata] keywords = one, two [metadata] keywords = one two
- In some cases, complex values can be provided in dedicated subsections for clarity.
- Some keys allow
file:
,attr:
,find:
, andfind_namespace:
directives in order to cover common usecases. - Unknown keys are ignored.
One commonly used package configuration has all the module source code in a subdirectory (often called the src/
layout), like this:
├── src
│ └── mypackage
│ ├── __init__.py
│ └── mod1.py
├── setup.py
└── setup.cfg
You can set up your setup.cfg
to automatically find all your packages in the subdirectory like this:
# This example contains just the necessary options for a src-layout, set up
# the rest of the file as described above.
[options]
package_dir=
=src
packages=find:
[options.packages.find]
where=src
Some values are treated as simple strings, some allow more logic.
Type names used below:
str
- simple stringlist-comma
- dangling list or string of comma-separated valueslist-semi
- dangling list or string of semicolon-separated valuesbool
-True
is 1, yes, truedict
- list-comma where keys are separated from values by=
section
- values are read from a dedicated (sub)section
Special directives:
attr:
- Value is read from a module attribute.attr:
supports callables and iterables; unsupported types are cast usingstr()
.In order to support the common case of a literal value assigned to a variable in a module containing (directly or indirectly) third-party imports,
attr:
first tries to read the value from the module by examining the module's AST. If that fails,attr:
falls back to importing the module.file:
- Value is read from a list of files and then concatenatedNote
The
file:
directive is sandboxed and won't reach anything outside the directory containingsetup.py
.
Note
The aliases given below are supported for compatibility reasons, but their use is not advised.
Key | Aliases | Type | Minimum Version | Notes |
---|---|---|---|---|
name version url download_url project_urls author author_email maintainer maintainer_email classifiers license license_files description long_description long_description_content_type keywords platforms provides requires obsoletes |
home-page download-url author-email maintainer-email classifier license_file summary long-description platform |
str attr:, file:, str str str dict str str str str file:, list-comma str list-comma file:, str file:, str str list-comma list-comma list-comma list-comma list-comma |
39.2.0 38.3.0 42.0.0 38.6.0 |
Notes:
Key | Type | Minimum Version | Notes |
---|---|---|---|
zip_safe setup_requires install_requires extras_require python_requires entry_points scripts eager_resources dependency_links tests_require include_package_data packages package_dir package_data exclude_package_data namespace_packages py_modules |
bool list-semi list-semi section str file:, section list-comma list-comma list-comma list-semi bool find:, find_namespace:, list-comma dict section section list-comma list-comma |
36.7.0 34.4.0 51.0.0
|
|
data_files | section | 40.6.0 | 6 |
Notes:
Historically, several tools explored declarative package configuration in parallel. And several of them chose to place the packaging configuration within the project's setup.cfg
file. One of the first was distutils2
, which development has stopped in 2013. Other include pbr
which is still under active development or d2to1
, which was a plug-in that backports declarative configuration to distutils
, but has had no release since Oct. 2015. As a way to harmonize packaging tools, setuptools
, having held the position of de facto standard, has gradually integrated those features as part of its core features.
Still this has lead to some confusion and feature incompatibilities:
- some tools support features others don't;
- some have similar features but the declarative syntax differs;
The table below tries to summarize the differences. But, please, refer to each tool documentation for up-to-date information.
feature | setuptools | distutils2 | d2to1 | pbr |
---|---|---|---|---|
[metadata] description-file | S | Y | Y | Y |
[files] | S | Y | Y | Y |
entry_points | Y | Y | Y | S |
[backwards_compat] | N | Y | Y | Y |
Y: supported, N: unsupported, S: syntax differs (see above example<example-setup-config>
).
Also note that some features were only recently added to setuptools
. Please refer to the previous sections to find out when.
The
version
file attribute has only been supported since 39.2.0.A version loaded using the
file:
directive must comply with PEP 440. It is easy to accidentally put something other than a valid version string in such a file, so validation is stricter in this case.↩In the
extras_require
section, values are parsed aslist-semi
. This implies that in order to include markers, they must be dangling:↩[options.extras_require] rest = docutils>=0.3; pack ==1.1, ==1.3 pdf = ReportLab>=1.2 RXP importlib-metadata; python_version < "3.8"
The
find:
andfind_namespace:
directive can be further configured in a dedicated subsectionoptions.packages.find
. This subsection accepts the same keys as thesetuptools.find_packages
and thesetuptools.find_namespace_packages
function:where
,include
, andexclude
.The
find_namespace:
directive is supported since Python >=3.3.↩In the
package_data
section, a key named with a single asterisk (*
) refers to all packages, in lieu of the empty string used insetup.py
.↩namespace_packages
is deprecated in favour of native/implicit namespaces (420
). Checkthe Python Packaging User Guide <PyPUG:guides/packaging-namespace-packages>
for more information.↩data_files
is deprecated and should be avoided. Please check/userguide/datafiles
for more information.↩