Home | History | Annotate | Download | only in library 
      1 :mod:`ensurepip` --- Bootstrapping the ``pip`` installer
      2 ========================================================
      3 
      4 .. module:: ensurepip
      5    :synopsis: Bootstrapping the "pip" installer into an existing Python
      6               installation or virtual environment.
      7 
      8 .. versionadded:: 3.4
      9 
     10 --------------
     11 
     12 The :mod:`ensurepip` package provides support for bootstrapping the ``pip``
     13 installer into an existing Python installation or virtual environment. This
     14 bootstrapping approach reflects the fact that ``pip`` is an independent
     15 project with its own release cycle, and the latest available stable version
     16 is bundled with maintenance and feature releases of the CPython reference
     17 interpreter.
     18 
     19 In most cases, end users of Python shouldn't need to invoke this module
     20 directly (as ``pip`` should be bootstrapped by default), but it may be
     21 needed if installing ``pip`` was skipped when installing Python (or
     22 when creating a virtual environment) or after explicitly uninstalling
     23 ``pip``.
     24 
     25 .. note::
     26 
     27    This module *does not* access the internet. All of the components
     28    needed to bootstrap ``pip`` are included as internal parts of the
     29    package.
     30 
     31 .. seealso::
     32 
     33    :ref:`installing-index`
     34       The end user guide for installing Python packages
     35 
     36    :pep:`453`: Explicit bootstrapping of pip in Python installations
     37       The original rationale and specification for this module.
     38 
     39 
     40 Command line interface
     41 ----------------------
     42 
     43 The command line interface is invoked using the interpreter's ``-m`` switch.
     44 
     45 The simplest possible invocation is::
     46 
     47     python -m ensurepip
     48 
     49 This invocation will install ``pip`` if it is not already installed,
     50 but otherwise does nothing. To ensure the installed version of ``pip``
     51 is at least as recent as the one bundled with ``ensurepip``, pass the
     52 ``--upgrade`` option::
     53 
     54     python -m ensurepip --upgrade
     55 
     56 By default, ``pip`` is installed into the current virtual environment
     57 (if one is active) or into the system site packages (if there is no
     58 active virtual environment). The installation location can be controlled
     59 through two additional command line options:
     60 
     61 * ``--root <dir>``: Installs ``pip`` relative to the given root directory
     62   rather than the root of the currently active virtual environment (if any)
     63   or the default root for the current Python installation.
     64 * ``--user``: Installs ``pip`` into the user site packages directory rather
     65   than globally for the current Python installation (this option is not
     66   permitted inside an active virtual environment).
     67 
     68 By default, the scripts ``pipX`` and ``pipX.Y`` will be installed (where
     69 X.Y stands for the version of Python used to invoke ``ensurepip``). The
     70 scripts installed can be controlled through two additional command line
     71 options:
     72 
     73 * ``--altinstall``: if an alternate installation is requested, the ``pipX``
     74   script will *not* be installed.
     75 
     76 * ``--default-pip``: if a "default pip" installation is requested, the
     77    ``pip`` script will be installed in addition to the two regular scripts.
     78 
     79 Providing both of the script selection options will trigger an exception.
     80 
     81 
     82 Module API
     83 ----------
     84 
     85 :mod:`ensurepip` exposes two functions for programmatic use:
     86 
     87 .. function:: version()
     88 
     89    Returns a string specifying the bundled version of pip that will be
     90    installed when bootstrapping an environment.
     91 
     92 .. function:: bootstrap(root=None, upgrade=False, user=False, \
     93                         altinstall=False, default_pip=False, \
     94                         verbosity=0)
     95 
     96    Bootstraps ``pip`` into the current or designated environment.
     97 
     98    *root* specifies an alternative root directory to install relative to.
     99    If *root* is ``None``, then installation uses the default install location
    100    for the current environment.
    101 
    102    *upgrade* indicates whether or not to upgrade an existing installation
    103    of an earlier version of ``pip`` to the bundled version.
    104 
    105    *user* indicates whether to use the user scheme rather than installing
    106    globally.
    107 
    108    By default, the scripts ``pipX`` and ``pipX.Y`` will be installed (where
    109    X.Y stands for the current version of Python).
    110 
    111    If *altinstall* is set, then ``pipX`` will *not* be installed.
    112 
    113    If *default_pip* is set, then ``pip`` will be installed in addition to
    114    the two regular scripts.
    115 
    116    Setting both *altinstall* and *default_pip* will trigger
    117    :exc:`ValueError`.
    118 
    119    *verbosity* controls the level of output to :data:`sys.stdout` from the
    120    bootstrapping operation.
    121 
    122    .. note::
    123 
    124       The bootstrapping process has side effects on both ``sys.path`` and
    125       ``os.environ``. Invoking the command line interface in a subprocess
    126       instead allows these side effects to be avoided.
    127 
    128    .. note::
    129 
    130       The bootstrapping process may install additional modules required by
    131       ``pip``, but other software should not assume those dependencies will
    132       always be present by default (as the dependencies may be removed in a
    133       future version of ``pip``).
    134