用户指南¶

运行 pip¶

pip 是一个命令行程序。当你安装 pip 时，一个 pip 命令被添加到你的系统中，可以在命令提示符下运行，如下：

Unix/macOS

python -m pip <pip arguments>

python -m pip 使用你指定的 Python 解释器执行 pip。所以 /usr/bin/python3.7 -m pip 意味着你正在为位于 /usr/bin/python3.7 的解释器执行 pip。

Windows

py -m pip <pip arguments>

py -m pip 使用你所安装的最新 Python 解释器执行 pip。更多细节，请阅读 Python Windows launcher 文档。

安装包¶

pip 支持从 PyPI 、版本控制、本地项目以及直接从发行文件中安装。

最常见的情况是使用 Requirement Specifiers 从 PyPI 安装

Unix/macOS

python -m pip install SomePackage            # latest version
python -m pip install SomePackage==1.0.4     # specific version
python -m pip install 'SomePackage>=1.0.4'     # minimum version

Windows

py -m pip install SomePackage            # latest version
py -m pip install SomePackage==1.0.4     # specific version
py -m pip install 'SomePackage>=1.0.4'   # minimum version

更多信息和例子，请参见 pip install 参考。

基本认证凭证¶

这一点现在已经在认证中涵盖。

netrc 支持¶

这一点现在已经在认证中涵盖。

Keyring 支持¶

这一点现在已经在认证中涵盖。

使用代理服务器¶

当从 PyPI 安装软件包时，pip 需要互联网接入，在许多企业环境中，这需要一个出站的 HTTP 代理服务器。

pip 可以通过各种方式配置为通过代理服务器连接：

使用 --proxy 命令行选项，以 [user:passwd@]proxy.server:port 的形式指定一个代理。
在配置文件中使用 proxy。
通过设置标准环境变量 http_proxy, https_proxy 和 no_proxy。
使用环境变量 PIP_USER_AGENT_USER_DATA，在 pip 的请求中使用的 user-agent 变量中包含一个 JSON 编码的字符串。

需求文件¶

“需求文件”是包含使用 pip install 来安装的项目列表的文件，像这样：

Unix/macOS

python -m pip install -r requirements.txt

Windows

py -m pip install -r requirements.txt

关于文件格式的细节在这里： Requirements File Format。

从逻辑上讲，需求文件只是一个放在文件中的 pip install 参数的列表。注意，你不应该依赖文件中的项目以任何特定的顺序被 pip 安装。

实践中，有 4 种常见的需求文件的用途。”

需求文件被用来保存来自 pip freeze 的结果，以实现 Repeatable Installs。在这种情况下，你的需求文件包含了运行 pip freeze 时安装的所有东西的钉子版本。
Unix/macOS
python -m pip freeze > requirements.txt python -m pip install -r requirements.txt
Windows
py -m pip freeze > requirements.txt py -m pip install -r requirements.txt
需求文件是用来强制 pip 正确解决依赖关系的。pip 20.2 和更早的版本没有真正的依赖关系解决，而是简单地使用它为一个项目找到的第一个规范。例如，如果 pkg1 需要 pkg3>=1.0 ，pkg2 需要 pkg3>=1.0,<=2.0 ，如果 pkg1 先被解决，pip 将只使用 pkg3>=1.0 ，并且很容易导致安装 pkg3 的版本与 pkg2 的需求冲突。为了解决这个问题，你可以将 pkg3>=1.0,<=2.0 （即正确的规格）与其他顶级需求一起直接放入你的需求文件。像这样
```
pkg1
pkg2
pkg3>=1.0,<=2.0
```
需求文件是用来强制 pip 安装子依赖的另一个版本的。例如，假设你的需求文件中的 “ProjectA” 需要 “ProjectB”，但最新版本（v1.3）有一个错误，你可以强制pip接受较早的版本，像这样
```
ProjectA
ProjectB<1.3
```
需求文件是用来覆盖依赖性的，它是一个存在于版本控制中的本地补丁。例如，假设一个来自 PyPI 的依赖 SomeDependency 有一个错误，而你不能等待上游的修复。你可以克隆/复制 src，进行修复，并以 sometag 为标签放在 VCS 中。你可以在你的需求文件中引用它，比如说
```
git+https://myvcs.com/some_dependency@sometag#egg=SomeDependency
```
如果 SomeDependency 之前是你需求文件中的顶级需求，那么用新的一行替换该行。如果 SomeDependency 是一个子需求，那么增加新的一行。

必须明确，pip 是通过 install_requires metadata 来确定软件包的依赖性，而不是通过发现嵌入项目中的 requirements.txt 文件。

另见：

约束文件¶

约束文件是需求文件，只控制需求的哪个版本被安装，而不是它是否被安装。它们的语法和内容是需求文件的一个子集，有几种语法是不允许的：约束必须有一个名字，它们不能被编辑，也不能指定额外的东西。在语义方面，有一个关键的区别。在约束文件中包括一个包并不触发包的安装”

像这样使用一个约束文件：

Unix/macOS

python -m pip install -c constraints.txt

Windows

py -m pip install -c constraints.txt

当你不知道你要安装什么东西时，约束文件的使用原因与需求文件完全相同。例如，假设 “helloworld” 包在你的环境中不工作，所以你有一个本地的补丁版本。你安装的一些东西依赖 “helloworld”，而一些则不依赖。

确保统一使用补丁版本的一个方法是，手动审核你安装的所有东西的依赖关系，如果存在 “helloworld”，就写一个需求文件，在安装那个东西时使用。

约束文件提供了一个更好的方法：为你的组织写一个单一的约束文件，然后到处使用。如果被安装的东西需要安装 “helloworld”，你在约束文件中指定的固定版本将被使用。

约束文件的支持是在 pip 7.1 中添加的。在对 20.3 (2020) 中 pip 依赖关系解析器的修改中，我们做了一次相当全面的整改，从以前的实现中删除了一些没有记录的和不支持的怪癖，并将约束文件剥离出来，使其成为一种纯粹的为包指定全局（版本）限制的方式。

从轮子开始安装¶

“Wheel” 是一种构建的档案格式，与从源档案构建和安装相比，可以大大加快安装速度。更多信息，请参见 Wheel 文档、PEP 427 和 PEP 425。

pip 更喜欢有轮子的。要禁用这一点，请使用 --no-binary 标志，用于 pip install。

如果没有找到满意的轮子，pip 将默认为寻找源档案。

要直接从轮子档案中安装：

Unix/macOS

python -m pip install SomePackage-1.0-py2.py3-none-any.whl

Windows

py -m pip install SomePackage-1.0-py2.py3-none-any.whl

要在轮子中包括 provides_extras 元数据中提供的可选依赖，你必须在安装目标名称周围加上引号：

Unix/macOS

python -m pip install './somepackage-1.0-py2.py3-none-any.whl[my-extras]'

Windows

py -m pip install './somepackage-1.0-py2.py3-none-any.whl[my-extras]'

注解

在未来，path[extras] 的语法可能会被废弃。建议尽可能使用 PEP 508 的语法。

对于没有轮子的情况，pip 提供了 pip wheel 作为一种便利，为你的所有需求和依赖建立轮子。

pip wheel 需要安装 wheel package，它提供了其所使用的 “bdist_wheel” setuptools 扩展。

为你的需求和所有的依赖性建立轮子到本地目录：

Unix/macOS

python -m pip install wheel
python -m pip wheel --wheel-dir=/local/wheels -r requirements.txt

Windows

py -m pip install wheel
py -m pip wheel --wheel-dir=/local/wheels -r requirements.txt

然后使用你本地的轮子目录（而不是从 PyPI）来安装这些需求：

Unix/macOS

python -m pip install --no-index --find-links=/local/wheels -r requirements.txt

Windows

py -m pip install --no-index --find-links=/local/wheels -r requirements.txt

卸载包¶

pip 能够像这样卸载大多数软件包：

Unix/macOS

python -m pip uninstall SomePackage

Windows

py -m pip uninstall SomePackage

在升级到较新的版本之前，pip 也会对旧版本的软件包进行自动卸载。

更多信息和例子，请参见 pip uninstall 参考。

包的列表¶

要列出已安装的软件包：

Unix/macOS

$ python -m pip list
docutils (0.9.1)
Jinja2 (2.6)
Pygments (1.5)
Sphinx (1.1.2)

Windows

C:\> py -m pip list
docutils (0.9.1)
Jinja2 (2.6)
Pygments (1.5)
Sphinx (1.1.2)

列出过时的软件包，并显示可用的最新版本：

Unix/macOS

$ python -m pip list --outdated
docutils (Current: 0.9.1 Latest: 0.10)
Sphinx (Current: 1.1.2 Latest: 1.1.3)

Windows

C:\> py -m pip list --outdated
docutils (Current: 0.9.1 Latest: 0.10)
Sphinx (Current: 1.1.2 Latest: 1.1.3)

要显示一个已安装软件包的细节：

Unix/macOS

$ python -m pip show sphinx
---
Name: Sphinx
Version: 1.1.3
Location: /my/env/lib/pythonx.x/site-packages
Requires: Pygments, Jinja2, docutils

Windows

C:\> py -m pip show sphinx
---
Name: Sphinx
Version: 1.1.3
Location: /my/env/lib/pythonx.x/site-packages
Requires: Pygments, Jinja2, docutils

更多信息和例子，请参见 pip list 和 pip show 参考页。

搜索包¶

pip 可以使用 pip search 命令来搜索 PyPI 的软件包。

Unix/macOS

python -m pip search "query"

Windows

py -m pip search "query"

该查询将被用来搜索所有软件包的名称和摘要。

更多信息和例子，请参见 pip search 参考。

配置¶

这一点现在在配置中涉及。

配置文件¶

这一点现在在配置中涉及。

环境变量¶

这一点现在在配置中涉及。

配置优先级¶

这一点现在在配置中涉及。

命令补全¶

pip 支持 bash、zsh 和 fish 的命令行补全。

为 bash 设置:

python -m pip completion --bash >> ~/.profile

为 zsh 设置:

python -m pip completion --zsh >> ~/.zprofile

为 fish 设置:

python -m pip completion --fish > ~/.config/fish/completions/pip.fish

另外，你可以直接用 shell 的 eval 函数来使用 completion 命令的结果，例如，在你的启动文件中添加以下内容

eval "`pip completion --bash`"

从本地软件包安装¶

在某些情况下，你可能只想从本地软件包中进行安装，而不需要访问 PyPI。

首先，下载满足你需求的档案：

Unix/macOS

python -m pip download --destination-directory DIR -r requirements.txt

Windows

py -m pip download --destination-directory DIR -r requirements.txt

注意，pip download 会先查看你的轮子缓存，然后再尝试从 PyPI 下载。如果你以前从未安装过你的需求，你就不会有这些项目的轮子缓存。在这种情况下，如果你的一些需求不是以轮子的形式从 PyPI 下载的，而你想要轮子，那么就运行这个：

Unix/macOS

python -m pip wheel --wheel-dir DIR -r requirements.txt

Windows

py -m pip wheel --wheel-dir DIR -r requirements.txt

然后，要从本地安装，你将使用 --find-links 和 --no-index 像这样：

Unix/macOS

python -m pip install --no-index --find-links=DIR -r requirements.txt

Windows

py -m pip install --no-index --find-links=DIR -r requirements.txt

“只有在需要时”才递归升级¶

pip install --upgrade 现在有一个 --upgrade-strategy 选项，控制 pip 处理升级依赖关系的方式。有两种升级策略支持：

eager：升级所有的依赖关系，不管它们是否仍然满足新的父需求
only-if-needed：只有在不满足新的父系要求的情况下才升级一个依赖关系

默认的策略是 only-if-needed。由于在升级冲突的依赖关系时，eager 的破坏性，这在 pip 10.0 中被改变了。

需要注意的是，--upgrade 影响的是 直接需求 （例如那些在命令行或通过需求文件指定的需求），而 --upgrade-strategy 影响的是 间接需求 （直接需求的依赖关系）。

举个例子，比如说 SomePackage 有一个依赖项 SomeDependency，它们都已经安装，但不是最新的可用版本：

pip install SomePackage：将不会升级现有的 SomePackage 或 SomeDependency。
pip install --upgrade SomePackage：将升级 SomePackage，但不升级 SomeDependency （除非没有满足最低要求）”
pip install --upgrade SomePackage --upgrade-strategy=eager：同时升级 SomePackage 和 SomeDependency。

作为一个历史性的说明，早期的一个获得 only-if-needed 的行为的 “fix” 是：

Unix/macOS

python -m pip install --upgrade --no-deps SomePackage
python -m pip install SomePackage

Windows

py -m pip install --upgrade --no-deps SomePackage
py -m pip install SomePackage

正在考虑一项关于 upgrade-all 命令的建议，作为对 eager 升级行为的更安全的替代。

确保可重复性¶

这一点现在在 Repeatable Installs 中已经涵盖。

修复冲突的依赖关系¶

这一点现在在 Dependency Resolution 中已经涵盖。

从你的程序中使用 pip¶

如前所述，pip 是一个命令行程序。虽然它是在 Python 中实现的，因此可以通过 import pip 从你的 Python 代码中获得，但你不能以这种方式使用 pip 的内部 API。这有很多原因：

pip 代码假设是唯一控制程序的全局状态。pip 管理诸如日志系统配置，或标准 IO 流的值，而不考虑用户代码可能受到影响的可能性。
pip 的代码不是线程安全的。如果你在一个线程中运行 pip，不能保证你的代码和 pip 的代码都能按你的期望工作。
pip假设一旦它完成了它的工作，进程就会终止。它不需要处理其他代码在那之后继续运行的可能性，所以（例如）在同一个进程中调用两次 pip 很可能会有问题。

这并不意味着 pip 的开发者原则上反对将 pip 作为一个库来使用的想法--只是它不是这样写的，要重新设计作为库使用的内部结构，处理上述所有问题，并设计一个可用的、强大的、稳定的 API，我们可以保证在 pip 的多个版本中保持可用，这将是一项大量的工作。而我们目前根本没有资源来考虑这样的任务。

这在实践中意味着，pip 内部的一切都被认为是一个实现细节。即使是导入名称为 “pip” 这一事实，也可能在没有通知的情况下发生变化。虽然我们尽量不破坏东西，但所有的内部 API 都可以在任何时候，以任何理由改变。这也意味着，我们一般不会修复因以不支持的方式使用 pip 而导致的问题”

还应该注意的是，在运行中的 Python 进程中向 sys.path 安装软件包是应该谨慎进行的事情。导入系统缓存了某些数据，在程序运行时安装新的软件包可能并不总是像预期那样。在实践中，很少出现问题，但这是需要注意的。

说了以上这些，如果你决定确实想从你的程序中运行 pip，那么值得介绍一下可用的选项。最可靠的方法，也是完全被支持的方法，是在一个子进程中运行 pip。使用标准的 subprocess 模块可以很容易地做到这一点

subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'my_package'])

如果你想进一步处理输出，请使用该模块中的其他 API。我们在这里使用 freeze，它以需求格式输出已安装的软件包。

reqs = subprocess.check_output([sys.executable, '-m', 'pip', 'freeze'])

如果你不想使用 pip 的命令行功能，而是想实现与 Python 包、它们的元数据或 PyPI 一起工作的代码，那么你应该考虑其他支持的、提供这类能力的包。你可以考虑的一些例子包括：

packaging —— 处理标准包元数据（版本、需求等）的实用程序。
setuptools （特别是 pkg_resources）--用于查询用户在其系统中安装了哪些软件包的功能。
distlib - 打包和分发工具（包括与 PyPI 交互的功能）。

对 20.3 (2020) 中 pip 依赖关系解析器的修改¶

pip 20.3 有一个新的依赖关系解析器，对于 Python 3 用户来说默认是打开的。 (pip 20.1 和 20.2 包括新的依赖关系解析器的预发布版本，隐藏在可选的用户标志后面。）请阅读下面的迁移指南，如何调用传统的解析器，以及弃用时间表。我们还制作了一个两分钟的视频解释，你可以观看。

我们将根据测试者的反馈继续改进 pip 依赖性解析器。请通过解析器测试调查向我们提供反馈

注意事项¶

这个版本中最大的变化是对 pip 内部的 pip 依赖性解析器。

Computers need to know the right order to install pieces of software (“to install x, you need to install y first”). So, when Python programmers share software as packages, they have to precisely describe those installation prerequisites, and pip needs to navigate tricky situations where it’s getting conflicting instructions. This new dependency resolver will make pip better at handling that tricky logic, and make pip easier for you to use and troubleshoot.

The most significant changes to the resolver are:

It will reduce inconsistency: it will no longer install a combination of packages that is mutually inconsistent. In older versions of pip, it is possible for pip to install a package which does not satisfy the declared requirements of another installed package. For example, in pip 20.0, pip install "six<1.12" "virtualenv==20.0.2" does the wrong thing, “successfully” installing six==1.11, even though virtualenv==20.0.2 requires six>=1.12.0,<2 (defined here). The new resolver, instead, outright rejects installing anything if it gets that input.
It will be stricter - if you ask pip to install two packages with incompatible requirements, it will refuse (rather than installing a broken combination, like it did in previous versions).

So, if you have been using workarounds to force pip to deal with incompatible or inconsistent requirements combinations, now’s a good time to fix the underlying problem in the packages, because pip will be stricter from here on out.

This also means that, when you run a pip install command, pip only considers the packages you are installing in that command, and may break already-installed packages. It will not guarantee that your environment will be consistent all the time. If you pip install x and then pip install y, it’s possible that the version of y you get will be different than it would be if you had run pip install x y in a single command. We are considering changing this behavior (per #7744) and would like your thoughts on what pip’s behavior should be; please answer our survey on upgrades that create conflicts.

We are also changing our support for 约束文件, editable installs, and related functionality. We did a fairly comprehensive overhaul and stripped constraints files down to being purely a way to specify global (version) limits for packages, and so some combinations that used to be allowed will now cause errors. Specifically:

Constraints don’t override the existing requirements; they simply constrain what versions are visible as input to the resolver (see #9020)
Providing an editable requirement (-e .) does not cause pip to ignore version specifiers or constraints (see #8076), and if you have a conflict between a pinned requirement and a local directory then pip will indicate that it cannot find a version satisfying both (see #8307)
Hash-checking mode requires that all requirements are specified as a == match on a version and may not work well in combination with constraints (see #9020 and #8792)
If necessary to satisfy constraints, pip will happily reinstall packages, upgrading or downgrading, without needing any additional command-line options (see #8115 and Options that control the installation process)
Unnamed requirements are not allowed as constraints (see #6628 and #8210)
Links are not allowed as constraints (see #8253)
Constraints cannot have extras (see #6628)

Per our Python 2 Support policy, pip 20.3 users who are using Python 2 will use the legacy resolver by default. Python 2 users should upgrade to Python 3 as soon as possible, since in pip 21.0 in January 2021, pip dropped support for Python 2 altogether.

How to upgrade and migrate¶

Install pip 20.3 with python -m pip install --upgrade pip.
Validate your current environment by running pip check. This will report if you have any inconsistencies in your set of installed packages. Having a clean installation will make it much less likely that you will hit issues with the new resolver (and may address hidden problems in your current environment!). If you run pip check and run into stuff you can’t figure out, please ask for help in our issue tracker or chat.
Test the new version of pip.

While we have tried to make sure that pip’s test suite covers as many cases as we can, we are very aware that there are people using pip with many different workflows and build processes, and we will not be able to cover all of those without your help.
- If you use pip to install your software, try out the new resolver and let us know if it works for you with pip install. Try:
  - installing several packages simultaneously
  - re-creating an environment using a requirements.txt file
  - using pip install --force-reinstall to check whether it does what you think it should
  - using constraints files
  - the “Setups to test with special attention” and “Examples to try” below
- If you have a build pipeline that depends on pip installing your dependencies for you, check that the new resolver does what you need.
- Run your project’s CI (test suite, build process, etc.) using the new resolver, and let us know of any issues.
- If you have encountered resolver issues with pip in the past, check whether the new resolver fixes them, and read 修复冲突的依赖关系. Also, let us know if the new resolver has issues with any workarounds you put in to address the current resolver’s limitations. We’ll need to ensure that people can transition off such workarounds smoothly.
- If you develop or support a tool that wraps pip or uses it to deliver part of your functionality, please test your integration with pip 20.3.
Troubleshoot and try these workarounds if necessary.
- If pip is taking longer to install packages, read Dependency resolution backtracking for ways to reduce the time pip spends backtracking due to dependency conflicts.
- If you don’t want pip to actually resolve dependencies, use the --no-deps option. This is useful when you have a set of package versions that work together in reality, even though their metadata says that they conflict. For guidance on a long-term fix, read 修复冲突的依赖关系.
- If you run into resolution errors and need a workaround while you’re fixing their root causes, you can choose the old resolver behavior using the flag --use-deprecated=legacy-resolver. This will work until we release pip 21.0 (see Deprecation timeline).
Please report bugs through the resolver testing survey.

Setups to test with special attention¶

Requirements files with 100+ packages
Installation workflows that involve multiple requirements files
Requirements files that include hashes (Hash-Checking Mode) or pinned dependencies (perhaps as output from pip-compile within pip-tools)
Using 约束文件
Continuous integration/continuous deployment setups
Installing from any kind of version control systems (i.e., Git, Subversion, Mercurial, or CVS), per VCS Support
Installing from source code held in local directories

Examples to try¶

Install:

tensorflow
hacking
pycodestyle
pandas
tablib
elasticsearch and requests together
six and cherrypy together
pip install flake8-import-order==0.17.1 flake8==3.5.0 --use-feature=2020-resolver
pip install tornado==5.0 sprockets.http==1.5.0 --use-feature=2020-resolver

Try:

pip install
pip uninstall
pip check
pip cache

Tell us about¶

Specific things we’d love to get feedback on:

Cases where the new resolver produces the wrong result, obviously. We hope there won’t be too many of these, but we’d like to trap such bugs before we remove the legacy resolver.
Cases where the resolver produced an error when you believe it should have been able to work out what to do.
Cases where the resolver gives an error because there’s a problem with your requirements, but you need better information to work out what’s wrong.
If you have workarounds to address issues with the current resolver, does the new resolver let you remove those workarounds? Tell us!

Please let us know through the resolver testing survey.

Deprecation timeline¶

We plan for the resolver changeover to proceed as follows, using Feature Flags and following our Release Cadence:

pip 20.1: an alpha version of the new resolver was available, opt-in, using the optional flag --unstable-feature=resolver. pip defaulted to legacy behavior.
pip 20.2: a beta of the new resolver was available, opt-in, using the flag --use-feature=2020-resolver. pip defaulted to legacy behavior. Users of pip 20.2 who want pip to default to using the new resolver can run pip config set global.use-feature 2020-resolver (for more on that and the alternate PIP_USE_FEATURE environment variable option, see issue 8661).
pip 20.3: pip defaults to the new resolver in Python 3 environments, but a user can opt-out and choose the old resolver behavior, using the flag --use-deprecated=legacy-resolver. In Python 2 environments, pip defaults to the old resolver, and the new one is available using the flag --use-feature=2020-resolver.
pip 21.0: pip uses new resolver by default, and the old resolver is no longer supported. It will be removed after a currently undecided amount of time, as the removal is dependent on pip’s volunteer maintainers’ availability. Python 2 support is removed per our Python 2 Support policy.

Since this work will not change user-visible behavior described in the pip documentation, this change is not covered by the Deprecation Policy.

Context and followup¶

As discussed in our announcement on the PSF blog, the pip team are in the process of developing a new “dependency resolver” (the part of pip that works out what to install based on your requirements).

We’re tracking our rollout in #6536 and you can watch for announcements on the low-traffic packaging announcements list and the official Python blog.

用户指南¶

运行 pip¶

安装包¶

基本认证凭证¶

netrc 支持¶

Keyring 支持¶

使用代理服务器¶

需求文件¶

约束文件¶

从轮子开始安装¶

卸载包¶

包的列表¶

搜索包¶

配置¶

配置文件¶

环境变量¶

配置优先级¶

命令补全¶

从本地软件包安装¶

“只有在需要时”才递归升级¶

用户安装¶

确保可重复性¶

修复冲突的依赖关系¶

从你的程序中使用 pip¶

对 20.3 (2020) 中 pip 依赖关系解析器的修改¶

注意事项¶

How to upgrade and migrate¶

Setups to test with special attention¶

Examples to try¶

Tell us about¶

Deprecation timeline¶

Context and followup¶