在虚拟环境中使用 pip 和 venv 安装包

本指南讨论如何使用标准库的虚拟环境工具 venv 创建和激活虚拟环境，以及安装包。本指南涵盖以下内容：

  • 创建并激活虚拟环境

  • 准备 pip

  • 使用 pip 命令将包安装到虚拟环境中

  • 使用并创建 requirements 文件

注意

本指南适用于受支持的 Python 版本，目前是 3.8 及更高版本。

注意

本指南使用术语 包 来指代 分发包，通常从外部主机安装。这与术语 导入包 不同，后者指代 Python 源代码中的导入模块。

重要提示

本指南有一个前提条件，即您正在使用从 <https://pythonlang.cn/downloads/> 获取的官方 Python 版本。如果您正在使用操作系统的包管理器安装 Python，请在执行这些步骤之前确保 Python 已安装。

创建和使用虚拟环境

创建一个新的虚拟环境

venv (适用于 Python 3) 允许您为不同的项目管理单独的包安装。它会创建一个“虚拟”的独立 Python 安装。当您切换项目时，您可以创建一个新的虚拟环境，该环境与其他虚拟环境是隔离的。您会受益于虚拟环境，因为包可以放心地安装，并且不会干扰其他项目的环境。

提示

建议在使用第三方包时使用虚拟环境。

要创建虚拟环境，请进入您的项目目录并运行以下命令。这将在名为 .venv 的本地文件夹中创建一个新的虚拟环境

python3 -m venv .venv

py -m venv .venv

第二个参数是创建虚拟环境的位置。通常，您只需在项目中创建它并将其命名为 .venv。

venv 将在 .venv 文件夹中创建一个虚拟 Python 安装。

注意

您应该使用 .gitignore 或类似工具将您的虚拟环境目录排除在版本控制系统之外。

激活虚拟环境

在您开始在虚拟环境中安装或使用包之前，您需要 激活 它。激活虚拟环境会将虚拟环境特定的 python 和 pip 可执行文件放入您 shell 的 PATH 中。

source .venv/bin/activate

.venv\Scripts\activate

要确认虚拟环境已激活，请检查 Python 解释器的位置

which python

where python

当虚拟环境激活时，上述命令将输出一个包含 .venv 目录的文件路径，以以下内容结尾

.venv/bin/python

.venv\Scripts\python

当虚拟环境激活时，pip 会将包安装到该特定环境中。这使您可以在 Python 应用程序中导入和使用包。

停用虚拟环境

如果您想切换项目或离开虚拟环境，请 停用 该环境

deactivate

注意

关闭 shell 将停用虚拟环境。如果您打开一个新的 shell 窗口并想使用虚拟环境，请重新激活它。

重新激活虚拟环境

如果您想重新激活一个现有的虚拟环境，请遵循与激活虚拟环境相同的说明。无需创建新的虚拟环境。

准备 pip

pip 是 Python 的参考包管理器。它用于将包安装和更新到虚拟环境中。

macOS 的 Python 安装程序包含 pip。在 Linux 上，您可能需要安装额外的包，例如 python3-pip。您可以通过运行以下命令确保 pip 是最新的

python3 -m pip install --upgrade pip
python3 -m pip --version

之后，您的用户站点中应该安装了最新版本的 pip

pip 23.3.1 from .../.venv/lib/python3.9/site-packages (python 3.9)

Windows 的 Python 安装程序包含 pip。您可以通过运行以下命令确保 pip 是最新的

py -m pip install --upgrade pip
py -m pip --version

之后，您应该拥有最新版本的 pip

pip 23.3.1 from .venv\lib\site-packages (Python 3.9.4)

使用 pip 安装包

当您的虚拟环境激活时，您可以安装包。使用 pip install 命令来安装包。

安装包

例如，让我们从 Python 包索引 (PyPI) 安装 Requests 库

python3 -m pip install requests

py -m pip install requests

pip 应该下载 requests 及其所有依赖项并安装它们

Collecting requests
  Using cached requests-2.18.4-py2.py3-none-any.whl
Collecting chardet<3.1.0,>=3.0.2 (from requests)
  Using cached chardet-3.0.4-py2.py3-none-any.whl
Collecting urllib3<1.23,>=1.21.1 (from requests)
  Using cached urllib3-1.22-py2.py3-none-any.whl
Collecting certifi>=2017.4.17 (from requests)
  Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
Collecting idna<2.7,>=2.5 (from requests)
  Using cached idna-2.6-py2.py3-none-any.whl
Installing collected packages: chardet, urllib3, certifi, idna, requests
Successfully installed certifi-2017.7.27.1 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22

安装特定包版本

pip 允许您使用 版本说明符 指定要安装的包版本。例如，要安装特定版本的 requests

python3 -m pip install 'requests==2.18.4'

py -m pip install "requests==2.18.4"

要安装 requests 的最新 2.x 版本

python3 -m pip install 'requests>=2.0.0,<3.0.0'

py -m pip install "requests>=2.0.0,<3.0.0"

要安装包的预发布版本，请使用 --pre 标志

python3 -m pip install --pre requests

py -m pip install --pre requests

安装 extras

某些包具有可选的 extras。您可以通过在方括号中指定 extra 来告诉 pip 安装这些 extras

python3 -m pip install 'requests[security]'

py -m pip install "requests[security]"

从源代码安装包

pip 可以直接从其源代码安装包。例如，要安装 google-auth 目录中的源代码

cd google-auth
python3 -m pip install .

cd google-auth
py -m pip install .

此外，pip 可以在 开发模式 下从源代码安装包，这意味着对源代码目录的更改将立即影响已安装的包，而无需重新安装

python3 -m pip install --editable .

py -m pip install --editable .

从版本控制系统安装

pip 可以直接从其版本控制系统安装包。例如，您可以直接从 git 仓库安装

google-auth @ git+https://github.com/GoogleCloudPlatform/google-auth-library-python.git

有关支持的版本控制系统和语法的更多信息，请参阅 pip 关于 VCS 支持 的文档。

从本地存档安装

如果您有 分发包 存档（zip、wheel 或 tar 文件）的本地副本，您可以直接使用 pip 安装它

python3 -m pip install requests-2.18.4.tar.gz

py -m pip install requests-2.18.4.tar.gz

如果您有一个包含多个包存档的目录，您可以告诉 pip 在该目录中查找包，而不使用 Python 包索引 (PyPI)

python3 -m pip install --no-index --find-links=/local/dir/ requests

py -m pip install --no-index --find-links=/local/dir/ requests

这在连接受限的系统上安装包或您想严格控制分发包来源时非常有用。

从其他包索引安装

如果您想从 Python 包索引 (PyPI) 之外的其他索引下载包，您可以使用 --index-url 标志

python3 -m pip install --index-url http://index.example.com/simple/ SomeProject

py -m pip install --index-url http://index.example.com/simple/ SomeProject

如果您想允许来自 Python 包索引 (PyPI) 和单独索引的包，您可以使用 --extra-index-url 标志代替

python3 -m pip install --extra-index-url http://index.example.com/simple/ SomeProject

py -m pip install --extra-index-url http://index.example.com/simple/ SomeProject

升级包

pip 可以使用 --upgrade 标志就地升级包。例如，要安装最新版本的 requests 及其所有依赖项

python3 -m pip install --upgrade requests

py -m pip install --upgrade requests

使用 requirements 文件

pip 允许您将所有依赖项声明在 Requirements 文件 中，而不是单独安装包。例如，您可以创建一个包含以下内容的 requirements.txt 文件

requests==2.18.4
google-auth==1.1.0

并告诉 pip 使用 -r 标志安装此文件中的所有包

python3 -m pip install -r requirements.txt

py -m pip install -r requirements.txt

冻结依赖项

Pip 可以使用 freeze 命令导出所有已安装包及其版本的列表

python3 -m pip freeze

py -m pip freeze

它将输出一个包说明符列表，例如

cachetools==2.0.1
certifi==2017.7.27.1
chardet==3.0.4
google-auth==1.1.1
idna==2.6
pyasn1==0.3.6
pyasn1-modules==0.1.4
requests==2.18.4
rsa==3.4.2
six==1.11.0
urllib3==1.22

pip freeze 命令对于创建可以重新创建环境中所有已安装包的精确版本的 Requirements 文件 非常有用。