Building and Distributing Packages with Setuptools ¶

Setuptools is a collection of enhancements to the Pythondistutilsthat allow developers to more easily build anddistribute Python packages, especially ones that have dependencies on otherpackages.

Packages built and distributed usingsetuptools look to the user likeordinary Python packages based on thedistutils.

Feature Highlights:

CreatePython 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 themindividually in setup.py
Automatically include all relevant files in your source distributions,without needing to create aMANIFEST.in file,and without having to force regeneration of theMANIFEST file when yoursource tree changes[1].
Automatically generate wrapper scripts or Windows (console and GUI) .exefiles for any number of “main” functions in your project. (Note: this is nota py2exe replacement; the .exe files rely on the local Python installation.)
Transparent Cython support, so that your setup.py can list.pyx files andstill work even when the end-user doesn’t have Cython installed (as long asyou include the Cython-generated C in your source distribution)
Command aliases - create project-specific, per-user, or site-wide shortcutnames for commonly used commands and options
Deploy your project in “development mode”, such that it’s available onsys.path, yet can still be edited directly from its source checkout.
Easily extend the distutils with new commands orsetup() arguments, anddistribute/reuse your extensions for multiple projects, without copying code.
Create extensible applications and frameworks that automatically discoverextensions, using simple “entry points” declared in a project’s setup script.
Full support for PEP 420 viafind_namespace_packages(), which is also backwardscompatible to the existingfind_packages() for Python >= 3.3.

Developer’s Guide¶

The developer’s guide has been updated. See themost recent version.

TRANSITIONAL NOTE¶

Setuptools automatically callsdeclare_namespace() for you at runtime,but future versions maynot. This is because the automatic declarationfeature has some negative side effects, such as needing to import all namespacepackages during the initialization of thepkg_resources runtime, and alsothe need forpkg_resources to be explicitly imported before any namespacepackages work at all. In some future releases, you’ll be responsiblefor including your own declaration lines, and the automatic declaration featurewill be dropped to get rid of the negative side effects.

During the remainder of the current development cycle, therefore, setuptoolswill warn you about missingdeclare_namespace() calls in your__init__.py files, and you should correct these as soon as possiblebefore the compatibility support is removed.Namespace packages without declaration lines will not workcorrectly once a user has upgraded to a later version, so it’s important thatyou 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.

setup.cfg-only projects¶

Added in version 40.9.0.

Ifsetup.py is missing from the project directory when aPEP 517build is invoked,setuptools emulates a dummysetup.py file containingonly asetuptools.setup() call.

Note

PEP 517 doesn’t support editable installs so this is currentlyincompatible withpipinstall-e..

This means that you can have a Python project with all build configurationspecified insetup.cfg, without asetup.py file, if youcan relyon your project always being built by aPEP 517/PEP 518 compatiblefrontend.

To use this feature:

Specify build requirements andPEP 517 build backend inpyproject.toml.For example:

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

Use aPEP 517 compatible build frontend, such aspip>=19 orbuild.
Warning
AsPEP 517 is new, support is not universal, and frontends thatdo support it may still have bugs. For compatibility, you may want toput asetup.py file containing only asetuptools.setup()invocation.

Configuration API¶

Some automation tools may wish to access data from a configuration file.

Setuptools exposes aread_configuration() function forparsingmetadata andoptions sections into a dictionary.

fromsetuptools.configimportread_configurationconf_dict=read_configuration("/home/user/dev/package/setup.cfg")

By default,read_configuration() will read only the file providedin the first argument. To include values from other configuration fileswhich could be in various places, set thefind_others keyword argumenttoTrue.

If you have only a configuration file but not the whole package, you can stilltry to get data out of it with the help of theignore_option_errors keywordargument. When it is set toTrue, all options with errors possibly producedby directives, such asattr: and others, will be silently ignored.As a consequence, the resulting dictionary will include no such options.

Forum and Bug Tracker¶

Please useGitHub Discussions for questions and discussion aboutsetuptools, and thesetuptools bug tracker ONLY for issues you haveconfirmed via the forum are actual bugs, and which you have reduced to a minimalset of steps to reproduce.

[1]

The default behaviour forsetuptools will work well for purePython packages, or packages with simple C extensions (that don’t requireany special C header). SeeControlling files in the distribution andData Files Support for more information about complex scenarios, ifyou want to include other types of files.

On this page

Building and Distributing Packages with Setuptools
- Developer’s Guide
  - TRANSITIONAL NOTE