ensurepip —- Bootstrapping the pip installer

3.4 新版功能.

The ensurepip package provides support for bootstrapping the pipinstaller into an existing Python installation or virtual environment. Thisbootstrapping approach reflects the fact that pip 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 (as pip should be bootstrapped by default), but it may beneeded if installing pip was skipped when installing Python (orwhen creating a virtual environment) or after explicitly uninstallingpip.

注解

This module does not access the internet. All of the componentsneeded to bootstrap pip are included as internal parts of thepackage.

参见

  • 安装 Python 模块

  • 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.

Command line interface

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

The simplest possible invocation is:

  1. python -m ensurepip

This invocation will install pip if it is not already installed,but otherwise does nothing. To ensure the installed version of pipis at least as recent as the one bundled with ensurepip, pass the—upgrade option:

  1. python -m ensurepip --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>: Installs pip relative to the given root directoryrather than the root of the currently active virtual environment (if any)or the default root for the current Python installation.

  • —user: Installs pip into the user site packages directory ratherthan globally for the current Python installation (this option is notpermitted inside an active virtual environment).

By default, the scripts pipX and pipX.Y will be installed (whereX.Y stands for the version of Python used to invoke ensurepip). Thescripts installed can be controlled through two additional command lineoptions:

  • —altinstall: if an alternate installation is requested, the pipXscript will not be installed.

    • —default-pip: if a "default pip" installation is requested, the
    • pip script will be installed 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 bundled 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)

  • Bootstraps pip into 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 locationfor the current environment.

upgrade indicates whether or not to upgrade an existing installationof an earlier version of pip to the bundled version.

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

By default, the scripts pipX and pipX.Y will be installed (whereX.Y stands for the current version of Python).

If altinstall is set, then pipX will not be installed.

If default_pip is set, then pip will be installed in addition tothe two regular scripts.

Setting both altinstall and default_pip will triggerValueError.

verbosity controls the level of output to sys.stdout from thebootstrapping operation.

Raises an auditing event ensurepip.bootstrap with argument root.

注解

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

注解

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 of pip).