mirror of
https://github.com/python/cpython.git
synced 2024-12-16 21:34:44 +08:00
75e59a97f5
Add --with-wheel-pkg-dir=PATH option to the ./configure script. If specified, the ensurepip module looks for setuptools and pip wheel packages in this directory: if both are present, these wheel packages are used instead of ensurepip bundled wheel packages. Some Linux distribution packaging policies recommend against bundling dependencies. For example, Fedora installs wheel packages in the /usr/share/python-wheels/ directory and don't install the ensurepip._bundled package. ensurepip: Remove unused runpy import.
136 lines
4.9 KiB
ReStructuredText
136 lines
4.9 KiB
ReStructuredText
:mod:`ensurepip` --- Bootstrapping the ``pip`` installer
|
|
========================================================
|
|
|
|
.. module:: ensurepip
|
|
:synopsis: Bootstrapping the "pip" installer into an existing Python
|
|
installation or virtual environment.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
--------------
|
|
|
|
The :mod:`ensurepip` package provides support for bootstrapping the ``pip``
|
|
installer into an existing Python installation or virtual environment. This
|
|
bootstrapping approach reflects the fact that ``pip`` is an independent
|
|
project with its own release cycle, and the latest available stable version
|
|
is bundled with maintenance and feature releases of the CPython reference
|
|
interpreter.
|
|
|
|
In most cases, end users of Python shouldn't need to invoke this module
|
|
directly (as ``pip`` should be bootstrapped by default), but it may be
|
|
needed if installing ``pip`` was skipped when installing Python (or
|
|
when creating a virtual environment) or after explicitly uninstalling
|
|
``pip``.
|
|
|
|
.. note::
|
|
|
|
This module *does not* access the internet. All of the components
|
|
needed to bootstrap ``pip`` are included as internal parts of the
|
|
package.
|
|
|
|
.. seealso::
|
|
|
|
:ref:`installing-index`
|
|
The end user guide for installing Python packages
|
|
|
|
:pep:`453`: Explicit bootstrapping of pip in Python installations
|
|
The original rationale and specification for this module.
|
|
|
|
|
|
Command line interface
|
|
----------------------
|
|
|
|
The command line interface is invoked using the interpreter's ``-m`` switch.
|
|
|
|
The simplest possible invocation is::
|
|
|
|
python -m ensurepip
|
|
|
|
This invocation will install ``pip`` if it is not already installed,
|
|
but otherwise does nothing. To ensure the installed version of ``pip``
|
|
is at least as recent as the one available in ``ensurepip``, pass the
|
|
``--upgrade`` option::
|
|
|
|
python -m ensurepip --upgrade
|
|
|
|
By default, ``pip`` is installed into the current virtual environment
|
|
(if one is active) or into the system site packages (if there is no
|
|
active virtual environment). The installation location can be controlled
|
|
through two additional command line options:
|
|
|
|
* ``--root <dir>``: Installs ``pip`` relative to the given root directory
|
|
rather than the root of the currently active virtual environment (if any)
|
|
or the default root for the current Python installation.
|
|
* ``--user``: Installs ``pip`` into the user site packages directory rather
|
|
than globally for the current Python installation (this option is not
|
|
permitted inside an active virtual environment).
|
|
|
|
By default, the scripts ``pipX`` and ``pipX.Y`` will be installed (where
|
|
X.Y stands for the version of Python used to invoke ``ensurepip``). The
|
|
scripts installed can be controlled through two additional command line
|
|
options:
|
|
|
|
* ``--altinstall``: if an alternate installation is requested, the ``pipX``
|
|
script will *not* be installed.
|
|
|
|
* ``--default-pip``: if a "default pip" installation is requested, the
|
|
``pip`` script will be installed in addition to the two regular scripts.
|
|
|
|
Providing both of the script selection options will trigger an exception.
|
|
|
|
|
|
Module API
|
|
----------
|
|
|
|
:mod:`ensurepip` exposes two functions for programmatic use:
|
|
|
|
.. function:: version()
|
|
|
|
Returns a string specifying the available version of pip that will be
|
|
installed when bootstrapping an environment.
|
|
|
|
.. function:: bootstrap(root=None, upgrade=False, user=False, \
|
|
altinstall=False, default_pip=False, \
|
|
verbosity=0)
|
|
|
|
Bootstraps ``pip`` into the current or designated environment.
|
|
|
|
*root* specifies an alternative root directory to install relative to.
|
|
If *root* is ``None``, then installation uses the default install location
|
|
for the current environment.
|
|
|
|
*upgrade* indicates whether or not to upgrade an existing installation
|
|
of an earlier version of ``pip`` to the available version.
|
|
|
|
*user* indicates whether to use the user scheme rather than installing
|
|
globally.
|
|
|
|
By default, the scripts ``pipX`` and ``pipX.Y`` will be installed (where
|
|
X.Y stands for the current version of Python).
|
|
|
|
If *altinstall* is set, then ``pipX`` will *not* be installed.
|
|
|
|
If *default_pip* is set, then ``pip`` will be installed in addition to
|
|
the two regular scripts.
|
|
|
|
Setting both *altinstall* and *default_pip* will trigger
|
|
:exc:`ValueError`.
|
|
|
|
*verbosity* controls the level of output to :data:`sys.stdout` from the
|
|
bootstrapping operation.
|
|
|
|
.. audit-event:: ensurepip.bootstrap root ensurepip.bootstrap
|
|
|
|
.. note::
|
|
|
|
The bootstrapping process has side effects on both ``sys.path`` and
|
|
``os.environ``. Invoking the command line interface in a subprocess
|
|
instead allows these side effects to be avoided.
|
|
|
|
.. note::
|
|
|
|
The bootstrapping process may install additional modules required by
|
|
``pip``, but other software should not assume those dependencies will
|
|
always be present by default (as the dependencies may be removed in a
|
|
future version of ``pip``).
|