pip install --user should check that the user's $PATH is correct

On Unix, pip install --user ... drops scripts into ~/.local/bin. Historically, this directory has not been on the default Debian/Ubuntu $PATH.

This is hopefully on its way to being fixed (bash 4.3-15 is on its way into Debian unstable now, and should hopefully land in Debian testing in a few weeks, bug report here; the Ubuntu bug that will hopefully be used to justify a backport of this fix into Xenial is here). But, even once the fix lands, all it will do is change the default for newly created accounts – so for a long time, there are going to be people who try running pip install --user and end up with it dropping executables into a directory that’s not on $PATH.

When pip install --user installs a script into ~/.local/bin (or the equivalent on other OSes, why not), then it should check the current os.environ["PATH"], and if this directory is not on the PATH, then it should print an explanatory message that warns the user and gives them some information on how to fix the problem.

(Or heck, it could even suggest they run pip fix-user-path to have pip automatically add tihs to their ~/.profile – it’s a little wonky but not too hard to make reasonably robust, and if it’s a manual action that tells the user what it’s doing as it runs then it should be reasonable helpful.)

(This would be a reasonable first fix for someone new to pip – does pip’s issue tracker have a tag for those?)

[njsmith]

I guess I’m currently +0 on pip fix-user-path on the following rationale:

• For users who understand how ~/.profile and friends work, then it’s a small convenience that they’ll use or ignore as they prefer, and if it breaks things then they’ll be able to fix it.
• For users who don’t understand how ~/.profile and friends work, then the best they can hope to do is to blindly follow some complicated instructions, and if those instructions have an error then they’re doomed regardless. So we might as well implement those instructions in the form of code, to at least eliminate human error and human pain.

For concreteness, I’m imagining a user interaction that would look something like

$ pip install --user virtualenv
Collecting virtualenv
  [...]
Successfully installed virtualenv-15.0.2

WARNING: this package provides a script called "virtualenv", and I put this
into your personal script directory, /home/njs/.local/bin/
BUT, your command line is not set up to look for scripts in this directory!
You won't be able to run the "virtualenv" script until you fix this.
For more information, see

   https://...

or, if you want me to try fixing your configuration for you automatically, run:

   pip fix-user-path

(You only have to do this once.)
$ pip fix-user-path
It looks like you're using the "bash" shell! Great, I know how to handle that.
I've added the following lines to the file /home/njs/.profile:

    # -- start lines automatically added by pip fix-user-path --
    export PATH=$HOME/.local/bin:$PATH
    # -- end lines automatically added by pip fix-user-path --

If this looks wrong, you can edit that file directly in your favorite text editor.

PLEASE NOTE: You probably need to log out and log back in before the
new configuration will take effect!
$ pip fix-user-path
It looks like you're using the "bash" shell! Great, I know how to handle that.
...I just checked the file /home/njs/.profile, and it looks like I've already fixed
your configuration for you, but it hasn't taken effect yet.
Most likely, this means you need to log out and log back in again.
If that doesn't help, [...]
$ logout
<start new shell>
$ pip fix-user-path
It looks like /home/njs/.local/bin is already on your $PATH, so there's
nothing for me to do -- you're all set!

[dstufft]

So here’s a question, it seems to me that we can get most of the way there by just having a suggested snippet in the error message without any sort of fix-me-up command. Yes it’ll require them to copy/paste but I think it’s a fairly trivial operation for them to do that, and we avoid any sort of “pip broke my profile” issues.