Pip: Why are useful command line options in pip undocumented and explicitly hidden?

[musically-ut]

I use export PIP_REQUIRE_VIRTUALENV=true; in my .bashrc to ensure that I do not accidentally pollute my global env while installing packages for the various projects I work on.

I vaguely remembered that this was the same as adding a --require-virtualenv to the command line while invoking pip.

However, I was unable to find _any_ documentation for this anywhere except in the source code, where help for the feature is explicitly suppressed (using SUPRESS_HELP)! There are 11 such options for which the help has also been explicitly disabled (e.g. --no-input).

I look through the history of the file, but did not find any mention of _why_ the feature was hidden in the commit messages.

Is this an experimental feature which should not be relied upon? Should I not use (nor encourage others to use) these features or is there a different way of using these features? Could someone please shine some light on this conundrum?

---

This is a question which I had previously posted on StackOverflow hoping that there was an explanation along the lines that these options were only to be used if pip was invoked from other dependency management software.

However, that doesn't seem to be case, or at least it isn't common knowledge.

[remram44]

+1, it's hard to defend hiding recognized command-line flags, but useful ones it's just stupid. SUPPRESS_HELP is meant for internal or otherwise-documented options, not to filter what you feel people should read about elsewhere.

Relevant code: cmdoptions.py

[keitherskine]

At the very least, please give guidance about whether these command options are still valid or are deprecated. Not documenting them at all just leaves them in limbo, and causes confusion for the users.

[justinmayer]

I fully agree that these extremely useful options should be documented. They were documented previously at the following, now-defunct location: http://www.pip-installer.org/en/latest/other-tools.html#using-pip-with-virtualenv

[chrahunt]

To be specific, in the current version of pip these are the hidden options:

| Name | Location | Note |
|-|-|-|
| --require-virtualenv | link | added in 301dc31, no explanation |
| --no-input | link | added in 4d33521, no explanation |
| --skip-requirements-regex | link | added in 5aa4be, no explanation - deprecated in #7297 |
| --no-use-pep517 | link | this was done in #5743 here probably just to remove any redundancy with --use-pep517 |
| --always-unzip | link | Commented with "Deprecated, remove later", looks like it is a no-op |
| install --no-user | link | #5116 indicates it needed more thought before exposing |

[deveshks]

There is now https://github.com/pypa/pip/pull/8182 to test --no-input and officially document and unhide it.

[pradyunsg]

At the very least, please give guidance about whether these command options are still valid or are deprecated.

Any pip functionality that is not documented in any form (in the CLI --help, or in docs/) is not supported. Documenting them would move the to being supported and following pip's deprecation policy.

I'm not opposed to supporting --no-input or --require-virtualenv. Both of these would likely need to be documented in the docs, in addition to surfacing them in --help.

[gutsytechster]

I would like to create the PR to document the --require-virtualenv. :)

[deveshks]

I'm not opposed to supporting --no-input or --require-virtualenv. Both of these would likely need to be documented in the docs, in addition to surfacing them in --help.

Correct me if I am wrong, but removing SUPPRESS_HELP from the cmdoptions should automatically document for e.g. --no-input under pip's General Options , as well as showing them in --help

Is there any other place in the docs we need to add these options manually?

[pradyunsg]

Is there any other place in the docs we need to add these options manually?

For --no-input, I don't think we need anything else.

For --require-virtualenv, I think we should add a section to the User Guide, describing the behavior of it and what the intended use case is.

[deveshks]

I have created issue https://github.com/pypa/pip/issues/8408 to get rid of --always-unzip from pip source. If this is something we are looking to do, I can go ahead and create a PR for it.

[deveshks]

I have created issue #8408 to get rid of --always-unzip from pip source. If this is something we are looking to do, I can go ahead and create a PR for it.

https://github.com/pypa/pip/pull/8470 is created for this.