Better documentation on install --user/--no-user and related envvars

[jlumpe]

What's the problem this feature will solve?

When running pip install and it is detected that the user does not have permissions to edit site-packages, it defaults to behaving as if the --user option had been used:

Defaulting to user installation because normal site-packages is not writeable

I feel like this is problematic for the following reasons:

• It is often not what the user wants. If I intentionally wanted to do a user install, I would add the --user option explicitly.
• It is very easy to miss. The warning above is printed as the first line of output, followed immediately by a large amount of progress information that often fills the full height of the terminal.

I just ran into this issue when trying to update a package in a shared conda installation and I forgot to run the command as the maintenance user that own the conda environment directory. My mistake, but it's an easy one to make and I missed the warning amidst all the other output, so I was under the impression that it had done what I wanted. This led to further confusion when tests worked with my account, but failed for other users.

Describe the solution you'd like

Unless the --user option is given, check if site-packages is writeable and immediately fail with a useful error message if it not. This is close to the behavior with the undocumented --no-user option, which shows a message like the following:

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied: 'METADATA'
Consider using the `--user` option or check the permissions.

However the error happens when actually trying to write to site-packages, which is after checking dependences and (if no dependencies need installing/updating and installing from source) building the package. The check is already being done at the beginning by default, ideally I think it should fail immediately instead of continuing until the actual permissions error is encountered.

Changing the default behavior breaks backward compatibility, but the new behavior could be enabled through an environment variable.

Alternative Solutions

There is the (undocumented) --no-user option, but if I remember to type that every time then I'm remembering to be on the lookout for the issue anyway.

Additional context

(none)

Code of Conduct

• I agree to follow the PSF Code of Conduct.

[uranusjr]

It is often not what the user wants.

Citation needed, I guess? When is doing a user-site install a problem instead of sytem-wide?

[jlumpe]

Citation needed, I guess? When is doing a user-site install a problem instead of sytem-wide?

When I'm administering a Python environment used by multiple users, for one. I don't think this logic makes much sense. If a user install is always acceptable, why even have the option of doing a system install?

[notatallshaw]

I administered a Python distribution and needed to turn user installs off, I set up a default pip config with:

[global]
user = false

You can create it from the command line with pip config set global.user false.

My use case was that user installs were breaking conda installations as the base conda environment was read only, pip would install packages into the user site, this would very frequently break Spyder in the base Anaconda environment. This was further problematic because every conda environment on that Python version would pick up packages installed into the user site, so I had to do a lot of user education on not using pip user installs.

So, I am very sympathetic to this being the default behaviour, I also know a lot of users of pip have workflows that assume falling back to user installs by default, so it would likely be a hugely disruptive change.

[jlumpe]

@notatallshaw Thank you! This is exactly what I was looking for, and works better than the environment variable for my purposes.

Although using the config file solves my problem, I think my feature request could be modified to request better documentation related to boolean flags:

• Document the --no-user option to pip install. For many or most other boolean flags the enable/disable options are both listed (e.g. --compile/--no-compile).
• It appears I can get the behavior I want by setting PIP_USER=0. However other on/off option pairs have separate environment variables (e.g. PIP_COMPILE and PIP_NO_COMPILE). Is PIP_COMPILE=0 the same as PIP_NO_COMPILE=1? PIP_NO_USER=1 does not seem to have the same effect, but I can't tell if this is an exception. The environment variables section in the documentation page on configuration could clarify this.

[notatallshaw]

I agree, there could be better documentation here, when I set that up I made educated guesses about the config. I'm sure PRs would be welcome.

[eli-schwartz]

Can you also update the issue title? When I first saw this in the list of issues I thought it was (still) a discussion about changing the actual behavior and came prepared to argue against such a change... :)