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