pip install¶

用法¶

Unix/macOS

python -m pip install [options] <requirement specifier> [package-index-options] ...
python -m pip install [options] -r <requirements file> [package-index-options] ...
python -m pip install [options] [-e] <vcs project url> ...
python -m pip install [options] [-e] <local project path> ...
python -m pip install [options] <archive url/path> ...

Windows

py -m pip install [options] <requirement specifier> [package-index-options] ...
py -m pip install [options] -r <requirements file> [package-index-options] ...
py -m pip install [options] [-e] <vcs project url> ...
py -m pip install [options] [-e] <local project path> ...
py -m pip install [options] <archive url/path> ...

描述¶

从以下位置安装包

使用需求规范从 PyPI（和其他索引）安装。
VCS 项目 URL。
本地项目目录。
本地或远程源代码存档。

pip 还支持从“需求文件”安装，这提供了一种简单的方法来指定要安装的整个环境。

概述¶

pip install 具有以下几个阶段

识别基本需求。用户提供的参数在此处进行处理。
解析依赖关系。在此处确定将要安装的内容。
构建轮子。所有可以构建的依赖项都将构建成轮子。
安装包（并卸载任何正在升级/替换的包）。

请注意，pip install 倾向于保留已安装的版本，除非指定了 --upgrade。

参数处理¶

在查看要安装的项目时，pip 按以下顺序检查每个项目是什么类型

项目或存档 URL。
本地目录（必须包含 pyproject.toml 或 setup.py，否则 pip 会报告错误）。
本地文件（一个 sdist 或 wheel 格式存档，遵循这些格式的命名约定）。
一个版本规范。

识别出的每个项目都将添加到安装要满足的需求集中。

确定名称和版本¶

对于每个候选项目，pip 需要知道项目名称和版本。对于轮子（由 .whl 文件扩展名标识），这可以从文件名中获取，根据轮子规范。对于本地目录或显式指定的 sdist 文件，setup.py egg_info 命令用于确定项目元数据。对于通过索引找到的 sdist，解析文件名以获取名称和项目版本（理论上这比使用 egg_info 命令稍微不可靠，但避免下载和处理不必要的数量的文件）。

任何 URL 都可以使用 #egg=name 语法（请参阅 VCS 支持）来明确声明项目名称。

满足需求¶

一旦 pip 拥有要满足的需求集，它就会使用以下简单规则选择要安装的每个需求的版本：将安装满足给定约束的最新版本（但请参阅此处关于预发布版本的例外）。如果选择的版本存在多个源，则假设任何源都是可以接受的（否则版本将不同）。

获取有关已安装内容的信息¶

install 命令有一个 --report 选项，该选项将生成已安装内容的 JSON 报告。结合 --dry-run 和 --ignore-installed，它可以用来 *解析* 一组需求，而无需实际安装它们。

该报告可以写入文件，也可以写入标准输出（使用 --report - 结合 --quiet）。

JSON 报告的格式在安装报告中描述。

安装顺序¶

注意

本节仅与运行时依赖项的安装顺序有关，不适用于构建依赖项（这些依赖项使用 [build-system] 表指定）。

从 v6.1.0 开始，pip 在安装其依赖项之前安装依赖项，即以“拓扑顺序”安装。这是 pip 目前做出的与顺序相关的唯一承诺。虽然 pip 可能碰巧按安装参数顺序或需求文件中的项目顺序安装，但这并非承诺。

在遇到依赖循环（又称“循环依赖”）的情况下，当前实现（可能在以后会更改）会安装循环中首先遇到的成员，最后安装。

例如，如果 quux 依赖于 foo，foo 依赖于 bar，bar 依赖于 baz，而 baz 依赖于 foo

Unix/macOS

$ python -m pip install quux
...
Installing collected packages baz, bar, foo, quux

$ python -m pip install bar
...
Installing collected packages foo, baz, bar

Windows

C:\> py -m pip install quux
...
Installing collected packages baz, bar, foo, quux

C:\> py -m pip install bar
...
Installing collected packages foo, baz, bar

在 v6.1.0 之前，pip 不会对安装顺序做出任何承诺。

决定以拓扑方式安装基于以下原则：安装应以在每个步骤都使环境可用的方式进行。这有两个主要实际好处

在安装过程中并发使用环境更有可能正常工作。
安装失败不太可能导致环境崩溃。尽管 pip 希望最终能够支持失败回滚，但目前这是一个改进。

虽然新的安装顺序并不打算取代（也不会取代）使用 setup_requires 来声明构建依赖项，但它可能有助于某些项目从 sdist 安装（以前可能失败），这些项目符合以下特征

它们具有使用 install_requires 声明为安装依赖项的构建依赖项。
python setup.py egg_info 在没有安装其构建依赖项的情况下工作。
无论出于何种原因，它们都不会或不会使用 setup_requires 声明其构建依赖项。

需求文件格式

本节已移至需求文件格式。

需求规范

本节已移至需求规范。

每个需求的覆盖

现在在需求文件格式中介绍。

预发布版本¶

从 v1.4 开始，pip 默认情况下只安装预发布指定的稳定版本。如果无法将版本解析为兼容版本，则假设它是一个预发布版本。

如果需求规范包含预发布或开发版本（例如 >=0.0.dev0），那么 pip 将允许该需求的预发布和开发版本。这并不包括 != 标志。

pip install 命令还支持 --pre 标志，该标志启用预发布和开发版本的安装。

VCS 支持

现在在 VCS 支持中介绍。

查找包¶

pip 使用 PyPI 上的 HTTP 简单接口搜索包，该接口在此处和此处有记录。

pip 提供了许多包索引选项，用于修改查找包的方式。

pip 在多个位置查找软件包：PyPI（或作为 --index-url 给出的索引，如果未通过 --no-index 禁用），本地文件系统以及通过 --find-links 或 --extra-index-url 指定的任何其他存储库。搜索位置没有优先级。而是检查所有位置，并选择与要求“最匹配”的版本（在版本号方面 - 有关详细信息，请参见规范）。

请参见 pip install 示例。

SSL 证书验证

此内容现已在 HTTPS 证书中介绍。

缓存

此内容现已在缓存中介绍。

Wheel 缓存

此内容现已在缓存中介绍。

哈希检查模式

此内容现已在安全安装中介绍。

本地项目安装

此内容现已在本地项目安装中介绍。

可编辑安装

此内容现已在本地项目安装中介绍。

构建系统接口

此内容现已在构建系统接口中介绍。

选项¶

-r, --requirement <file>¶

从给定的需求文件安装。此选项可以使用多次。

(环境变量：PIP_REQUIREMENT)

-c, --constraint <file>¶

使用给定的约束文件限制版本。此选项可以使用多次。

(环境变量：PIP_CONSTRAINT)

--no-deps¶

不要安装软件包依赖项。

(环境变量：PIP_NO_DEPS，PIP_NO_DEPENDENCIES)

--pre¶

包含预发布和开发版本。默认情况下，pip 只找到稳定版本。

(环境变量：PIP_PRE)

-e, --editable <path/url>¶

以可编辑模式（即 setuptools 的“开发模式”）从本地项目路径或 VCS URL 安装项目。

(环境变量：PIP_EDITABLE)

--dry-run¶

实际上不安装任何内容，只打印将要安装的内容。可以与 --ignore-installed 结合使用来“解析”需求。

(环境变量：PIP_DRY_RUN)

-t, --target <dir>¶

将软件包安装到 <dir> 中。默认情况下，这不会替换 <dir> 中的现有文件/文件夹。使用 --upgrade 替换 <dir> 中的现有软件包的新版本。

(环境变量：PIP_TARGET)

--platform <platform>¶

只使用与 <platform> 兼容的 wheels。默认设置为运行系统的平台。多次使用此选项以指定目标解释器支持的多个平台。

(环境变量：PIP_PLATFORM)

--python-version <python_version>¶

用于 wheel 和“Requires-Python”兼容性检查的 Python 解释器版本。默认设置为从运行的解释器派生的版本。版本可以使用最多三个用点分隔的整数指定（例如，“3”表示 3.0.0，“3.7”表示 3.7.0 或“3.7.3”）。也可以将主版本和次版本作为没有点的字符串给出（例如，“37”表示 3.7.0）。

(环境变量：PIP_PYTHON_VERSION)

--implementation <implementation>¶

只使用与 Python 实现 <implementation> 兼容的 wheels，例如 'pp'、'jy'、'cp' 或 'ip'。如果未指定，则使用当前解释器实现。使用 'py' 强制使用与实现无关的 wheels。

(环境变量：PIP_IMPLEMENTATION)

--abi <abi>¶

只使用与 Python abi <abi> 兼容的 wheels，例如 'pypy_41'。如果未指定，则使用当前解释器 abi 标签。多次使用此选项以指定目标解释器支持的多个 abi。通常，在使用此选项时，需要指定 --implementation、--platform 和 --python-version。

(环境变量：PIP_ABI)

--user¶

安装到平台的 Python 用户安装目录。通常为 ~/.local/，或 Windows 上的 %APPDATA%Python。（有关详细信息，请参见 Python 文档中有关 site.USER_BASE 的内容。）

(环境变量：PIP_USER)

--root <dir>¶

将所有内容相对于此备用根目录安装。

(环境变量：PIP_ROOT)

--prefix <dir>¶

安装 lib、bin 和其他顶级文件夹所在的安装前缀。请注意，生成的安装可能包含引用 pip 的 Python 解释器（而不是 --prefix 的 Python 解释器）的脚本和其他资源。如果要将软件包安装到另一个（可能是无 pip 的）环境中，请参阅 --python 选项。

(环境变量：PIP_PREFIX)

--src <dir>¶

用于签出可编辑项目的目录。虚拟环境中的默认目录为“<venv path>/src”。全局安装的默认目录为“<current dir>/src”。

(环境变量：PIP_SRC，PIP_SOURCE，PIP_SOURCE_DIR，PIP_SOURCE_DIRECTORY)

-U, --upgrade¶

将所有指定的软件包升级到最新版本。依赖项的处理方式取决于使用的升级策略。

(环境变量：PIP_UPGRADE)

--upgrade-strategy <upgrade_strategy>¶

确定如何处理依赖项升级 [默认：only-if-needed]。“eager” - 无论当前安装的版本是否满足升级的软件包的要求，都会升级依赖项。“only-if-needed” - 仅当依赖项不满足升级的软件包的要求时才升级。

(环境变量：PIP_UPGRADE_STRATEGY)

--force-reinstall¶

重新安装所有软件包，即使它们已经是最新版本。

(环境变量：PIP_FORCE_REINSTALL)

-I, --ignore-installed¶

忽略已安装的软件包，覆盖它们。如果现有软件包版本不同或使用不同的软件包管理器安装，这可能会破坏您的系统！

(环境变量：PIP_IGNORE_INSTALLED)

--ignore-requires-python¶

忽略 Requires-Python 信息。

(环境变量：PIP_IGNORE_REQUIRES_PYTHON)

--no-build-isolation¶

在构建现代源代码发行版时禁用隔离。如果使用此选项，则必须已安装 PEP 518 指定的构建依赖项。

(环境变量: PIP_NO_BUILD_ISOLATION)

--use-pep517¶

使用 PEP 517 构建源代码分发包（使用 --no-use-pep517 强制使用旧式行为）。

(环境变量: PIP_USE_PEP517)

--check-build-dependencies¶

在使用 PEP517 时检查构建依赖项。

(环境变量: PIP_CHECK_BUILD_DEPENDENCIES)

--break-system-packages¶

允许 pip 修改外部管理的 Python 安装。

(环境变量: PIP_BREAK_SYSTEM_PACKAGES)

-C, --config-settings <settings>¶

要传递给 PEP 517 构建后端的配置设置。设置采用 KEY=VALUE 的形式。使用多个 --config-settings 选项将多个键传递给后端。

(环境变量: PIP_CONFIG_SETTINGS)

--global-option <options>¶

要在安装或 bdist_wheel 命令之前提供给 setup.py 调用的额外全局选项。

(环境变量: PIP_GLOBAL_OPTION)

--compile¶

将 Python 源代码文件编译为字节码。

(环境变量: PIP_COMPILE)

--no-compile¶

不要将 Python 源代码文件编译为字节码。

(环境变量: PIP_NO_COMPILE)

--no-warn-script-location¶

在将脚本安装到 PATH 之外时不要发出警告。

(环境变量: PIP_NO_WARN_SCRIPT_LOCATION)

--no-warn-conflicts¶

不要警告有关损坏的依赖项。

(环境变量: PIP_NO_WARN_CONFLICTS)

--no-binary <format_control>¶

不要使用二进制软件包。可以多次提供，每次都会添加到现有值中。接受“：all：”以禁用所有二进制软件包，“：none：”以清空集合（注意冒号），或用逗号分隔的一个或多个软件包名称（没有冒号）。请注意，某些软件包很难编译，并且在对这些软件包使用此选项时可能无法安装。

(环境变量: PIP_NO_BINARY)

--only-binary <format_control>¶

不要使用源代码软件包。可以多次提供，每次都会添加到现有值中。接受“：all：”以禁用所有源代码软件包，“：none：”以清空集合，或用逗号分隔的一个或多个软件包名称。在对这些软件包使用此选项时，没有二进制分发的软件包将无法安装。

(环境变量: PIP_ONLY_BINARY)

--prefer-binary¶

优先使用二进制软件包而不是源代码软件包，即使源代码软件包更新。

(环境变量: PIP_PREFER_BINARY)

--require-hashes¶

要求使用哈希值来检查每个需求，以实现可重复安装。如果需求文件中任何软件包都有 --hash 选项，则会隐式使用此选项。

(环境变量: PIP_REQUIRE_HASHES)

--progress-bar <progress_bar>¶

指定是否应使用进度条 [on, off, raw]（默认：on）

(环境变量: PIP_PROGRESS_BAR)

--root-user-action <root_user_action>¶

如果 pip 作为 root 用户运行，则采取的操作 [warn, ignore]（默认：warn）

(环境变量: PIP_ROOT_USER_ACTION)

--report <file>¶

生成一个 JSON 文件，描述 pip 为安装提供的需求所做的事情。可以与 --dry-run 和 --ignore-installed 结合使用以“解析”需求。当使用 - 作为文件名时，它会写入 stdout。当写入 stdout 时，请与 --quiet 选项结合使用，以避免将 pip 日志输出与 JSON 输出混合。

(环境变量: PIP_REPORT)

--no-clean¶

不要清理构建目录。

(环境变量: PIP_NO_CLEAN)

-i, --index-url <url>¶

Python 软件包索引的基 URL（默认 https://pypi.ac.cn/simple）。这应该指向一个符合 PEP 503（简单存储库 API）的存储库或以相同格式布局的本地目录。

(环境变量: PIP_INDEX_URL, PIP_PYPI_URL)

--extra-index-url <url>¶

要除了 --index-url 之外使用的软件包索引的额外 URL。应遵循与 --index-url 相同的规则。

(环境变量: PIP_EXTRA_INDEX_URL)

--no-index¶

忽略软件包索引（只查找 --find-links URL）。

(环境变量: PIP_NO_INDEX)

-f, --find-links <url>¶

如果为 URL 或指向 html 文件的路径，则解析到存档的链接，例如 sdist (.tar.gz) 或 wheel (.whl) 文件。如果为本地路径或 file:// URL，即目录，则在目录列表中查找存档。不支持指向 VCS 项目 URL 的链接。

(环境变量: PIP_FIND_LINKS)

pip install¶

用法¶

描述¶

概述¶

参数处理¶

确定名称和版本¶

满足需求¶

获取有关已安装内容的信息¶

安装顺序¶

预发布版本¶

查找包¶

选项¶

示例¶