ensurepip — 引导 pip 安装程序

3.4 版本新增。

源代码: Lib/ensurepip

ensurepip 包提供了对将 pip 安装程序引导到现有 Python 安装或虚拟环境中的支持。这种引导方法反映了一个事实，即 pip 是一个具有自己发布周期的独立项目，并且最新的可用稳定版本与 CPython 参考解释器的维护和功能版本捆绑在一起。

在大多数情况下，Python 的最终用户不需要直接调用此模块（因为 pip 应该默认引导），但是如果在安装 Python（或创建虚拟环境时）跳过了 pip 的安装，或者在显式卸载 pip 后，可能需要调用此模块。

注解

此模块不访问互联网。引导 pip 所需的所有组件都作为包的内部部分包含在内。

参见

安装 Python 模块

安装 Python 包的最终用户指南

PEP 453：Python 安装中 pip 的显式引导

该模块的原始原理和规范。

可用性: 不支持 Android、iOS、WASI。

此模块不支持 移动平台 或 WebAssembly 平台。

命令行界面

命令行界面使用解释器的 -m 开关调用。

最简单的调用方式是

python -m ensurepip

如果尚未安装，此调用将安装 pip，否则不执行任何操作。要确保安装的 pip 版本至少与 ensurepip 中可用的版本一样新，请传递 --upgrade 选项

python -m ensurepip --upgrade

默认情况下，pip 安装到当前虚拟环境中（如果有一个处于活动状态），或者安装到系统站点包中（如果没有活动虚拟环境）。可以通过两个附加的命令行选项来控制安装位置

  • --root dir: 相对于给定的根目录而不是当前活动虚拟环境的根目录（如果有）或当前 Python 安装的默认根目录安装 pip。

  • --user: 将 pip 安装到用户站点包目录中，而不是当前 Python 安装的全局目录中（此选项在活动虚拟环境内部不允许使用）。

默认情况下，将安装脚本 pipX 和 pipX.Y （其中 X.Y 代表用于调用 ensurepip 的 Python 版本）。可以通过两个附加的命令行选项来控制安装的脚本

  • --altinstall: 如果请求备用安装，则将不安装 pipX 脚本。

  • --default-pip: 如果请求“默认 pip”安装，则除了两个常规脚本外，还将安装 pip 脚本。

提供这两个脚本选择选项将触发异常。

模块 API

ensurepip 公开了两个用于编程的函数

ensurepip.version()

返回一个字符串，指定在引导环境时将安装的 pip 的可用版本。

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

将 pip 引导到当前或指定的环境中。

root 指定一个相对于其安装的备用根目录。如果 root 为 None，则安装使用当前环境的默认安装位置。

upgrade 指示是否将现有较早版本的 pip 升级到可用版本。

user 指示是使用用户方案而不是全局安装。

默认情况下，将安装脚本 pipX 和 pipX.Y （其中 X.Y 代表当前的 Python 版本）。

如果设置了 altinstall，则将不安装 pipX。

如果设置了 default_pip，则除了两个常规脚本外，还将安装 pip。

同时设置 altinstall 和 default_pip 将触发 ValueError。

verbosity 控制引导操作中输出到 sys.stdout 的级别。

使用参数 root 引发 审计事件 ensurepip.bootstrap。

注解

引导过程对 sys.path 和 os.environ 都有副作用。在子进程中调用命令行界面可以避免这些副作用。

注解

引导过程可能会安装 pip 所需的其他模块，但其他软件不应假定这些依赖项将始终默认存在（因为这些依赖项可能会在未来的 pip 版本中删除）。