Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# `setup.py` (legacy)

Prior to the introduction of pyproject.toml-based builds (in PEP 517 and PEP 518), pip had only supported installing packages using `setup.py` files that were built using setuptools.

The interface documented here is retained currently solely for legacy purposes, until the migration to `pyproject.toml`-based builds can be completed.

Caution

The arguments and syntax of the various invocations of `setup.py` made by pip, are considered an implementation detail that is strongly coupled with setuptools. This build system interface is not meant to be used by any other build backend, which should be based on the pyproject.toml build system interface instead.

Further, projects should not expect to rely on there being any form of backward compatibility guarantees around the `setup.py` interface.

## Build process

The overall process for building a package is:

- Generate the package’s metadata.

- Generate a wheel for the package.

The wheel can then be used to perform an installation, if necessary.

### Metadata Generation

As a first step, `pip` needs to get metadata about a package (name, version, dependencies, and more). It collects this by calling `setup.py egg_info`.

The `egg_info` command generates the metadata for the package, which pip can then consume and proceed to gather all the dependencies of the package. Once the dependency resolution process is complete, pip will proceed to the next stage of the build process for these packages.

### Wheel Generation

When provided with a pypug:source distribution (or “sdist”) for a package, pip will attempt to build a pypug:wheel. Since wheel distributions can be cached, this can greatly speed up future installations for the package.

This is done by calling `setup.py bdist_wheel` which requires the wheel package to be installed.

If this wheel generation is successful (this can include compiling C/C++ code, depending on the package), the generated wheel is added to pip’s wheel cache and will be used for this installation. The built wheel is cached locally by pip to avoid repeated identical builds.

If this wheel generation fails, pip runs `setup.py clean` to clean up any build artifacts that may have been generated. After that, pip will attempt a direct installation.

### Editable Installation

For installing packages in “editable” mode (pip install --editable), pip will invoke `setup.py develop`, which will use setuptools’ mechanisms to perform an editable/development installation.

## Setuptools Injection

To support projects that directly use `distutils`, pip injects `setuptools` into `sys.modules` before invoking `setup.py`. This injection should be transparent to `distutils`-based projects.

## Customising the build

The `--global-option` and `--build-option` arguments to the `pip install` and `pip wheel` inject additional arguments into the `setup.py` command (`--build-option` is only available in `pip wheel`).

Attention

The use of `--global-option` and `--build-option` is highly setuptools specific, and is considered more an accident of the current implementation than a supported interface. It is documented here for completeness. These flags will not be supported, once this build system interface is dropped.

These arguments are included in the command as follows:

    python setup.py <global_options> BUILD COMMAND <build_options>

The options are passed unmodified, and presently offer direct access to the distutils command line. For example:

Linux

    $ python -m pip wheel --global-option bdist_ext --global-option -DFOO wheel

MacOS

    $ python -m pip wheel --global-option bdist_ext --global-option -DFOO wheel

Windows

    C:> py -m pip wheel --global-option bdist_ext --global-option -DFOO wheel

will result in pip invoking:

    setup.py bdist_ext -DFOO bdist_wheel -d TARGET

This passes a preprocessor symbol to the extension build.

## Build Output

Any output produced by the build system will be read by pip (for display to the user if requested). In order to correctly read the build system output, pip requires that the output is written in a well-defined encoding, specifically the encoding the user has configured for text output (which can be obtained in Python using `locale.getpreferredencoding`). If the configured encoding is ASCII, pip assumes UTF-8 (to account for the behaviour of some Unix systems).

Build systems should ensure that any tools they invoke (compilers, etc) produce output in the correct encoding. In practice - and in particular on Windows, where tools are inconsistent in their use of the “OEM” and “ANSI” codepages - this may not always be possible. pip will therefore attempt to recover cleanly if presented with incorrectly encoded build tool output, by translating unexpected byte sequences to Python-style hexadecimal escape sequences (`"\x80\xff"`, etc). However, it is still possible for output to be displayed using an incorrect encoding (mojibake).