Special Case Install Warning for Literal Package Name "requirements.txt"

[briantracy]

What's the problem this feature will solve?

I work in a technical support / system administration role for students and an extremely common issue they have is accidentally misusing the pip install command like this:

$ pip install requirements.txt
ERROR: Could not find a version that satisfies the requirement requirements.txt (from versions: none)
ERROR: No matching distribution found for requirements.txt

They of course want to install the packages listed in requirements.txt, and not the literal package named requirements.txt (there is none). As such they should be doing pip install -r requirements.txt (adding the -r flag), but this is not immediately obvious for beginners.

Describe the solution you'd like

I understand that you can't really hold people's hand for everything, and at a certain point, the user is responsible for investigating issues themselves, but this one keeps coming up and I think it is a rather low hanging fruit. I think it would be reasonable to include a special case error message when attempting to install a package that is literally named requirements.txt.

$ pip install requirements.txt
ERROR: Could not find a version that satisfies the requirement requirements.txt (from versions: none)
ERROR: No matching distribution found for requirements.txt
INFO: You are attempting to install a package literally named "requirements.txt".
INFO: You might want `pip install -r requirements.txt` to install packages listed in a file.

Alternative Solutions

This sort of diagnostic is frequently issued by compilers when the developer attempts to write something very close to an idiomatic expression. For example, C compilers will generally warn when using an unknown symbol that is 1 letter away from a common symbol (kread: no such symbol, did you mean read?).

Additional context

pip install -r requirements.txt is such a common idiom, and in my experience is frequently mis-remembered as pip install requirements.txt. For this reason, I suggest special casing the standard error message and adding an additional line suggesting the idiomatic use.

I would be happy to tackle this issue myself (it should be a relatively trivial fix), but I wanted to know what people think before getting to work. Thanks for your time.

[uranusjr]

Sounds like a good feature to me, feel free to send in a PR!

As a side note, you might want to change the instruction to the following instead; pip emits a more useful message if the user forgets -r and the argument looks like a path:

$ pip install -r ./requirements.txt
ERROR: Invalid requirement: './requirements.txt'
Hint: It looks like a path. The path does exist. The argument you provided (./requirements.txt) appears to be
a requirements file. If that is the case, use the '-r' flag to install the packages specified within it.

[briantracy]

Thanks for the feedback, I will definitely be working on this. I had one question though.

Do you think it is worth it to bring in true path detection (like os.path.exists()) or just do everything at the string comparison level (by directly examining the path being requested).

The benefit of actual path detection (ie: searching the file system) is that it picks up more cases of the issue such as the one you pointed out (./requirements.txt) as well as completely different file names (like packages.txt).

The downside is the added complexity of bringing in the os module in the two files that issue this warning.

What do you think?

[uranusjr]

I would just do a literal string match to requirements.txt. If someone knows enough to name the requirements file something else, they should know enough to understand it’s important to supply -r and notice the wrong output when they forget to. We don’t need to be overly smart for them.

[briantracy]

@uranusjr Not sure if you were notified, but I submitted a pull request that needs a maintainer's permission to run through the CI system. Thanks for all your help on this one.

[ichard26]

I don't like how error is presented as is, but this will improve once the error is migrated to the more user friendly rich error format (see #10421).

Regardless, this issue can be issue as the resolving PR has been merged (and released into the wild too!) almost three years ago?!

[ichard26]

*nudge* This issue can be closed as the resolving PR has been merged and published ~3 years ago.