Issue #22295: Adopt 'python -m pip' as the preferred invocation

3 files changed, 39 insertions, 12 deletions

diff --git a/Doc/distributing/index.rst b/Doc/distributing/index.rst
index 4bcb633..9949553 100644
--- a/Doc/distributing/index.rst
+++ b/Doc/distributing/index.rst
@@ -93,9 +93,18 @@ is important to have standard tools that work consistently, even on older
 versions of Python.
 
 The currently recommended build and distribution tools can be installed
-using ``pip``::
+by invoking the ``pip`` module at the command line::
 
-    pip install setuptools wheel twine
+    python -m pip install setuptools wheel twine
+
+.. note::
+
+   For POSIX users (including Mac OS X and Linux users), these instructions
+   assume the use of a :term:`virtual environment`.
+
+   For Windows users, these instructions assume that the option to
+   adjust the system PATH environment variable was selected when installing
+   Python.
 
 The Python Packaging User Guide includes more details on the `currently
 recommended tools`_.
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 1093376..5fb9126 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -857,6 +857,14 @@ Glossary
       dictionary view to become a full list use ``list(dictview)``.  See
       :ref:`dict-views`.
 
+   virtual environment
+      A cooperatively isolated runtime environment that allows Python users
+      and applications to install and upgrade Python distribution packages
+      without interfering with the behaviour of other Python applications
+      running on the same system.
+
+      See also :ref:`scripts-pyvenv`
+
    virtual machine
       A computer defined entirely in software.  Python's virtual machine
       executes the :term:`bytecode` emitted by the bytecode compiler.
diff --git a/Doc/installing/index.rst b/Doc/installing/index.rst
index 1284613..1bf182e 100644
--- a/Doc/installing/index.rst
+++ b/Doc/installing/index.rst
@@ -40,6 +40,10 @@ Key terms
 * ``pyvenv`` is the standard tool for creating virtual environments, and has
   been part of Python since Python 3.3. Starting with Python 3.4, it
   defaults to installing ``pip`` into all created virtual environments
+* ``virtualenv`` is a third party alternative (and predecessor) to
+  ``pyvenv``. It allows virtual environments to be used on versions of
+  Python prior to 3.4, which either don't provide ``pyvenv`` at all, or
+  aren't able to automatically install ``pip`` into created environments.
 * the `Python Package Index <https://pypi.python.org/pypi>`__ is a public
   repository of open source licensed packages made available for use by
   other Python users
@@ -63,27 +67,33 @@ Basic usage
 ===========
 
 The standard packaging tools are all designed to be used from the command
-line. For Windows users, the examples below assume that the option to
-adjust the system PATH environment variable was selected when installing
-Python. For Linux users, the command to install into the system version of
-Python 3 is likely to be ``pip3`` rather than ``pip``.
+line.
 
 The following command will install the latest version of a module and its
 dependencies from the Python Package Index::
 
-    pip install SomePackage
+    python -m pip install SomePackage
+
+.. note::
+
+   For POSIX users (including Mac OS X and Linux users), the examples in
+   this guide assume the use of a :term:`virtual environment`.
+
+   For Windows users, the examples in this guide assume that the option to
+   adjust the system PATH environment variable was selected when installing
+   Python.
 
 It's also possible to specify an exact or minimum version directly on the
 command line::
 
-    pip install SomePackage==1.0.4    # specific version
-    pip install 'SomePackage>=1.0.4'  # minimum version
+    python -m pip install SomePackage==1.0.4    # specific version
+    python -m pip install 'SomePackage>=1.0.4'  # minimum version
 
 Normally, if a suitable module is already installed, attempting to install
 it again will have no effect. Upgrading existing modules must be requested
 explicitly::
 
-    pip install --upgrade SomePackage
+    python -m pip install --upgrade SomePackage
 
 More information and resources regarding ``pip`` and its capabilities can be
 found in the `Python Packaging User Guide <http://packaging.python.org>`__.
@@ -120,8 +130,8 @@ User Guide.
 ... install packages just for the current user?
 -----------------------------------------------
 
-Passing the ``--user`` option to ``pip install`` will install a package
-just for the current user, rather than for all users of the system.
+Passing the ``--user`` option to ``python -m pip install`` will install a
+package just for the current user, rather than for all users of the system.
 
 
 ... install scientific Python packages?