安装软件包

本节介绍如何安装 Python 软件包 的基础知识。

需要注意的是，在此上下文中，“软件包”一词用于描述要安装的软件捆绑包（即 发行版 的同义词）。它并非指您在 Python 源代码中导入的那种 包 （即模块的容器）。在 Python 社区中，通常用“软件包”一词来指代 发行版。通常不首选使用“发行版”一词，因为它很容易与 Linux 发行版或 Python 本身等其他大型软件发行版混淆。

安装软件包的要求

本节描述安装其他 Python 软件包之前要遵循的步骤。

确保您可以从命令行运行 Python

在您进行任何操作之前，请确保您已安装 Python 并且命令行中可使用预期版本。您可以通过运行以下命令来检查：

python3 --version

py --version

您应该会看到类似 Python 3.6.3 的输出。如果您没有安装 Python，请从 python.org 安装最新的 3.x 版本，或参阅《Python 漫游指南》的 安装 Python 部分。

注意

如果您是新手并且遇到类似这样的错误

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

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

注意

如果您正在使用增强的 shell（例如 IPython 或 Jupyter notebook），您可以通过在命令前加上 ! 字符来运行本教程中的系统命令

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.org 的安装程序或通过 Homebrew 安装了 Python，您应该已经拥有 pip。如果您在 Linux 上并使用 OS 包管理器安装，您可能需要单独安装 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 安装到创建的虚拟环境中（Python 3.12 之前的版本也安装了 Setuptools）。

  • virtualenv 需要单独安装，但支持 Python 2.7+ 和 Python 3.3+，并且 pip、Setuptools 和 wheel 默认安装到创建的虚拟环境中。请注意，从 Python 3.12 开始，setuptools 不再默认包含（并且 virtualenv 遵循此行为）。

基本用法如下：

使用 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”的版本。

源发行版与 Wheel

pip 可以从 源发行版 (sdist) 或 Wheel 安装，但如果两者都在 PyPI 上存在，pip 将优先选择兼容的 wheel。您可以通过例如使用其 --no-binary 选项来覆盖 pip 的默认行为。

Wheel 是一种预构建的 发行版 格式，与 源发行版 (sdist) 相比，它提供了更快的安装速度，尤其是在项目包含编译扩展时。

如果 pip 没有找到可安装的 wheel，它将本地构建一个 wheel 并将其缓存以供将来安装，而不是将来重建源发行版。

升级软件包

将已安装的 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://:7777 SomeProject

安装预发布版本

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

python3 -m pip install --pre SomeProject

py -m pip install --pre SomeProject

安装“Extras”

额外功能是软件包的可选“变体”，可能包含额外的依赖项，从而实现软件包的额外功能。如果您希望为某个已知发布额外功能的软件包安装额外功能，可以将其包含在 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