From 1d52096d1466ed771c22a2d97e8cae6935fcdf8e Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sat, 6 Sep 2014 20:38:23 +1000 Subject: Issue #22295: Adopt 'python -m pip' as the preferred invocation --- Doc/distributing/index.rst | 13 +++++++++++-- Doc/glossary.rst | 8 ++++++++ Doc/installing/index.rst | 30 ++++++++++++++++++++---------- 3 files changed, 39 insertions(+), 12 deletions(-) (limited to 'Doc') diff --git a/Doc/distributing/index.rst b/Doc/distributing/index.rst index 4bcb63351e..9949553dde 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 1093376584..5fb91267f1 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 12846136b6..1bf182eb1d 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 `__ 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 `__. @@ -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? -- cgit v1.2.1