Deprecate legacy setup.py bdist_wheel mechanism for building projects · Issue #6334 · pypa/pip (original) (raw)

Last updated on April 27, 2025.

What's being deprecated?

DEPRECATION: Building 'version_pkg' using the legacy setup.py bdist_wheel mechanism, which will be removed in a future 
version. pip 25.3 will enforce this behaviour change. A possible replacement is to use the standardized build interface by 
setting the `--use-pep517` option, (possibly combined with `--no-build-isolation`), or adding a `pyproject.toml` file to the 
source tree of 'version_pkg'. Discussion can be found at https://github.com/pypa/pip/issues/6334

If you've received this deprecation warning, pip is using the setup.py bdist_wheel mechanism to build your project into a wheel for installation. This mechanism is legacy, deprecated, and slated for removal in pip 25.3 (Q4 2025).

FOR CONTEXT: The pyproject.toml specification covers how to build projects that include the file without specifying the optional [build-system] table. pip is now transitioning to this standard fallback mechanism when the pyproject.toml file is omitted entirely (replacing its previously deprecated non-standard ad hoc fallback logic for that case). Most projects which omit pyproject.toml will continue to build without problems after this change, but it's possible some projects will fail to build when using the standardised fallback mechanism (for example, due to undeclared build dependencies).

Specificially, pip currently calls the setup.py file directly in order to build projects without a pyproject.toml. The direct use of the setup.py command-line interface is deprecated, in favour of the PEP 517 mechanism which specifies a standard way for installers to ask the build backend (like setuptools) to build a project.

What should I do?

I am an USER of the affected project

You should report the deprecation warning to the project (if it has NOT already been reported!). Their packaging setup may need changes in order to be installable with future pip releases. You cannot fix this, only the project can.

Otherwise, you can silence the deprecation warning by force-enabling pip's PEP 517 mode, which will become the default and only installation method in the future. There are several ways to do this:

[install] use_pep517 = true

Generally, PEP 517 mode is mostly backwards compatible with the old setup.py bdist_wheel mechanism, however build isolation (see below) may cause build issues.

Warning

The project may fail to build or install when PEP 517 mode is enabled. If this happens, the recommended course of action is to do nothing and wait for the project to release a fixed version. Until support for the setup.py bdist_wheel is removed in pip 25.3, pip will continue to be able to install affected projects without any issue.

I am an AUTHOR of the affected project

You need to add a pyproject.toml file to your project. If you cannot add a pyproject.toml file, then follow the advice for USERS of affected projects above.

Without this file, pip does not know that your project supports the PEP 517 mechanism which is the replacement for the deprecated setup.py bdist_wheel mechanism.

In this file, you need to declare that your project is packaged using setuptools. You can add the following pyproject.toml to the root of your project, in the same folder that your setup.py or setup.cfg is contained in.

pyproject.toml

[build-system]

XXX: If your project needs other packages to build properly, add them to this list.

requires = ["setuptools >= 42.0.0"] build-backend = "setuptools.build_meta"

If the deprecation warning disappears, your project is being installed with the PEP 517 mechanism. Double check that the new installation functions correctly. If everything looks good, you're done. Congratulations!

Warning

By opting into pip's PEP 517 mode, you are also opting into build isolation. This means that pip will create a temporary Python environment to build the project in, whereas with the legacy behaviour the build occurs within the Python environment where pip is installed.

If your project needs specific dependencies (e.g., Cython) to be pre-installed for its build to function, it is recommended to declare them in build-system.requires in pyproject.toml.

If this is not possible, you can disable build isolation by passing the --no-build-isolation option. You are then responsible for ensuring the local environment has all dependencies needed for installation.

Tip

If you're struggling to reproduce the deprecation warning, double check that setuptools is installed. If setuptools is not installed, pip will always use the PEP 517 mechanism (and enable build isolation) as the setup.py bdist_wheel mechanism relies on setuptools being available.

Original issue text (for pip maintainers)

This is a longer-term goal, not something that can be done without a carefully managed transition, but pip should remove support for building and installing packages without using PEP 517.

Before this can be done, we need to be sure that PEP 517 support is complete, and there are no edge cases remaining of projects that cannot build with PEP 517, but need the legacy path. There is also an open question on how we provide editable install support, which is not covered by PEP 517.

I have raised this issue so that we have a central point to link to which makes it clear that this is the intended long term goal.