Use python -m pip install in porting guide and venv docs (GH-13257)

bsolomon1124 · brettcannon · commit 8b2aa1fddeb6 · 2019-06-21T11:20:21.000-07:00
This is to help prevent people from accidentally installing into the wrong Python interpreter if they are not aware of which Python interpreter `pip` points to.
diff --git a/Doc/howto/pyporting.rst b/Doc/howto/pyporting.rst
@@ -31,20 +31,26 @@ are:
 
 #. Only worry about supporting Python 2.7
 #. Make sure you have good test coverage (coverage.py_ can help;
-   ``pip install coverage``)
+   ``python -m pip install coverage``)
 #. Learn the differences between Python 2 & 3
-#. Use Futurize_ (or Modernize_) to update your code (e.g. ``pip install future``)
+#. Use Futurize_ (or Modernize_) to update your code (e.g. ``python -m pip install future``)
 #. Use Pylint_ to help make sure you don't regress on your Python 3 support
-   (``pip install pylint``)
+   (``python -m pip install pylint``)
 #. Use caniusepython3_ to find out which of your dependencies are blocking your
-   use of Python 3 (``pip install caniusepython3``)
+   use of Python 3 (``python -m pip install caniusepython3``)
 #. Once your dependencies are no longer blocking you, use continuous integration
    to make sure you stay compatible with Python 2 & 3 (tox_ can help test
-   against multiple versions of Python; ``pip install tox``)
+   against multiple versions of Python; ``python -m pip install tox``)
 #. Consider using optional static type checking to make sure your type usage
    works in both Python 2 & 3 (e.g. use mypy_ to check your typing under both
-   Python 2 & Python 3).
+   Python 2 & Python 3; ``python -m pip install mypy``).
 
+.. note::
+
+   Note: Using ``python -m pip install`` guarantees that the ``pip`` you invoke
+   is the one installed for the Python currently in use, whether it be
+   a system-wide ``pip`` or one installed within a
+   :ref:`virtual environment <tut-venv>`.
 
 Details
 =======
@@ -71,7 +77,7 @@ Drop support for Python 2.6 and older
 While you can make Python 2.5 work with Python 3, it is **much** easier if you
 only have to work with Python 2.7. If dropping Python 2.5 is not an
 option then the six_ project can help you support Python 2.5 & 3 simultaneously
-(``pip install six``). Do realize, though, that nearly all the projects listed
+(``python -m pip install six``). Do realize, though, that nearly all the projects listed
 in this HOWTO will not be available to you.
 
 If you are able to skip Python 2.5 and older, then the required changes
diff --git a/Doc/tutorial/venv.rst b/Doc/tutorial/venv.rst
@@ -110,7 +110,7 @@ You can install the latest version of a package by specifying a package's name:
 
 .. code-block:: bash
 
-  (tutorial-env) $ pip install novas
+  (tutorial-env) $ python -m pip install novas
   Collecting novas
     Downloading novas-3.1.1.3.tar.gz (136kB)
   Installing collected packages: novas
@@ -122,7 +122,7 @@ package name  followed by ``==`` and the version number:
 
 .. code-block:: bash
 
-  (tutorial-env) $ pip install requests==2.6.0
+  (tutorial-env) $ python -m pip install requests==2.6.0
   Collecting requests==2.6.0
     Using cached requests-2.6.0-py2.py3-none-any.whl
   Installing collected packages: requests
@@ -135,7 +135,7 @@ install --upgrade`` to upgrade the package to the latest version:
 
 .. code-block:: bash
 
-  (tutorial-env) $ pip install --upgrade requests
+  (tutorial-env) $ python -m pip install --upgrade requests
   Collecting requests
   Installing collected packages: requests
     Found existing installation: requests 2.6.0
@@ -193,7 +193,7 @@ necessary packages with ``install -r``:
 
 .. code-block:: bash
 
-  (tutorial-env) $ pip install -r requirements.txt
+  (tutorial-env) $ python -m pip install -r requirements.txt
   Collecting novas==3.1.1.3 (from -r requirements.txt (line 1))
     ...
   Collecting numpy==1.9.2 (from -r requirements.txt (line 2))
