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

diff --git a/Doc/distributing/index.rst b/Doc/distributing/index.rst
index 4bcb63351e56b0bdf38bf17c7cc3b26bed7a2f5e..9949553dde33f86aaf5ff4a31c7c3eb0aacc1b6c 100644 (file)
--- 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 10933765843399a6408ad6f083cb238cec8fc3b7..5fb91267f1c21dbd0db22c67cf1c1366334d191b 100644 (file)
--- 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 12846136b698bef7d5818a5d73d20868c0aa49ef..1bf182eb1deb340f34890def6fe002a896ab1dbb 100644 (file)
--- 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?