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 | bool | ||
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 |
file:, list-semi file:, list-semi file:, section str file:, section list-comma list-comma list-comma file:, list-semi bool find:, find_namespace:, list-comma dict section section list-comma list-comma |
36.7.0 34.4.0 51.0.0 34.4.0 |
|
data_files | section | 40.6.0 | 9 |
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.↩file:
directives for reading requirements are supported since version 63.0. The format for the file is basically the same as for arequirements.txt
file. Library developers should avoid tightly pinning their dependencies to a specific version (e.g. via a "locked" requirements file).↩file:
directives for reading requirements are supported since version 63.0. The format for the file is basically the same as for arequirements.txt
file. Library developers should avoid tightly pinning their dependencies to a specific version (e.g. via a "locked" requirements file).↩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"
file:
directives for reading requirements are supported since version 63.0. The format for the file is basically the same as for arequirements.txt
file. Library developers should avoid tightly pinning their dependencies to a specific version (e.g. via a "locked" requirements file).↩file:
directives for reading requirements are supported since version 63.0. The format for the file is basically the same as for arequirements.txt
file. Library developers should avoid tightly pinning their dependencies to a specific version (e.g. via a "locked" requirements file).↩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
.↩data_files
is deprecated and should be avoided. Please check/userguide/datafiles
for more information.↩