Deprecate and remove the setup.py bdist_wheel code path. Aka always use PEP 517.

[sbidoul]

What's the problem this feature will solve?

When faced with a project with setup.py but no pyproject.toml pip has logic to fall back to running setup.py bdist_wheel if setuptools and wheel are installed. We look for wheel because it is where setuptools' bdist_wheel command was implemented, until recently.

In version 70.1, setuptools adopted wheel's bdist_wheel implementation.
In version 0.46 (currently yanked), wheel is removing bdist_wheel.

This means that our logic falls apart for some combinations of setuptools and wheel.

For instance, in a venv, this fails:

# pip install "setuptools<70" "wheel==0.46.0"
# cat > setup.py <<EOF
from setuptools import setup
setup(name="pkga")
EOF
# pip install .
Processing /tmp/brol
  Preparing metadata (setup.py) ... done
Building wheels for collected packages: pkga
  Building wheel for pkga (setup.py) ... error
  error: subprocess-exited-with-error
  
  × python setup.py bdist_wheel did not run successfully.
  │ exit code: 1
  ╰─> [6 lines of output]
      usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
         or: setup.py --help [cmd1 cmd2 ...]
         or: setup.py --help-commands
         or: setup.py cmd --help
      
      error: invalid command 'bdist_wheel'
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for pkga
  Running setup.py clean for pkga
Failed to build pkga
ERROR: Failed to build installable wheels for some pyproject.toml based projects (pkga)

Enabling PEP 517 solves the problem.

Describe the solution you'd like

We could try to work around this, but I think the time has come to drop the legacy setuptools interface.

I propose to deprecate the setup.py bdist_wheel code path in 25.1 and remove it in 25.2.

Alternative Solutions

Something complicated involving looking at setuptools and wheel versions.

Additional context

I thought there was already an open issue for always using PEP 517 but I can't find it right now.

Code of Conduct

• I agree to follow the PSF Code of Conduct.

[notatallshaw]

uv has only supported PEP 517, and while they do get occasional feedback that projects work with pip but not uv for this scenario, it hasn't been a massive amount of feedback.

I propose to deprecate the setup.py bdist_wheel code path in 25.1 and remove it in 25.2.

Isn't pip's deprecation policy two releases? Why not 25.1 -> 25.3?

I also think it's worth reviewing issues marked as PEP 517 impact to see if there's any known still relevant significant UX issues.

I thought there was already an open issue for always using PEP 517 but I can't find it right now.

Isn't this basically #6334 or #9175?

[pfmoore]

Isn't pip's deprecation policy two releases? Why not 25.1 -> 25.3?

Given the situation with setuptools and wheel, it seems like there's probably no point drawing out the deprecation - we'll just end up with people hitting the known issues, and having to advise them to use --use-pep517 in any case.

[notatallshaw]

Given the situation with setuptools and wheel, it seems like there's probably no point drawing out the deprecation - we'll just end up with people hitting the known issues, and having to advise them to use --use-pep517 in any case.

What about applications and libraries that will be broken by this change? What makes this change special to not give them a normal amount of notice to fix their projects?

As I say, uv does get occasional feedback, I'm sure even now pip is still distributed to a much wider audience.

[notatallshaw]

I'll also note PEP 517 doesn't save users from the setuptools/wheel issue if they've defined their pyproject.toml like so:

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

Which isn't unusual: https://github.com/search?q=requires+%3D+%5B%22setuptools%22%2C+%22wheel%22%5D+language%3Atoml+path%3Apyproject.toml&type=code.

And because pip doesn't output build backend warnings, users aren't currently informed, by default, that this will break in the future and they should remove wheel from their build-system.requires.

[pradyunsg]

Any particular reason to have a duplicate issue for our discussion here, given that #9175 exists?

[sbidoul]

Any particular reason to have a duplicate issue for our discussion here, given that #9175 exists?

Except for my apparent inability to unheart old issues, no. ;) Or perhaps, the fact that I highlight a new failure mode for the legacy code path that was not present before, which is a new reason to push the deprecation forward, in my view.

I'll also note PEP 517 doesn't save users from the setuptools/wheel issue if they've defined their pyproject.toml like so:

I think users with such a pyproject.toml will not see any problem because they will get build isolation by default and obtain the last version of setuptools and wheel which should be compatible. If they consciously disable build isolation, getting compatible versions is on them, and was and still is ok.

The issue here is for projects without pyproject.toml where pip uses bdist_wheel without build isolation if setuptools and wheel are installed in the pip environment, which is something most users don't configure consciously themselves.

[sbidoul]

I have created the deprecation PR: #13319. We can discuss the timeline there, so closing this one.

[notatallshaw]

I think users with such a pyproject.toml will not see any problem because they will get build isolation by default and obtain the last version of setuptools and wheel which should be compatible. If they consciously disable build isolation, getting compatible versions is on them, and was and still is ok.

Build isolation does not save you here, under the circumstances I outlined above, when wheel 0.46.0 (the latest but currently yanked) and the latest setuptools were installed they were not compatible because setuptools normally uses it's own vendered version of wheel, but when wheel is installed it uses that one instead: pypa/setuptools#4457, and that broke lots of projects when wheel 0.46.0 removed something that setuptools was using.

This dependency is being discussed in pypa/setuptools#4935.

The issue here is for projects without pyproject.toml where pip uses bdist_wheel without build isolation if setuptools and wheel are installed in the pip environment, which is something most users don't configure consciously themselves.

I understand, but as above, this issue is not limited to non PEP-517 projects, and lots of other projects will be broken by using PEP-517: astral-sh/uv#2252

[notatallshaw]

There was a secondary issue with setuptools/wheel under PEP 517, which is a bit more nuanced, but an old version of setuptools was in projects cache (perhaps it was installed in an older docker layer, perhaps their distribution automatically installs an old version), but there wasn't a version of wheel in their cache.

So under PEP 517 they were getting an old cached setuptools and a new version of wheel, now it turned out even the latest version of setuptools had issues with wheel also, but this was another situation of possible failure as PEP 517 is not guaranteeing you the latest, hopefully fixed, version of everything.

I'm not really sure why this was happening, but you can read user reports of it on the wheel issue: pypa/wheel#659

Edit: Actually rereading this I think I misunderstood this situation, I'll do a bit more investigation and post a new issue if I think there's a pip issue here.

[sbidoul]

I understand that. There are bugs setuptools/wheel can fix, but the case I mentioned in OP does not seem fixable, and we will soon be in a situation where our logic to determine if bdist_wheel can be used will not be correct anymore. So to me this signals that the time has come to remove that legacy. I'm of course open to discussing the timeline.

[notatallshaw]

I am in strong agreement with removing this logic, just not in breaking affected projects with an accelerated timeline.

[pfmoore]

I don't think this is worth an extended debate - I'm fine with just going for the normal deprecation period, if that avoids arguments.

However, I think the critical point here is that the pip maintainers don't¹ understand the whole issue with setuptools and wheel well enough to advise users, or provide workarounds. The issues are acknowledged as bugs by the setuptools and wheel projects, and fixes have been implemented (for example, the offending wheel release was yanked). I'm fine with helping the setuptools/wheel projects find workarounds and/or solutions for users who are still hit by these issues, but I don't think it's our job to find such workarounds ourselves.

In the context of this deprecation, the legacy code path may or may not either cause or avoid certain instances of the issues. I don't feel confident in us making that determination. If the setuptools maintainers have concerns about pip dropping the legacy path, then they can speak up (it would probably be prudent to let them know our plans, though). But otherwise, we should proceed normally, not letting bugs in other projects determine our plans.

Footnotes

1. And shouldn't need to! ↩