安装包

这一节涵盖了如何安装 Python 包 的基本知识 。

需要注意的是，在这种情况下，术语 “包” 被用来描述要安装的一组软件（即作为一个 套件 的同义词）。它并不是指你在 Python 源代码中导入的那种 包 （即一个模块的容器）。在 Python 社区中，通常使用术语 “包” 来指代 套件。使用术语 “分发” 通常不是首选，因为它很容易与 Linux 发行版或另一个更大的软件发行版（如 Python 本身）相混淆。

安装软件包的需求

这一节描述了在安装其他 Python 软件包之前需要遵循的步骤。

确保你能从命令行运行 Python

在你进一步行动之前，确保你有 Python，并且预期的版本在你的命令行中可用。你可以通过运行以下命令来检查：

python3 --version

py --version

你应该得到一些输出，如 Python 3.6.3。如果你没有 Python，请从 python.org 安装最新的 3.x 版本，或者参考 Hitchhiker’s Guide to Python 中的章节 安装 Python。

备注

如果你是一个新人，而你遇到这样的错误：

>>> python --version
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'python' is not defined

这是因为这个命令和本教程中建议的其他命令是要在 shell （也叫 终端 或 控制台）。请参阅 Python for Beginners getting started tutorial 了解使用操作系统的 shell 和与 Python 交互的介绍。

备注

如果你使用的是 IPython 或 Jupyter 笔记本等增强型 shell，你可以在运行本教程中的那些系统命令时，在它们前面加上 ! 字符来表示：

In [1]: import sys
        !{sys.executable} --version
Python 3.6.3

建议编写 {sys.executable} 而不是普通的 python，以确保命令在与当前运行的笔记本相匹配的 Python 安装中运行（可能不是 python 命令所指的那个 Python 安装）。

备注

由于大多数 Linux 发行版处理 Python 3 迁移的方式，使用系统 Python 而不先创建虚拟环境的 Linux 用户应将本教程中的 python 命令改为 python3，python -m pip 命令改为 python3 -m pip --user。不要用 sudo 运行本教程中的任何命令：如果你得到一个权限错误，请回到创建虚拟环境的部分，设置一个虚拟环境，然后继续学习本教程。

确保你能从命令行运行 pip

此外，你需要确保你有 pip 可用。你可以通过运行以下程序来检查：

python3 -m pip --version

py -m pip --version

如果你从源代码，通过 python.org 的安装程序，或通过 Homebrew 安装了 Python，你应该已经有了 pip。如果你是在 Linux 上，并且使用你的操作系统包管理器安装，你可能需要单独安装 pip，参见 用 Linux 软件包管理器安装 pip/setuptools/wheel。

如果 pip 还没有安装，那么首先尝试从标准库启动它：

python3 -m ensurepip --default-pip

py -m ensurepip --default-pip

如果这仍然不允许你运行 python -m pip ：

  • 安全下载 get-pip.py 1

  • 运行 python get-pip.py。2 这将安装或升级 pip。此外，它将安装 setuptools 和 wheel，如果它们还没有安装。

    警告

    如果你使用的 Python 安装是由你的操作系统或其他软件包管理器管理的，那就要小心了。get-pip.py 不与这些工具协调，可能会让你的系统处于不一致的状态。你可以使用 python get-pip.py --prefix=/usr/local/ 来安装在 /usr/local 中，这是为本地安装的软件设计的。

确保 pip、setuptools 和 wheel 是最新的。

虽然单靠 pip 就足以从预先建立的二进制档案中进行安装，但 setuptools 和 wheel 项目的最新副本对于确保你也能从源代码档案中进行安装非常有用：

python3 -m pip install --upgrade pip setuptools wheel

py -m pip install --upgrade pip setuptools wheel

可选地，创建一个虚拟环境

详见 下面的 部分，但以下是在典型的 Linux 系统上使用的基本 venv 3 命令：

python3 -m venv tutorial_env
source tutorial_env/bin/activate

py -m venv tutorial_env
tutorial_env\Scripts\activate

这将在 tutorial_env 子目录下创建一个新的虚拟环境，并将当前的 shell 配置为使用它作为默认的 python 环境。

创建虚拟环境

Python “虚拟环境” 允许 Python 包 为特定的应用程序安装在一个孤立的位置，而不是全局安装。如果你想安全地安装全局命令行工具，请参阅 安装独立命令行工具。

想象一下，你有一个需要 LibFoo 版本 1 的应用程序，但另一个应用程序需要版本 2。你怎么能同时使用这些应用程序呢？如果你把所有东西都安装到 /usr/lib/python3.6/Site-packages （或者你的平台的标准位置），很容易出现无意中升级一个不应该升级的应用程序的情况。

或者更广泛地说，如果你想安装一个应用程序并让它保持原样，怎么办？如果一个应用程序可以工作，其库或这些库的版本的任何变化都会破坏该应用程序。

另外，如果你不能把 包 安装到全局站点的 packages 目录中，怎么办？例如，在一个共享主机上。

在所有这些情况下，虚拟环境可以帮助你。它们有自己的安装目录，而且它们不与其他虚拟环境共享库”

目前，有两种创建 Python 虚拟环境的常用工具：

  • venv 在 Python 3.3 及以后的版本中默认可用，并在 Python 3.4 及以后的版本中把 pip 和 setuptools 安装到创建的虚拟环境中。

  • virtualenv 需要单独安装，但支持 Python 2.7+ 和 Python 3.3+，并且 pip、setuptools 和 wheel 总是默认安装到创建的虚拟环境中（无论 Python 版本如何）。

基本的用法是这样的：

使用 venv：

python3 -m venv <DIR>
source <DIR>/bin/activate

py -m venv <DIR>
<DIR>\Scripts\activate

使用 virtualenv：

python3 -m virtualenv <DIR>
source <DIR>/bin/activate

virtualenv <DIR>
<DIR>\Scripts\activate

更多信息，请参阅 venv 文档或 virtualenv 文档。

在 Unix 外壳下使用 source 可以确保虚拟环境的变量是在当前的外壳中设置的，而不是在子进程中设置的（子进程随后消失，没有任何作用）。

在上述两种情况下，Windows 用户不应该使用 source 命令，而应该像这样直接从命令外壳运行 activate 脚本：

<DIR>\Scripts\activate

直接管理多个虚拟环境会变得很乏味，所以 依赖管理教程 介绍了一个更高层次的工具，Pipenv，它为你工作的每个项目和应用程序自动管理一个单独的虚拟环境。

使用 pip 进行安装

pip 是推荐的安装程序。下面，我们将介绍最常见的使用场景。更多细节，请参阅 pip docs，其中包括一个完整的 参考指南。

从 PyPI 进行安装

pip 最常见的用法是使用 Python 包索引 来安装，使用 requirement specifier。一般来说，需求说明由项目名称和可选的 version specifier 组成。PEP 440 包含一个 full specification 的当前支持的说明。下面是一些例子。

要安装最新版本的 “SomeProject”：

python3 -m pip install "SomeProject"

py -m pip install "SomeProject"

要安装一个特定的版本：

python3 -m pip install "SomeProject==1.4"

py -m pip install "SomeProject==1.4"

要安装大于或等于一个版本而小于另一个版本的产品：

python3 -m pip install "SomeProject>=1,<2"

py -m pip install "SomeProject>=1,<2"

要安装一个与 “compatible” 兼容某一版本：4

python3 -m pip install "SomeProject~=1.4.2"

py -m pip install "SomeProject~=1.4.2"

在这种情况下，这意味着要安装任何版本 “==1.4.*” 的版本，同时也是 “>=1.4.2”。

源分发与轮子

pip 可以从 源分发（sdist） 或 轮子 安装，但如果两者都存在于 PyPI 上，pip 会优先选择兼容的 轮子。你可以通过使用 -no-binary 选项来覆盖 pip 的默认行为。

轮子 是一种预先建立的 distribution 格式，与 源分发（sdist） 相比，它提供更快的安装，特别是当一个项目包含编译的扩展。

如果 pip 没有找到要安装的轮子，它将在本地建立一个轮子，并为将来的安装进行缓存，而不是在将来重建源码分布。

升级包

将已经安装的 SomeProject 升级到 PyPI 的最新版本。

python3 -m pip install --upgrade SomeProject

py -m pip install --upgrade SomeProject

安装到用户站点

要安装 包 隔离于当前用户，请使用 --user 标志：

python3 -m pip install --user SomeProject

py -m pip install --user SomeProject

更多信息请参见 pip docs 中的 用户安装 部分。

注意，--user 标志在虚拟环境内没有作用 – 所有的安装命令都会影响虚拟环境。

如果 SomeProject 定义了任何命令行脚本或控制台入口点，--user 将导致它们被安装在 user base 的二进制目录中，该目录可能已经存在于你的 shell 的 PATH 中，也可能不存在。(从版本 10 开始，当安装任何脚本到 PATH 以外的目录时，pip 会显示一个警告。）如果安装后脚本在你的 shell 中不可用，你需要将该目录添加到你的 PATH 中：

  • 在 Linux 和 macOS 上，你可以通过运行 python -m site --user-base 并在后面添加 bin 来找到用户基础二进制目录。例如，这通常会打印出 ~/.local （ ~ 扩展为你的主目录的绝对路径），所以你需要将 ~/.local/bin 加入你的 PATH。你可以通过 修改 ~/.profile 来永久设置你的 PATH。

  • 在 Windows 上，你可以通过运行 py -m site --user-site 并将 site-packages 替换为 Scripts 来找到用户基础二进制目录。例如，这可能会返回 C:\Users\Username\AppData\Roaming\Python36/site-packages，所以你需要设置你的 PATH 以包括 C:\Users\Username\AppData\Roaming\Python36/Scripts。你可以在 控制面板 中永久设置你的用户 PATH。你可能需要注销才能使 PATH 的改变生效。

需求文件

安装一个在 需求文件 中指定的需求列表。

python3 -m pip install -r requirements.txt

py -m pip install -r requirements.txt

从 VCS 安装

以 “editable” 模式从 VCS 安装一个项目。关于语法的详细介绍，请参见 pip 的 VCS 支持 部分。

python3 -m pip install -e git+https://git.repo/some_pkg.git#egg=SomeProject          # from git
python3 -m pip install -e hg+https://hg.repo/some_pkg#egg=SomeProject                # from mercurial
python3 -m pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomeProject         # from svn
python3 -m pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomeProject  # from a branch

py -m pip install -e git+https://git.repo/some_pkg.git#egg=SomeProject          # from git
py -m pip install -e hg+https://hg.repo/some_pkg#egg=SomeProject                # from mercurial
py -m pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomeProject         # from svn
py -m pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomeProject  # from a branch

从其他索引中安装

从另一个索引安装

python3 -m pip install --index-url http://my.package.repo/simple/ SomeProject

py -m pip install --index-url http://my.package.repo/simple/ SomeProject

在安装过程中，除了 PyPI 之外，还要搜索一个额外的索引

python3 -m pip install --extra-index-url http://my.package.repo/simple SomeProject

py -m pip install --extra-index-url http://my.package.repo/simple SomeProject

从本地 src 树上安装

在 Development Mode 中从本地 src 安装，即以这样一种方式，项目看似已经安装，但仍可从 src 树上编辑。

python3 -m pip install -e <path>

py -m pip install -e <path>

你也可以从 src 中正常安装

python3 -m pip install <path>

py -m pip install <path>

从本地档案库安装

安装一个特定的源存档文件。

python3 -m pip install ./downloads/SomeProject-1.0.4.tar.gz

py -m pip install ./downloads/SomeProject-1.0.4.tar.gz

从包含档案的本地目录中安装（并且不要检查 PyPI ）

python3 -m pip install --no-index --find-links=file:///local/dir/ SomeProject
python3 -m pip install --no-index --find-links=/local/dir/ SomeProject
python3 -m pip install --no-index --find-links=relative/dir/ SomeProject

py -m pip install --no-index --find-links=file:///local/dir/ SomeProject
py -m pip install --no-index --find-links=/local/dir/ SomeProject
py -m pip install --no-index --find-links=relative/dir/ SomeProject

从其他来源安装

要从其他数据源（例如 Amazon S3 存储）安装，你可以创建一个辅助应用程序，以 PEP 503 兼容的索引格式展示数据，并使用 --extra-index-url 标志来指导 pip 使用该索引。

./s3helper --port=7777
python -m pip install --extra-index-url http://localhost:7777 SomeProject

安装预发行版

除了稳定版本之外，还可以找到预发布版本和开发版本。默认情况下，pip 只查找稳定版本。

python3 -m pip install --pre SomeProject

py -m pip install --pre SomeProject

Installing “Extras”

Extras are optional “variants” of a package, which may include additional dependencies, and thereby enable additional functionality from the package. If you wish to install an extra for a package which you know publishes one, you can include it in the pip installation command:

python3 -m pip install SomePackage[PDF]
python3 -m pip install SomePackage[PDF]==3.0
python3 -m pip install -e .[PDF]  # editable project in current directory

py -m pip install SomePackage[PDF]
py -m pip install SomePackage[PDF]==3.0
py -m pip install -e .[PDF]  # editable project in current directory
1

“Secure” 在这里意味着使用现代浏览器或像 curl 这样的工具，在从 https 网址下载时验证 SSL 证书。

2

根据你的平台，这可能需要 root 或管理员权限。 pip 目前正在考虑通过 使用户安装成为默认行为 来改变这一点。

3

从 Python 3.4 开始，venv （ virtualenv 的 stdlib 替代品）将创建预装了 pip 的 virtualenv 环境，从而使其成为 virtualenv 的同等替代品。

4

在 PEP 440 中接受了兼容的发行规格，并在 setuptools v8.0 和 pip v6.0 中发布了支持