使用 Python 的 pip 管理项目依赖

Philipp Acsany

pip 是 Python 的标准包管理器，用于安装和管理不属于 Python 标准库的第三方库。你可以使用 pip 来管理依赖项，并从 Python Package Index（PyPI）安装软件包。

你可以通过在 Windows 上运行 where pip3 或在 Linux 和 macOS 上运行 which pip3 来验证是否已安装 pip。要安装 requirements.txt 文件中列出的包，可以使用命令 pip install -r requirements.txt。这能确保你的环境复现指定的依赖关系，在不同环境中保持一致性。

完成本教程后，你将理解以下内容：

• pip 代表 “pip installs packages”（pip 安装包），表明其主要功能。
• pip 用于管理不属于标准库的 Python 包。
• 当你的项目需要外部 Python 包时，应使用 pip。
• 可以使用 pip 安装和卸载包。
• 使用需求文件（requirements files）来管理项目的依赖。

pip 功能强大，但 Python 社区非常活跃，也开发了一些优秀的 pip 替代工具。本教程稍后会介绍这些替代方案。

入门 pip

那么，pip 到底是做什么的？pip 是 Python 的包管理器。这意味着它是一个工具，允许你安装和管理那些未包含在标准库中的库和依赖项。pip 这个名字由 Ian Bicking 在 2008 年提出：

我已经完成了将 pyinstall 重命名为新名字：pip。pip 是一个缩写，也是一种宣言：pip installs packages。（来源）

包管理非常重要，因此自 Python 3.4 和 2.7.9 起（分别对应 Python 3 和 Python 2），Python 安装程序就已内置了 pip。许多 Python 项目都使用 pip，使其成为每位 Python 开发者的必备工具。

如果你来自其他编程语言，可能对包管理器的概念并不陌生。JavaScript 使用 npm，Ruby 使用 gem，.NET 平台使用 NuGet。而在 Python 中，pip 已成为标准的包管理器。

在系统中查找 pip

Python 安装程序在安装 Python 时默认会勾选安装 pip，因此安装完 Python 后，pip 应该就可以直接使用。

注意：在某些 Linux（Unix）系统（如 Ubuntu）上，pip 是一个名为 python3-pip 的独立包，你需要通过 sudo apt install python3-pip 手动安装。它不会随解释器默认安装。

你可以通过查找系统中的 pip3 可执行文件来验证 pip 是否可用。根据你的操作系统，使用以下命令：

• Windows：

  where pip3
  

• Linux + macOS：

  which pip3
  

which 命令在 Linux 和 macOS 上会显示 pip3 二进制文件的位置。

在 Windows 和 Unix 系统上，pip3 可能存在于多个位置。这通常发生在你安装了多个 Python 版本时。如果你在系统中找不到 pip，可以考虑重新安装 pip。

除了直接运行系统中的 pip，你也可以将其作为 Python 模块运行。下一节将介绍这种方法。

将 pip 作为模块运行

当你直接运行系统中的 pip 时，命令本身不会显示 pip 属于哪个 Python 版本。这可能导致你不小心将包安装到旧版 Python 的 site-packages 目录中而毫无察觉。为避免这种情况，建议将 pip 作为 Python 模块运行：

$ python -m pip

这里使用 python -m 来运行 pip。-m 开关告诉 Python 将某个模块作为可执行脚本运行。这样可以确保使用的是系统默认的 Python 版本来执行 pip 命令。

注意：根据你的 Python 安装方式，Python 可执行文件的名称可能不是 python，而是 py 或 python3。本教程统一使用 python，你可能需要根据实际情况调整命令。

有时你希望将包限制在特定项目中。在这种情况下，应在虚拟环境中运行 pip。

在 Python 虚拟环境中使用 pip

为了避免将包直接安装到系统 Python 中，你可以使用虚拟环境。虚拟环境为你的项目提供一个隔离的 Python 解释器。在此环境中安装的所有包都与系统解释器和其他项目相互独立。

在虚拟环境中使用 pip 有三大优势：

1. 确保使用正确的 Python 版本；
2. 确保运行的是正确的 pip 实例；
3. 可以为项目使用特定版本的包，而不影响其他项目。

Python 内置了 venv 模块用于创建虚拟环境。该模块可帮助你创建一个带有隔离 Python 安装的环境。激活虚拟环境后，即可在其中安装包。这些包与其他环境完全隔离。

你可以按以下步骤创建并验证虚拟环境中的 pip：

• Linux + macOS：

  $ python -m venv venv/
  $ source venv/bin/activate
  
  (venv) $ pip3 --version
  pip 24.2 from .../python3.12/site-packages/pip (python 3.12)
  
  (venv) $ pip --version
  pip 24.2 from .../python3.12/site-packages/pip (python 3.12)
  

这里使用 Python 内置的 venv 模块初始化了一个名为 venv 的虚拟环境。Python 会在当前目录下创建一个 venv/ 文件夹。接着通过 source 命令激活虚拟环境。括号 (venv) 表示激活成功。

最后，检查激活环境中 pip3 和 pip 的版本。两者指向同一个 pip 模块，因此激活后可以任选其一。为保持一致性，你也可以继续使用 python -m pip。

出错时重新安装 pip

运行 pip 命令时可能会遇到错误。具体错误信息取决于你的操作系统：

这类错误表明 pip 安装存在问题。

注意：在开始排查之前，可以先尝试使用 pip3 或 python -m pip。

这些错误通常是因为系统无法在 PATH 环境变量中找到 pip。PATH 在 Windows 中是系统变量，在 macOS 和 Linux 中是环境变量。你可以通过以下命令查看 PATH 内容：

• Linux + macOS：

  $ echo $PATH
  

输出会列出操作系统查找可执行程序的目录列表（以冒号或分号分隔）。

正常情况下，pip 所在目录应在安装 Python 或创建虚拟环境后自动加入 PATH。如果缺失，可通过以下两种官方方法重新安装 pip：

1. ensurepip 模块
2. get-pip.py 脚本

ensurepip 自 Python 3.4 起就已内置，用于在跳过安装或意外卸载 pip 时重新安装：

• Linux + macOS：

  $ python -m ensurepip --upgrade
  

如果 pip 未安装，此命令会将其安装到当前 Python 环境；若在虚拟环境中，则安装到该环境。--upgrade 选项确保 pip 版本与 ensurepip 中声明的一致。

注意：ensurepip 不联网，只能安装 Python 安装包中附带的 pip 版本。例如，Python 3.12 附带 pip 24.2。如需更新版本，需先运行 ensurepip，再手动升级 pip。

另一种方法是使用 get-pip.py 脚本。该脚本包含完整 pip 的 ZIP 编码副本，可从 PyPA 引导页 下载。下载后运行：

• Linux + macOS：

  $ python get-pip.py
  

该脚本会安装最新版 pip、setuptools 和 wheel。若只需安装 pip，可添加 --no-setuptools 和 --no-wheel 选项。

如果以上方法均无效，建议重新下载并安装最新版 Python，并参考《Python 安装与设置指南》确保 pip 正确安装。

使用 pip 安装包

Python 被称为“自带电池”的语言，因其标准库提供了大量模块。同时，Python 社区贡献了更多扩展包，发布在 Python Package Index（PyPI） 上。

注意：安装第三方包时需谨慎。可参考《如何评估 Python 包的质量》确保包的安全可靠。

PyPI 托管了大量开发框架、工具和库，许多包为标准库功能提供了更友好的接口。

使用 Python Package Index（PyPI）

以 requests 为例，这是一个简化 HTTP 请求的流行库。要在项目中使用它，需先安装到环境中（建议先创建虚拟环境）。

激活虚拟环境后，命令行提示符会显示环境名（如 (venv)）。此后所有 pip 命令都在该环境中执行。

安装包使用 install 命令：

• Linux + macOS：

  (venv) $ python -m pip install requests
  

pip 会从 PyPI 查找包，解析依赖，并安装到当前环境。

你也可以一次安装多个包：

(venv) $ python -m pip install rptree codetiming

当包数量较多时，使用 requirements.txt 文件更方便（稍后介绍）。

注意：除非特别说明，本教程中的版本号 x.y.z 为占位符，实际输出会显示具体版本。

使用 list 命令查看已安装包：

(venv) $ python -m pip list
Package            Version
------------------ ---------
certifi            x.y.z
charset-normalizer x.y.z
codetiming         x.y.z
idna               x.y.z
pip                x.y.z
requests           x.y.z
rptree             x.y.z
urllib3            x.y.z

使用 show 命令查看包的元数据：

(venv) $ python -m pip show requests
Name: requests
Version: x.y.z
Summary: Python HTTP for Humans.
...
Requires: certifi, idna, charset-normalizer, urllib3
Required-by:

Requires 行列出了 requests 依赖的包。这些包会随 requests 一并安装。

安装完成后，可在 Python 中导入：

>>> import requests
>>> requests.__version__
"x.y.z"
>>> requests.__file__
'.../venv/lib/python3.12/site-packages/requests/__init__.py'

使用自定义包索引

默认情况下，pip 使用 PyPI。但你也可以指定自定义索引，适用于 PyPI 被屏蔽或需使用私有包的情况。

自定义索引需符合 PEP 503 – Simple Repository API。例如，从 TestPyPI 安装 rptree：

(venv) $ python -m pip install -i https://test.pypi.org/simple/ rptree

-i（或 --index-url）指定索引地址。TestPyPI 常用于测试包发布流程。

若需永久使用自定义索引，可在 pip.conf 配置文件中设置：

[global]
index-url = https://test.pypi.org/simple/

配置后，pip 默认使用该索引，无需每次指定 -i。

从 Git 仓库安装包

pip 不仅支持 PyPI，还可从 Git 仓库安装包。例如安装 Real Python 的 rptree：

(venv) $ python -m pip install git+https://github.com/realpython/rptree

git+https 方案指向包含可安装包的 Git 仓库。你也可从公司内网的私有 Git 服务器安装。

以可编辑模式安装包（便于开发）

开发自己的包时，可安装为“可编辑模式”，以便在修改源码的同时正常使用命令行：

$ git clone https://github.com/realpython/rptree
$ cd rptree
$ python -m venv venv/
$ source venv/bin/activate
(venv) $ python -m pip install -e .

-e（或 --editable）选项使 pip 在 site-packages 中创建指向本地项目的链接（如 rptree.egg-link），而非复制文件。这样修改源码后无需重新安装。

使用需求文件（Requirements Files）

默认情况下，pip install 安装最新版包，但有时项目需要特定版本。

固定依赖版本（Pinning Requirements）

为确保开发、测试和生产环境一致，可将依赖及版本记录在 requirements.txt 中。

使用 freeze 命令生成需求文件：

(venv) $ python -m pip freeze > requirements.txt

生成的 requirements.txt 内容如下：

certifi==x.y.z
charset-normalizer==x.y.z
idna==x.y.z
requests==x.y.z
urllib3==x.y.z

在其他环境中，使用以下命令安装相同依赖：

(venv) $ python -m pip install -r requirements.txt

灵活指定版本

硬编码版本会错过安全更新。需求文件支持比较运算符，如 >=：

requests>=2.25.0

升级依赖：

(venv) $ python -m pip install -U -r requirements.txt

若新版本（如 requests 3.0）不兼容，可限制版本范围：

requests>=2.25.0,<3.0

分离生产和开发依赖

开发依赖（如 pytest）不应出现在生产环境。可创建 requirements_dev.txt：

-r requirements.txt
pytest>=6.0.0

-r requirements.txt 表示同时安装生产依赖。

开发环境安装：

(venv) $ python -m pip install -r requirements_dev.txt

生产环境仅安装：

(venv) $ python -m pip install -r requirements.txt

为生产环境冻结依赖

发布前，应冻结确切版本以确保一致性：

requirements_lock.txt 可确保用户使用与你相同的依赖版本。

使用 pip 卸载包

有时需要卸载不再需要的包。注意：卸载前应检查依赖关系。

使用 show 命令查看包信息：

(venv) $ python -m pip show requests
...
Requires: certifi, idna, charset-normalizer, urllib3
Required-by:

Required-by 为空表示无其他包依赖它，可安全卸载。

逐个卸载：

(venv) $ python -m pip uninstall certifi

使用 -y 跳过确认：

(venv) $ python -m pip uninstall urllib3 -y

批量卸载：

(venv) $ python -m pip uninstall -y charset-normalizer idna requests

从需求文件卸载：

(venv) $ python -m pip uninstall -r requirements.txt -y

提示：在虚拟环境中，直接删除整个环境并重建可能比逐个卸载更高效。

pip 的替代工具

Python 社区提供了多种 pip 替代方案：

只有 pip 随 Python 默认安装，其他工具需单独安装。

总结

pip 是 Python 项目依赖管理的核心工具。本教程介绍了：

• 如何设置和运行 pip；
• 如何修复常见错误；
• 如何安装和卸载包；
• 如何使用需求文件管理依赖；
• 如何固定版本并分离开发/生产依赖；
• pip 的替代工具。

掌握 pip 能让你高效管理项目依赖，专注于核心代码开发。