Deprecate legacy setup.py bdist_wheel mechanism for building projects

[pfmoore]

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:

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

[ichard26]

So for those who don't follow the PyPA Discord aggressively, I'm working on a mini-project to build a bunch of PyPI projects w/o a pyproject.toml and test whether --use-pep517 will succeed or break their build. So far, I'm focusing on the top 1500 PyPI packages, then selecting for those that...

• Do not contain a pyproject.toml
• Are pure Python (the detection logic is rather crude and probably has a bunch of false negatives)
• Have had a release in the last year
  • if you haven't had a release in the last year, the project is probably not accepting updates so the default pyproject.toml fallback is good enough for 'em

On Python 3.13, the results are:

Projects where --use-pep517 succeeds: 207
Projects where --use-pep517 fails: 7
Projects that don't build at all: 15

I'm planning to file PRs for the projects where enabling --use-pep517 is a breaking change so they can avoid future breakage, but what about the projects that successfully build today and will continue to build even when --use-pep517 is always on?

I wouldn't mind filing PRs for the ~200 projects over the six month span before pip 25.3, but I wouldn't want to waste time doing something isn't beneficial. I've always assumed that Python projects in 2025 really should have a pyproject.toml with a valid build-system declaration, but perhaps this isn't as true as I think it is.

I'm working on testing the top 10000 projects (with the same restrictions). I'll follow up with the results of that experiment. Of course, the real trouble lies with the non-pure Python projects, but that's a mess I haven't figured out how to study yet.