安装包#

本部分介绍如何安装 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 部分。

注意

如果你是一个新手，并且遇到了这样的错误

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

这是因为本教程中的此命令和其他建议的命令旨在在 shell（也称为 终端 或 控制台）中运行。请参阅 Python for Beginners 入门教程，了解如何使用操作系统的 shell 并与 Python 交互。

注意

如果你使用的是 IPython 或 Jupyter notebook 等增强型 shell，你可以通过在这些命令前加上 ! 字符来运行本教程中的系统命令

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

建议编写 {sys.executable} 而不是简单的 python，以确保命令在与当前运行的 notebook 匹配的 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，使用来自 python.org 的安装程序，或通过 Homebrew 安装，你应该已经有了 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（或你的平台的标准位置），很容易陷入无意中升级不应该升级的应用程序的情况。

或者更一般地说，如果您想安装一个应用程序并置之不理，该怎么办？如果应用程序有效，其库或这些库的版本中的任何更改都可能破坏该应用程序。

此外，如果您无法将软件包安装到全局 site-packages 目录中，该怎么办？例如，在共享主机上。

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

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

  • venv 在 Python 3.3 及更高版本中默认可用，并在 Python 3.4 及更高版本中将pip安装到创建的虚拟环境中（3.12 之前的 Python 版本还安装了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 shell 中使用source可确保在当前 shell 中设置虚拟环境的变量，而不是在子进程中（子进程随后消失，没有有用的效果）。

在上述两种情况下，Windows 用户不应使用source命令，而应直接从命令 shell 运行activate脚本，如下所示

<DIR>\Scripts\activate

直接管理多个虚拟环境可能会变得繁琐，因此依赖项管理教程引入了一个更高级别的工具Pipenv，它可以自动管理您处理的每个项目和应用程序的单独虚拟环境。

使用 pip 进行安装#

pip是推荐的安装程序。下面，我们将介绍最常见的用法场景。有关更多详细信息，请参阅pip 文档，其中包括完整的参考指南。

从 PyPI 安装#

最常见的pip用法是从Python 包索引使用需求说明符进行安装。一般来说，需求说明符由项目名称和可选的版本说明符组成。可以在版本说明符规范中找到对受支持说明符的完整描述。以下是一些示例。

要安装“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"

要安装与特定版本兼容的版本：[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 将优先选择兼容的轮子。您可以覆盖 pip 的默认行为，例如使用其–no-binary选项。

轮子是一种预构建的发行版格式，与源发行版 (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 文档中的用户安装部分。

请注意，当在虚拟环境中时，--user标志无效 - 所有安装命令都将影响虚拟环境。

如果 SomeProject 定义了任何命令行脚本或控制台入口点， --user 将导致它们安装在 用户基础 的二进制目录中，该目录可能已经存在于 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 安装#

以“可编辑”模式从 VCS 安装项目。有关语法的完整细分，请参阅 pip 关于 VCS 支持 的部分。

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

py -m pip install -e SomeProject @ git+https://git.repo/some_pkg.git          # from git
py -m pip install -e SomeProject @ hg+https://hg.repo/some_pkg                # from mercurial
py -m pip install -e SomeProject @ svn+svn://svn.repo/some_pkg/trunk/         # from svn
py -m pip install -e SomeProject @ git+https://git.repo/some_pkg.git@feature  # 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 树安装#

从 开发模式 中的本地 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 存储）安装，你可以创建一个帮助程序，以符合 简单存储库 API 格式显示数据，并使用 --extra-index-url 标志指导 pip 使用该索引。

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

安装预发布版本#

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

python3 -m pip install --pre SomeProject

py -m pip install --pre SomeProject

安装“附加内容”#

附加内容是包的可选“变体”，可能包括其他依赖项，从而启用包的其他功能。如果你希望为已知发布附加内容的包安装附加内容，则可以将其包含在 pip 安装命令中

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