ensurepip — Bootstrapping thepip installer

Added in version 3.4.

Source code:Lib/ensurepip

Theensurepip package provides support for bootstrapping thepipinstaller into an existing Python installation or virtual environment. Thisbootstrapping approach reflects the fact thatpip is an independentproject with its own release cycle, and the latest available stable versionis bundled with maintenance and feature releases of the CPython referenceinterpreter.

In most cases, end users of Python shouldn’t need to invoke this moduledirectly (aspip should be bootstrapped by default), but it may beneeded if installingpip was skipped when installing Python (orwhen creating a virtual environment) or after explicitly uninstallingpip.

Note

This moduledoes not access the internet. All of the componentsneeded to bootstrappip are included as internal parts of thepackage.

This is anoptional module.If it is missing from your copy of CPython,look for documentation from your distributor (that is,whoever provided Python to you).If you are the distributor, seeRequirements for optional modules.

See also

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 Android, not iOS, not WASI.

This module is not supported onmobile platformsorWebAssembly platforms.

Command-line interface

The command line interface is invoked using the interpreter’s-m switch.

The simplest possible invocation is:

python-mensurepip

This invocation will installpip if it is not already installed,but otherwise does nothing. To ensure the installed version ofpipis at least as recent as the one available inensurepip, pass the--upgrade option:

python-mensurepip--upgrade

By default,pip is installed into the current virtual environment(if one is active) or into the system site packages (if there is noactive virtual environment). The installation location can be controlledthrough two additional command line options:

--root<dir>

Installspip relative to the given root directory rather than the rootof the currently active virtual environment (if any) or the default rootfor the current Python installation.

--user

Installspip into the user site packages directory rather than globallyfor the current Python installation (this option is not permitted inside anactive virtual environment).

By default, the scriptspipX andpipX.Y will be installed (whereX.Y stands for the version of Python used to invokeensurepip). Thescripts installed can be controlled through two additional command lineoptions:

--altinstall

If an alternate installation is requested, thepipX script willnot beinstalled.

--default-pip

If a “default pip” installation is requested, thepip script will beinstalled in addition to the two regular scripts.

Providing both of the script selection options will trigger an exception.

Module API

ensurepip exposes two functions for programmatic use:

ensurepip.version()

Returns a string specifying the available version of pip that will beinstalled when bootstrapping an environment.

ensurepip.bootstrap(root=None,upgrade=False,user=False,altinstall=False,default_pip=False,verbosity=0)

Bootstrapspip into the current or designated environment.

root specifies an alternative root directory to install relative to.Ifroot isNone, then installation uses the default install locationfor the current environment.

upgrade indicates whether or not to upgrade an existing installationof an earlier version ofpip to the available version.

user indicates whether to use the user scheme rather than installingglobally.

By default, the scriptspipX andpipX.Y will be installed (whereX.Y stands for the current version of Python).

Ifaltinstall is set, thenpipX willnot be installed.

Ifdefault_pip is set, thenpip will be installed in addition tothe two regular scripts.

Setting bothaltinstall anddefault_pip will triggerValueError.

verbosity controls the level of output tosys.stdout from thebootstrapping operation.

Raises anauditing eventensurepip.bootstrap with argumentroot.

Note

The bootstrapping process has side effects on bothsys.path andos.environ. Invoking the command line interface in a subprocessinstead allows these side effects to be avoided.

Note

The bootstrapping process may install additional modules required bypip, but other software should not assume those dependencies willalways be present by default (as the dependencies may be removed in afuture version ofpip).