如果你使用 Python 一段时间，你一定对 requirements.txt 文件不陌生。
pip freeze > requirements.txt 这条命令，可能是很多开发者管理依赖的起点。它简单直接，能够锁定环境中所有包的精确版本，确保环境的可复现性。

但这真的是最佳实践吗？

想象一下，你的 requirements.txt 文件里有几十上百行，里面混杂着 pandas、pytz、numpy、six… 你还记得当初为什么需要安装 six 吗？当你想要升级 pandas 时，应该如何安全地处理它所有的下游依赖？

pip freeze 带来的最大问题是：它混淆了项目的直接依赖与间接依赖，让依赖关系变得模糊不清，给长期维护带来了噩梦。

今天，我们将介绍一个能彻底改变这一现状的工具 —— pip-tools。它的核心哲学非常简单：将你的“意图”（直接依赖）与最终的“锁定环境”（所有依赖）分离开，让依赖管理变得前所未有的清晰和可控。

---

一、 为你的项目生成依赖文件

作为项目的创建者和维护者，你的目标是建立一个清晰、可维护且易于他人复现的依赖环境。pip-tools 将帮助你完美地实现这一点。

步骤 1：搭建基础环境并安装 pip-tools

一如既往，我们从创建一个干净的虚拟环境开始。

# 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
------------------------------------------------------------
conda create -n myproject python=3.x
conda activate myproject
------------------------------------------------------------
# 安装 pip-tools
pip install pip-tools

步骤 2：创建 requirements.in，声明你的“意图”

现在，你需要手动创建一个 requirements.in 文件。这是整个流程的核心，你只需在这里列出你的项目直接需要的包。

# requirements.in

# 数据处理核心
pandas

# 网络请求库
requests

# Web 框架
flask>=2.0
...

这个文件就是你项目的“依赖蓝图”，清晰地告诉了所有人，这个项目直接依赖这三个库。

步骤 3：使用 pip-compile “编译”锁定文件

接下来，运行 pip-compile 命令，它会读取你的“蓝图”并生成一份详尽的“施工计划”——requirements.txt。

pip-compile requirements.in

命令执行后，一个内容丰富、注释清晰的 requirements.txt 文件就诞生了。它包含了 pandas, requests, flask 以及它们背后的所有子依赖，并且全部锁定了精确的版本号，甚至还通过 # via ... 注释标明了每个包的来源。

这个自动生成的 requirements.txt 文件，才是你应该提交到版本控制（如 Git）中的锁定文件。

步骤 4：维护你的依赖

随着项目的迭代，依赖管理是持续性的工作。pip-tools 让这个过程变得非常简单。

• 添加新依赖：

  1. 将新的包（如 scipy）添加到 requirements.in。
  2. 重新运行 pip-compile 来更新 requirements.txt。

• 移除依赖：

  1. 从 requirements.in 中删除不再需要的包。
  2. 重新运行 pip-compile。

• 更新依赖：

  • 全部更新到最新：只需再次运行 pip-compile。
  • 只更新特定包：使用 --upgrade-package 标志，例如 pip-compile --upgrade-package pandas。

完成上述任何操作后，你本地的环境可能与 requirements.txt 不一致了。此时，你可以运行 pip-sync 命令来使你的环境与 requirements.txt 完美同步。

---

二、 使用别人的项目依赖文件

现在，切换到协作者或用户的视角。当你从 GitHub 克隆一个使用 pip-tools 管理依赖的仓库时，你会发现项目里已经有了 requirements.in 和 requirements.txt。

你的任务就简单多了：完美复现作者定义好的环境。

步骤 1：创建并激活虚拟环境

这依然是必不可少的第一步。

git clone <repository_url>
cd <repository_name>
-----------------------------------------
python -m venv venv
source venv/bin/activate
-----------------------------------------
conda create -n myproject python=3.x
conda activate myproject
-----------------------------------------

步骤 2：安装依赖

此时，你的目标是 requirements.txt 这个已经由项目作者为你准备好的、精确的“配方”。

你可以使用 pip 的常规命令来安装：

pip install -r requirements.txt

这会安装所有在文件中列出的、版本精确的包，确保你得到和作者几乎完全一致的环境。

步骤 3：（推荐）使用 pip-sync 保持环境纯净

为了达到最严格的环境一致性，我们推荐使用 pip-tools 提供的 pip-sync 命令。它不仅会安装所有需要的包，还会卸载任何“多余”的包。

# 你需要先安装 pip-tools 才能使用 sync 命令
pip install pip-tools

# 同步环境，不多也不少
pip-sync

通过 pip-sync，你可以确信你的本地环境与项目的 requirements.txt 文件是 100% 的镜像，有效避免了“在我电脑上能跑”的经典难题。

总结

通过 pip-tools，我们将依赖管理流程清晰地划分为两个角色：

• 项目维护者：通过维护简洁的 requirements.in 来表达意图，并使用 pip-compile 生成精确的 requirements.txt 锁定文件。
• 项目使用者：直接利用 requirements.txt 文件，通过 pip install 或 pip-sync 快速、准确地复现开发环境。

这种工作流分离带来了巨大的好处：清晰的依赖关系、可复现的环境和极低的维护成本。如果你还在为混乱的依赖所困扰，现在就是拥抱 pip-tools 的最佳时机。