Deprecate legacy setup.py bdist_wheel mechanism for building projects

[pfmoore]

Last updated on April 26, 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).

This deprecation only affects projects that are packaged with setuptools and not have been updated to use the modern PEP 517 mechanism, which is enabled by the presence of pyproject.toml.

Once the legacy setup.py bdist_wheel mechanism is removed, all packages will be built using the PEP 517 mechanism. While this should "just work" for many packages, there are behavioural differences between the mechanisms, so pip is issuing a deprecation warning to ensure there is time to migrate.

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:

• Use the --use-pep517 flag
• Set a PIP_USE_PEP517=true environment variable
• Force PEP 517 mode in a pip configuration file like so:

[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.

Important

The setup.py file is NOT deprecated. It is perfectly fine to keep your setup.py (or setup.cfg) file to configure setuptools for your project. However, if you wish, you can migrate your project's packaging configuration to the pyproject.toml file.

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.