Debian Codegraph @

Doc/library/ensurepip.rst

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