Building and Distributing Packages with Setuptools#

Setuptools is a collection of enhancements to the Python distutils that allow developers to more easily build and distribute Python packages, especially ones that have dependencies on other packages.

Packages built and distributed using setuptools look to the user like ordinary Python packages based on the distutils.

Feature Highlights:

  • 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.in file, and without having to force regeneration of the MANIFEST file 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 .pyx files 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.

Developer’s Guide#

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

TRANSITIONAL NOTE#

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.

setup.cfg-only projects#

New in version 40.9.0.

If setup.py is missing from the project directory when a PEP 517 build is invoked, setuptools emulates a dummy setup.py file containing only a setuptools.setup() call.

Note

PEP 517 doesn’t support editable installs so this is currently incompatible with pip install -e ..

This means that you can have a Python project with all build configuration specified in setup.cfg, without a setup.py file, if you can rely on your project always being built by a PEP 517/PEP 518 compatible frontend.

To use this feature:

  • Specify build requirements and PEP 517 build backend in pyproject.toml. For example:

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

  • Use a PEP 517 compatible build frontend, such as pip >= 19 or build.

    Warning

    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.py file containing only a setuptools.setup() invocation.

Configuration API#

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

Setuptools exposes a read_configuration() function for parsing metadata and options sections into a dictionary.

from setuptools.config import read_configuration

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

By default, 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 to True.

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 ignore_option_errors keyword 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.