[UX] Constraint file lookup error message is misleading (a troubleshooting adventure)

[webknjaz]

Description

So I was helping out @thomasrockhu-codecov diagnose an issue over at codecov/codecov-cli#642 (comment) where he's working on building wheels for codecov-cli and release automation.

He asked me to help understand an error that was happening during smoke-testing. And the error was ambiguous enough to confuse us both.

Initially, I was presented with

$ pip install codecov_cli-10.1.0-cp311-cp311-macosx_11_0_arm64.whl
ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'

and a guess that pip tries to find a 'requirements.txt' file within said wheel, and it's not there.

I knew that it was impossible, but couldn't understand where it was coming from. And I couldn't reproduce locally. I assumed all sorts of things then (bugs in pip, messed up CPython install/build, somehow broken env in general).

At some point I suggested --no-deps because the only place that I expected possibly dealing with requirements installs would be ephemeral build envs. And since the requested install was a wheel, I thought it'd be coming from some dependency that needed to be built from sdist. But that didn't help.

Eventually, I asked for -vvvvv and got a traceback pointing to https://github.com/pypa/pip/blob/de44d99/src/pip/_internal/req/req_file.py#L587.

But I still couldn't get where the requirement file assumption was coming from. It was driving me crazy. The error said “requirements file”.

I inspected the wheel for having acceptable metadata. In a disbelief, I gave in to what Tom was implying at the beginning, and asked him to install some other known-good wheel. “Could it really be coming from a malformed wheel?” — I thought to myself, — “Nooo… It can't be true. I just can't!”
Tom reported that a different wheel produced the same error, and I restored my faith in at least partially understanding what was going on.

Now what? At this point, I've finally pasted the error into the pip tracker. There wasn't an issue calling out this ambiguity, but I've seen enough hints to make an educated guess.

Together with some other context, I've made an educated guess that Tom executed export PIP_CONSTRAINT=requirements.txt at some point earlier, in the same shell session, and never reset it. So it was influencing all his attempts to check if the wheels the CI was producing were installable.

While this was exciting to explore this rabbit hole, I figured that this needs to be documented as an opportunity to improve UX. So here I am. Doing that now.

Expected behavior

I suppose, I'd expect the error mentioning where that requirements.txt thing was coming from. It was PIP_CONSTRAINT env var, but even saying --constraint would've been a much better hint.

At no point did the verbose output mention what was the entire user-requests with any non-default settings coming from various places (env vars, CLI flags, config). This would've been extremely useful.

Oh, and the requirement file thing. It wasn't set as a requirement but a constraint. So the error message must've said it was a constraint file. It might be a good idea to print out some hint, even without the maximum verbosity, saying something like “The dependency resolution will additionally use constraints declared in file X as it was requested by the end user”.

pip version

main branch and the released versions

Python version

3.13 / 3.12 / irrelevant, really

OS

macOS / Gentoo Linux

How to Reproduce

$ PIP_CONSTRAINT=blah python -Im pip install blah
ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'blah'

Output

No response

Code of Conduct

• I agree to follow the PSF Code of Conduct.

[thomasrockhu-codecov]

Honestly, this was a far better writeup than I could have written myself. I think for our sanity, it would have been helpful knowing what env variables (that are not secret) were being consumed during pip install.

[webknjaz]

@thomasrockhu-codecov yeah, the env vars are mapped to the corresponding CLI args on the arg parser level: https://pip.pypa.io/en/stable/topics/configuration/#environment-variables. It's pretty common, frameworks like Click do this out of the box.

[notatallshaw]

Simple steps to reproduce in an empty directory:

$ PIP_CONSTRAINT=requirements.txt pip install --dry-run requests
ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'

A PR to improve this error message would be great.

[webknjaz]

@notatallshaw oh, you don't actually need an existing PyPI project for this repro. That's why I used blah in the example — it triggers the error before learning that there's no such project. I I'm under impression that the constraint file is loaded even before the depresolver gets even instantiated.

[notatallshaw]

That makes sense, I only posted that because I missed that you'd actually posted a "How to Reproduce".