Building and Distributing Packages with Setuptools#
Setuptools is a collection of enhancements to the Python
that allow developers to more easily build and
distribute Python packages, especially ones that have dependencies on other
Packages built and distributed using
setuptools look to the user like
ordinary Python packages based on the
Create Python Eggs - a single-file importable distribution format
Enhanced support for accessing data files hosted in zipped packages.
Automatically include all packages in your source tree, without listing them individually in setup.py
Automatically include all relevant files in your source distributions, without needing to create a
MANIFEST.infile, and without having to force regeneration of the
MANIFESTfile when your source tree changes 1.
Automatically generate wrapper scripts or Windows (console and GUI) .exe files for any number of “main” functions in your project. (Note: this is not a py2exe replacement; the .exe files rely on the local Python installation.)
Transparent Cython support, so that your setup.py can list
.pyxfiles and still work even when the end-user doesn’t have Cython installed (as long as you include the Cython-generated C in your source distribution)
Command aliases - create project-specific, per-user, or site-wide shortcut names for commonly used commands and options
Deploy your project in “development mode”, such that it’s available on
sys.path, yet can still be edited directly from its source checkout.
Easily extend the distutils with new commands or
setup()arguments, and distribute/reuse your extensions for multiple projects, without copying code.
Create extensible applications and frameworks that automatically discover extensions, using simple “entry points” declared in a project’s setup script.
Full support for PEP 420 via
find_namespace_packages(), which is also backwards compatible to the existing
find_packages()for Python >= 3.3.
The developer’s guide has been updated. See the most recent version.
Setuptools automatically calls
declare_namespace() for you at runtime,
but future versions may not. This is because the automatic declaration
feature has some negative side effects, such as needing to import all namespace
packages during the initialization of the
pkg_resources runtime, and also
the need for
pkg_resources to be explicitly imported before any namespace
packages work at all. In some future releases, you’ll be responsible
for including your own declaration lines, and the automatic declaration feature
will be dropped to get rid of the negative side effects.
During the remainder of the current development cycle, therefore, setuptools
will warn you about missing
declare_namespace() calls in your
__init__.py files, and you should correct these as soon as possible
before the compatibility support is removed.
Namespace packages without declaration lines will not work
correctly once a user has upgraded to a later version, so it’s important that
you make this change now in order to avoid having your code break in the field.
Our apologies for the inconvenience, and thank you for your patience.
New in version 40.9.0.
setup.py is missing from the project directory when a PEP 517
build is invoked,
setuptools emulates a dummy
setup.py file containing
PEP 517 doesn’t support editable installs so this is currently
pip install -e ..
This means that you can have a Python project with all build configuration
setup.cfg, without a
setup.py file, if you can rely
on your project always being built by a PEP 517/PEP 518 compatible
To use this feature:
Specify build requirements and PEP 517 build backend in
pyproject.toml. For example:
[build-system] requires = [ "setuptools >= 40.9.0", "wheel", ] build-backend = "setuptools.build_meta"
Use a PEP 517 compatible build frontend, such as
pip >= 19or
As PEP 517 is new, support is not universal, and frontends that do support it may still have bugs. For compatibility, you may want to put a
setup.pyfile containing only a
Some automation tools may wish to access data from a configuration file.
Setuptools exposes a
read_configuration() function for
options sections into a dictionary.
from setuptools.config import read_configuration conf_dict = read_configuration("/home/user/dev/package/setup.cfg")
read_configuration() will read only the file provided
in the first argument. To include values from other configuration files
which could be in various places, set the
find_others keyword argument
If you have only a configuration file but not the whole package, you can still
try to get data out of it with the help of the
argument. When it is set to
True, all options with errors possibly produced
by directives, such as
attr: and others, will be silently ignored.
As a consequence, the resulting dictionary will include no such options.
Forum and Bug Tracker#
Please use GitHub Discussions for questions and discussion about setuptools, and the setuptools bug tracker ONLY for issues you have confirmed via the forum are actual bugs, and which you have reduced to a minimal set of steps to reproduce.
The default behaviour for
setuptoolswill work well for pure Python packages, or packages with simple C extensions (that don’t require any special C header). See Controlling files in the distribution and Data Files Support for more information about complex scenarios, if you want to include other types of files.