Dependencies Management in Setuptools

There are three types of dependency styles offered by setuptools: 1) build system requirement, 2) required dependency and 3) optional dependency.

Each dependency, regardless of type, needs to be specified according to PEP 508 and PEP 440. This allows adding version range restrictions and environment markers.

Build system requirement

After organizing all the scripts and files and getting ready for packaging, there needs to be a way to specify what programs and libraries (build backend) are actually needed to build the package for distribution. For Setuptools, the requisite library is setuptools. Specify the build backend in a pyproject.toml file (see also Quickstart or Build System Support):

[build-system]
requires = ["setuptools"]
#...

Also include any other setuptools plugins (e.g., setuptools_scm, setuptools-golang, setuptools-rust) or build-time dependency (e.g., Cython, cppy, pybind11).

[build-system]
requires = ["setuptools", "cython", "setuptools_scm"]

If the project depends on a feature introduced in a specific version of Setuptools, it is good practice to specify it as a lower bound:

[build-system]
requires = ["setuptools >= 61.2"]

Some may be tempted to also include an upper-bound for yet unreleased major versions (e.g. setuptools <= 70) or pin to a specific version (e.g. setuptools == 70.0.4) in order to avoid the project being uninstallable should those backward-incompatible changes affect this release of the project. Setuptools maintainers recommend strongly against this precautionary approach. The team primarily maintains one release, the latest monotonically-increasing release, and encourages users to use that latest release (work at HEAD). As a result, the team is cognizant of and takes responsibility for making backward-incompatible changes and aims to mitigate the impact of any breaking changes prior to releasing that change. By pinning against an unreleased version, it causes toil (maintenance burden) for each and every project that does the pinning (and the consumers that use it) and increases the risk of erosion if maintenance is unsustained. This tradeoff between reproducibility and compatibility is especially stark because Setuptools frequently releases backward-incompatible releases for a variety of reasons, many of which won’t affect a given project.

Note

In previous versions of setuptools, the setup_requires keyword performed a similar function but is now considered deprecated in favor of the PEP 517 style described above. To peek into how this legacy keyword is used, consult our guide on deprecated practice (WIP).

Declaring required dependency

This is where a package declares its core dependencies, without which it won’t be able to run. setuptools supports automatically downloading and installing these dependencies when the package is installed. Although there is more finesse to it, let’s start with a simple example.

When your project is installed (e.g., using pip), all of the dependencies not already installed will be located (via PyPI), downloaded, built (if necessary), and installed and 2) Any scripts in your project will be installed with wrappers that verify the availability of the specified dependencies at runtime.

Platform specific dependencies

Setuptools offers the capability to evaluate certain conditions before blindly installing everything listed in install_requires. This is great for platform specific dependencies. For example, the enum package was added in Python 3.4, therefore, package that depends on it can elect to install it only when the Python version is older than 3.4. To accomplish this

Similarly, if you also wish to declare pywin32 with a minimal version of 1.0 and only install it if the user is using a Windows operating system:

The environmental markers that may be used for testing platform types are detailed in PEP 508.

See also

Alternatively, a backend wrapper can be used for specific use cases where environment markers aren’t sufficient.

Direct URL dependencies

Attention

PyPI and other standards-conformant package indices do not accept packages that declare dependencies using direct URLs. pip will accept them when installing packages from the local filesystem or from another URL, however.

Dependencies that are not available on a package index but can be downloaded elsewhere in the form of a source repository or archive may be specified using a variant of PEP 440’s direct references:

For source repository URLs, a list of supported protocols and VCS-specific features such as selecting certain branches or tags can be found in pip’s documentation on VCS support. Supported formats for archive URLs are sdists and wheels.

Optional dependencies

Setuptools allows you to declare dependencies that are not installed by default. This effectively means that you can create a “variant” of your package with a set of extra functionalities.

For example, let’s consider a Package-A that offers optional PDF support and requires two other dependencies for it to work:

The name PDF is an arbitrary identifier of such a list of dependencies, to which other components can refer and have them installed.

A use case for this approach is that other package can use this “extra” for their own dependencies. For example, if Package-B needs Package-A with PDF support installed, it might declare the dependency like this:

This will cause ReportLab to be installed along with Package-A, if Package-B is installed – even if Package-A was already installed. In this way, a project can encapsulate groups of optional “downstream dependencies” under a feature name, so that packages that depend on it don’t have to know what the downstream dependencies are. If a later version of Package-A builds in PDF support and no longer needs ReportLab, or if it ends up needing other dependencies besides ReportLab in order to provide PDF support, Package-B’s setup information does not need to change, but the right packages will still be installed if needed.

Tip

Best practice: if a project ends up no longer needing any other packages to support a feature, it should keep an empty requirements list for that feature in its extras_require argument, so that packages depending on that feature don’t break (due to an invalid feature name).

Warning

Historically setuptools also used to support extra dependencies in console scripts, for example:

This syntax indicates that the entry point (in this case a console script) is only valid when the PDF extra is installed. It is up to the installer to determine how to handle the situation where PDF was not indicated (e.g., omit the console script, provide a warning when attempting to load the entry point, assume the extras are present and let the implementation fail later).

However, pip and other tools might not support this use case for extra dependencies, therefore this practice is considered deprecated. See PyPUG:specifications/entry-points.

Python requirement

In some cases, you might need to specify the minimum required python version. This can be configured as shown in the example below.