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