[Distutils] The future of invoking pip

[Donald Stufft]

On November 9, 2015 at 6:17:41 AM, Oscar Benjamin (oscar.j.benjamin at gmail.com) wrote:
> On 9 November 2015 at 10:44, Wolfgang Maier
> wrote:
> >
> > Something I miss in all the discussions taking place here is the fact that
> > python -m pip is the officially documented way of invoking pip at
> > https://docs.python.org/3/installing/index.html#basic-usage and it is not
> > particularly helpful if that recommendation keeps changing back and forth.
> >
> > I know some people don't like the wordy invocation, but other people
> > (including me) use and teach it because it works reliably. Just because a
> > pip executable based invocation pattern looks better, I don't think it
> > justifies the change.
>  
> I also teach this invocation. Somehow you have to select the Python
> version you're interested in and I really don't see why
>  
> $ pip -p ./foo/bar/python ...
>  
> is better than
>  
> $ ./foo/bar/python -m pip ...
>  
> I already need to explain to students how to ensure that their Python
> executable is on PATH. Needing pip to be on PATH as well is just
> another possible source of confusion (even if there's only one Python
> installation).
>  

The primary difference is one of verbosity, particularly in common cases. You’ll have situations like:

* I don’t care what version of Python something is being installed into, I just want to install it to use the CLI of some project that just happens to be written in python. ``pip install`` vs ``python -m pip install``.
* I’ve already selected which version of Python should be used either via virtual environment, conda environment, or some other environment manager. ``pip install`` vs ``python -m pip install``.
* I just want to install into the same thing as ``python3`` or ``python2`` or ``python3.3``. ``pip -3 install`` vs ``python3 -m pip install`` or ``pip -2 install`` vs ``python2 -m pip install`` or ``pip -3.3 install`` vs ``python3.3 -m pip install``.
* I want to install into ``pypy``. ``pip -p peppy install`` vs ``pypy -m pip install``.
* I want to install into ``./foo/bar/python``. ``pip -p ./foo/bar/python install`` vs ./foo/bar/python -m pip install``.

I think the main thing this illustrates is that the ``pip -p`` version is nicer in the common scenarios like not caring what version of Python you’re installing into, having pre-selected the version of Python, or just wanting to install into a particular CPython of X or X.Y version [1]. It only really degrades into an equivalent invocation in the less common cases where you need to install into a non CPython interpreter or your interpreter isn’t one of ``pythonX`` or ``pythonX.Y`` on your path.

Of course, the main benefit of ``python -m`` is that it’s a standard (within Python) interface and it already works and doesn’t require any backwards incompatibilities (except to possibly remove the ``pip`` or ``pipX.Y`` commands due to their footman-ish nature). It also delays the need to ensure that the distutils bindir is on $PATH (though you’ll quickly need to ensure it’s there anyways if you install anything that doesn’t use ``-m`` to be invoked).

[1] This could be made better by shipping a ``py`` launcher on *nix too, which brings it down to ``py -3 -m pip`` which is still a bit longer than ``pip -3`` but is better than ``python3 -m pip``.

-----------------
Donald Stufft
PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA