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

• [X] I agree to follow the PSF Code of Conduct.