Python 依赖管理：requirements.txt 从安装到实战

1. 在项目根目录下，新建一个名为 requirements.txt 的文本文件（无后缀，纯文本）。

按'包名==版本号'的格式，逐行写入依赖。例如：

# 注释：项目基础依赖
flask==2.3.3 # Web 框架，指定 2.3.3 版本
requests>=2.31.0 # HTTP 请求库，最低 2.31.0 版本
pandas~=2.1.0 # 数据分析库，兼容 2.1.x 系列版本

版本号写法说明（关键！）

版本号的指定决定了依赖的兼容性，常见写法有 3 种：

• ==x.y.z：精确版本（推荐），强制安装指定版本，避免版本兼容问题。
• >=x.y.z：最低版本，安装不低于该版本的最新版，适合对版本不敏感的依赖。
• ~=x.y.z：兼容版本，允许升级到同系列的小版本（如 ~=2.1.0 可安装 2.1.1、2.1.9，但不支持 2.2.0）。

场景 2：已有项目（自动生成，主要使用场景）

如果项目已开发一段时间，手动记录依赖太麻烦，可借助 pip freeze 命令自动生成 requirements.txt，但有个重要前提：先激活项目的虚拟环境（否则会把全局所有 Python 包都列出来，导致文件冗余）。

步骤 1：创建并激活虚拟环境（关键！）

虚拟环境能隔离不同项目的依赖，避免全局包污染。以 Python 自带的 venv 为例：

# 1. 在项目根目录创建虚拟环境（venv 是环境目录名，可自定义）
python -m venv venv
# 或 python3 -m venv venv

# 2. 激活虚拟环境
# Windows（命令提示符）：
venv\Scripts\activate
# Windows（PowerShell）：
.\\venv\Scripts\Activate.ps1
# macOS/Linux：
source venv/bin/activate

激活成功后，终端前缀会出现 (venv)，表示当前处于虚拟环境中。

步骤 2：安装项目依赖（若未安装）

在虚拟环境中，安装项目所需的所有依赖（比如 pip install flask requests），确保项目能正常运行。

步骤 3：自动生成 requirements.txt

执行以下命令，将当前虚拟环境中的所有依赖（及其版本）写入 requirements.txt：

pip freeze > requirements.txt

此时打开项目根目录，会发现已生成 requirements.txt，内容类似：

进阶：用 pipreqs 生成更精简的依赖（推荐）

pip freeze 会列出虚拟环境中的所有依赖（包括项目间接依赖的包，比如安装 flask 时自动安装的 werkzeug），导致 requirements.txt 冗余。而 pipreqs 工具能只识别项目代码中实际导入的包，生成更精简的依赖清单。

使用 pipreqs 的步骤：

进入项目根目录，执行命令生成 requirements.txt：

# --encoding=utf8 解决中文注释编码问题
pipreqs . --encoding=utf8

安装 pipreqs：

pip install pipreqs

例如，若项目代码中只导入了 flask 和 requests，pipreqs 生成的文件会只有这两个包，比 pip freeze 更简洁。

使用 requests 生成：

使用 pipreqs 生成：

四、核心操作：用 requirements.txt 安装依赖

当你拿到一个带有 requirements.txt 的项目（比如从 GitHub 下载），只需一条命令即可安装所有依赖。

步骤 1：激活虚拟环境（可选但推荐）

和生成时一样，先在项目根目录创建并激活虚拟环境（避免污染全局依赖）。

步骤 2：安装所有依赖

执行以下命令，pip 会自动读取 requirements.txt 中的内容，安装所有指定包和版本：

pip install -r requirements.txt

常用扩展参数

• 使用国内镜像源（提速）：国内直接访问 PyPI 可能较慢，可指定清华、阿里等镜像源：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

• 不缓存安装包（节省空间）：适合 CI/CD 或临时环境，避免缓存冗余包：

pip install -r requirements.txt --no-cache-dir

• 升级依赖：如果想将依赖升级到 requirements.txt 指定版本范围内的最新版（需配合 >= 或 ~= 写法）：

pip install --upgrade -r requirements.txt

执行命令安装之后，原有的依赖报错就被解决了。

五、进阶技巧：管理多环境依赖

实际开发中，项目可能需要区分开发环境和生产环境的依赖（比如开发时需要 pytest 做测试，生产环境不需要）。这时可以创建多个 requirements 文件。

示例：多环境依赖文件结构

your_project/
├── requirements.txt # 生产环境依赖（核心依赖，如 flask、requests）
└── requirements-dev.txt # 开发环境依赖（额外依赖，如 pytest、flake8）

1. requirements.txt（生产环境）

flask==2.3.3
requests==2.31.0
pandas==2.1.0

2. requirements-dev.txt（开发环境）

# 先包含生产环境依赖
-r requirements.txt
# 再添加开发专属依赖
pytest==7.4.3 # 测试框架
flake8==6.1.0 # 代码规范检查
black==23.10.1 # 代码格式化工具

3. 安装对应环境的依赖

• 生产环境安装：pip install -r requirements.txt
• 开发环境安装：pip install -r requirements-dev.txt

六、常见问题与解决方案

问题 1：执行 pip install -r 时报'版本冲突'

原因：不同依赖包对同一个子依赖的版本要求不一致（比如 A 包需要 requests<2.30，B 包需要 requests>=2.31）。解决方案：

1. 用 pipdeptree 查看依赖树，定位冲突来源：pip install pipdeptree && pipdeptree。
2. 手动调整冲突包的版本，找到一个双方都兼容的版本（比如将 A 包升级到支持 requests>=2.31 的版本）。

问题 2：pip freeze 生成的依赖太多，包含无用包

原因：未激活虚拟环境，导致全局依赖被写入。解决方案：

1. 删除现有 requirements.txt。
2. 按步骤创建并激活项目专属虚拟环境，重新安装依赖后用 pip freeze 生成。
3. 或直接用 pipreqs 生成精简版依赖。

问题 3：Windows 下激活虚拟环境提示'权限不足'

原因：PowerShell 默认禁止执行脚本。解决方案：

1. 以'管理员身份'打开 PowerShell。
2. 执行命令修改执行策略：Set-ExecutionPolicy RemoteSigned，输入 Y 确认。
3. 重新激活虚拟环境：.\venv\Scripts\Activate.ps1。

七、总结

requirements.txt 看似简单，却是 Python 项目规范化、可移植的关键。掌握它的核心流程：

1. 准备：确保 pip 最新，用虚拟环境隔离依赖。
2. 生成：新项目手动写，老项目用 pip freeze 或 pipreqs 自动生成。
3. 安装：pip install -r requirements.txt 一键还原环境。
4. 进阶：用多文件管理开发 / 生产环境依赖。

养成在 Python 项目中使用 requirements.txt 的习惯，能极大减少环境不一致带来的麻烦，让协作和部署更高效。