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:: 2.7.9
9
10The :mod:`ensurepip` package provides support for bootstrapping the ``pip``
11installer into an existing Python installation or virtual environment. This
12bootstrapping approach reflects the fact that ``pip`` is an independent
13project with its own release cycle, and the latest available stable version
14is bundled with maintenance and feature releases of the CPython reference
15interpreter.
16
17In most cases, end users of Python shouldn't need to invoke this module
18directly (as ``pip`` should be bootstrapped by default), but it may be
19needed if installing ``pip`` was skipped when installing Python (or
20when creating a virtual environment) or after explicitly uninstalling ``pip``.
21
22.. note::
23
24   This module *does not* access the internet. All of the components
25   needed to bootstrap ``pip`` are included as internal parts of the
26   package.
27
28.. seealso::
29
30   :ref:`installing-index`
31      The end user guide for installing Python packages
32
33   :pep:`453`: Explicit bootstrapping of pip in Python installations
34      The original rationale and specification for this module.
35
36   :pep:`477`: Backport ensurepip (PEP 453) to Python 2.7
37      The rationale and specification for backporting PEP 453 to Python 2.7.
38
39
40Command line interface
41----------------------
42
43The command line interface is invoked using the interpreter's ``-m`` switch.
44
45The simplest possible invocation is::
46
47    python -m ensurepip
48
49This invocation will install ``pip`` if it is not already installed,
50but otherwise does nothing. To ensure the installed version of ``pip``
51is at least as recent as the one bundled with ``ensurepip``, pass the
52``--upgrade`` option::
53
54    python -m ensurepip --upgrade
55
56By default, ``pip`` is installed into the current virtual environment
57(if one is active) or into the system site packages (if there is no
58active virtual environment). The installation location can be controlled
59through 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
68By default, the scripts ``pip``, ``pipX``, and ``pipX.Y`` will be installed
69(where X.Y stands for the version of Python used to invoke ``ensurepip``). The
70scripts installed can be controlled through two additional command line
71options:
72
73* ``--altinstall``: if an alternate installation is requested, the ``pip`` and
74  ``pipX`` script will *not* be installed.
75
76* ``--no-default-pip``: if a non-default installation is request, the ``pip``
77  script will *not* be installed.
78
79.. versionchanged:: 2.7.15
80   The exit status is non-zero if the command fails.
81
82
83Module API
84----------
85
86:mod:`ensurepip` exposes two functions for programmatic use:
87
88.. function:: version()
89
90   Returns a string specifying the bundled version of pip that will be
91   installed when bootstrapping an environment.
92
93.. function:: bootstrap(root=None, upgrade=False, user=False, \
94                        altinstall=False, default_pip=True, \
95                        verbosity=0)
96
97   Bootstraps ``pip`` into the current or designated environment.
98
99   *root* specifies an alternative root directory to install relative to.
100   If *root* is ``None``, then installation uses the default install location
101   for the current environment.
102
103   *upgrade* indicates whether or not to upgrade an existing installation
104   of an earlier version of ``pip`` to the bundled version.
105
106   *user* indicates whether to use the user scheme rather than installing
107   globally.
108
109   By default, the scripts ``pip``, ``pipX``, and ``pipX.Y`` will be installed
110   (where X.Y stands for the current version of Python).
111
112   If *altinstall* is set, then ``pip`` and ``pipX`` will *not* be installed.
113
114   If *default_pip* is set to ``False``, then ``pip`` will *not* be installed.
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