What's the difference between "pip install" and "python -m pip install"?

I have a local version of Python 3.4.1 and I can run python -m pip install, but I'm unable to find the pip binary to run pip install. What's the difference between these two?

Solution

They do exactly the same thing, assuming pip is using the same version of Python as the python executable. The docs for distributing Python modules were just updated to suggest using python -m pip instead of the pip executable, because it allows you to be explicit about which version of Python to use. In systems with more than one version of Python installed, it's not always clear which one pip is linked to.

Here's some more concrete "proof" that both commands should do the same thing, beyond just trusting my word and the bug report I linked :)

If you take a look at the pip executable script, it's just doing this:

from pkg_resources import load_entry_point
<snip>
load_entry_point('pip==1.5.4', 'console_scripts', 'pip')()

It's calling load_entry_point, which returns a function, and then executing that function. The entry point it's using is called 'console_scripts'. If you look at the entry_points.txt file for pip (/usr/lib/python2.7/dist-packages/pip-1.5.4.egg-info/entry_points.txt on my Ubuntu machine), you'll see this:

[console_scripts]
pip = pip:main
pip2.7 = pip:main
pip2 = pip:main

So the entry point returned is the main function in the pip module.

When you run python -m pip, you're executing the __main__.py script inside the pip package. That looks like this:

import sys
from .runner import run

if __name__ == '__main__':
    exit = run()
    if exit:
        sys.exit(exit)

And the runner.run function looks like this:

def run():
    base = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    ## FIXME: this is kind of crude; if we could create a fake pip
    ## module, then exec into it and update pip.__path__ properly, we
    ## wouldn't have to update sys.path:
    sys.path.insert(0, base)
    import pip
    return pip.main()

As you can see, it's just calling the pip.main function, too. So both commands end up calling the same main function in pip/__init__.py.