ensurepip — Bootstrapping the
New in version 3.4.
Source code: Lib/ensurepip
ensurepip package provides support for bootstrapping the
installer into an existing Python installation or virtual environment. This
bootstrapping approach reflects the fact that
pip is an independent
project with its own release cycle, and the latest available stable version
is bundled with maintenance and feature releases of the CPython reference
In most cases, end users of Python shouldn’t need to invoke this module
pip should be bootstrapped by default), but it may be
needed if installing
pip was skipped when installing Python (or
when creating a virtual environment) or after explicitly uninstalling
This module does not access the internet. All of the components
needed to bootstrap
pip are included as internal parts of the
- Installing Python Modules
The end user guide for installing Python packages
- PEP 453: Explicit bootstrapping of pip in Python installations
The original rationale and specification for this module.
Availability: not Emscripten, not WASI.
This module does not work or is not available on WebAssembly platforms
WebAssembly platforms for more information.
Command line interface¶
The command line interface is invoked using the interpreter’s
The simplest possible invocation is:
python -m ensurepip
This invocation will install
pip if it is not already installed,
but otherwise does nothing. To ensure the installed version of
is at least as recent as the one available in
ensurepip, pass the
python -m ensurepip --upgrade
pip is installed into the current virtual environment
(if one is active) or into the system site packages (if there is no
active virtual environment). The installation location can be controlled
through two additional command line options:
--root <dir>: Installs
piprelative to the given root directory rather than the root of the currently active virtual environment (if any) or the default root for the current Python installation.
pipinto the user site packages directory rather than globally for the current Python installation (this option is not permitted inside an active virtual environment).
By default, the scripts
pipX.Y will be installed (where
X.Y stands for the version of Python used to invoke
scripts installed can be controlled through two additional command line
--altinstall: if an alternate installation is requested, the
pipXscript will not be installed.
--default-pip: if a “default pip” installation is requested, the
pipscript will be installed in addition to the two regular scripts.
Providing both of the script selection options will trigger an exception.
ensurepip exposes two functions for programmatic use:
Returns a string specifying the available version of pip that will be installed when bootstrapping an environment.
- ensurepip.bootstrap(root=None, upgrade=False, user=False, altinstall=False, default_pip=False, verbosity=0)¶
pipinto the current or designated environment.
root specifies an alternative root directory to install relative to. If root is
None, then installation uses the default install location for the current environment.
upgrade indicates whether or not to upgrade an existing installation of an earlier version of
pipto the available version.
user indicates whether to use the user scheme rather than installing globally.
By default, the scripts
pipX.Ywill be installed (where X.Y stands for the current version of Python).
If altinstall is set, then
pipXwill not be installed.
If default_pip is set, then
pipwill be installed in addition to the two regular scripts.
Setting both altinstall and default_pip will trigger
verbosity controls the level of output to
sys.stdoutfrom the bootstrapping operation.
Raises an auditing event
The bootstrapping process has side effects on both
os.environ. Invoking the command line interface in a subprocess instead allows these side effects to be avoided.
The bootstrapping process may install additional modules required by
pip, but other software should not assume those dependencies will always be present by default (as the dependencies may be removed in a future version of