Python requirements.txt文件格式规范与基本用法

在 Python 项目开发与交付过程中，确保不同机器运行相同代码时拥有一致的第三方依赖，是避免“在我的机器上运行正常，部署后就报错”的关键前提。requirements.txt 是 Python 社区中最通用、最直接的依赖声明文件。通过明确的包名与版本运算符约束，配合标准包管理工具 pip，开发者可以实现跨环境的快速依赖安装与环境复现。本文将从具体开发场景切入，系统梳理 requirements.txt 的语法规则、运算符规范、常用命令及多环境拆分实践。

一、requirements.txt 的定位与工作机制

假设你刚刚克隆了一个团队成员编写的 Python Web 项目，本地直接运行启动脚本，终端立即抛出了 ModuleNotFoundError: No module named 'flask' 或由于版本不兼容引发的语法异常。此时，逐个猜解缺失模块不仅耗时，而且极易因安装了错误的主版本导致逻辑隐患。

requirements.txt 的本质是一个纯文本文件，里面按行罗列了项目运行或开发所需的外部依赖包及其版本约束。当执行 pip install -r requirements.txt 时，pip 解析器会自上而下读取每一行配置，解析依赖树，并从 Python 官方包索引（PyPI）或指定镜像源下载并安装对应版本的轮子文件（wheel）或源码包。

图 1：requirements.txt 在 Python 研发、协同与部署周期中的流转关系

二、文件格式规范与语法细节

requirements.txt 遵循 PEP 508 规范及 pip 内部的依赖解析规则。每一行代表一个独立的依赖描述项。了解各项语法成分的作用，可以避免在多平台分发或版本升级时出现解析失败。

图 2：PEP 508 标准单行依赖语法组成结构

1. 基础包名与无约束声明

最简单的格式仅包含软件包名称。此写法不会限制版本，pip 默认下载当前索引源中可用的最新稳定版：

requests
flask
numpy

这种写法在实际工程中存在较高风险，一旦第三方库发布了含有破坏性更改（Breaking Changes）的大版本升级，重新构建项目时可能直接崩溃。

2. 版本比较运算符

为了保障构建稳定性，通常需要使用比较运算符限定依赖包的版本区间：

3. 兼容版本操作符（~=）与多条件组合

~=（Compatible Release）遵循语义化版本号（Semantic Versioning）原则：

• ~= 1.4.2：允许补丁版本升级，匹配 >= 1.4.2, < 1.5.0。
• ~= 1.4：允许次版本升级，匹配 >= 1.4.0, < 2.0.0。

若需要同时设置上限与下限，使用英文逗号分隔多个约束条件即可（逗号表示逻辑与）：

# 允许使用 2.x 系列中 2.25 以上的任意版本，但禁止升级到 3.0
requests >= 2.25.0, < 3.0.0

4. 附加特性（Extras）

部分库为了精简安装体积，将某些不常用的可选模块声明为扩展依赖（Extras）。通过在中括号内指定特性名，可以在安装主库时自动拉取相关扩展：

# 安装 Celery 及其 Redis 消息代理驱动
celery[redis] >= 5.3.0

# 安装 FastAPI 及其常用的 uvicorn、pydantic 等生产套件
fastapi[all] == 0.104.1

5. 环境标记（Environment Markers）

有时某些包只能在特定操作系统运行，或者只针对旧版本 Python 提供向后兼容支持。使用分号 ; 附加环境标记，可以让 pip 自动判断是否在当前机器上执行安装：

# 仅在 Python 3.8 及更低版本上安装 backports 模块
typing-extensions >= 4.5.0; python_version < '3.9'

# 仅在 Windows 系统安装 pywin32，避免 Linux 构建镜像时报错
pywin32 >= 306; sys_platform == 'win32'

# 仅在特定 CPU 架构或平台使用
uvloop >= 0.19.0; sys_platform != 'win32'

6. 直接引用 Git 仓库与本地包文件

在企业内网或使用尚未发布到 PyPI 的开源补丁时，可以直接写入远程仓库或本地源码包路径：

# 引用公开 Git 仓库的特定分支、Tag 或 Commit SHA
git+https://github.com/psf/requests.git@v2.31.0#egg=requests

# 引用本地磁盘上的 wheel 预编译二进制文件
./wheels/custom_package-1.0.0-py3-none-any.whl

# 以可编辑模式（editable mode）引用本地源码目录
-e ./local_library

7. 注释与嵌套引用参数（-r）

行首使用 # 表示注释。此外，使用 -r 选项可以递归导入另一个文件，便于模块化管理：

# 基础核心依赖
-r base.txt

# 测试环境专用补充
pytest >= 7.4.0
coverage >= 7.3.0

三、核心操作与基本用法流程

规范管理 requirements.txt 必须与正确的终端工作流紧密结合。在日常操作中，务必在独立的虚拟环境中操作，防止全局 Python 库被污染。

图 3：基于 requirements.txt 的标准工程操作全流程

1. 导出依赖清单：pip freeze

在已经安装好各模块的虚拟环境中，执行以下命令将当前环境所有已安装的第三方包及其精确版本导出：

# 导出当前虚拟环境的所有已安装包
pip freeze > requirements.txt

2. 按文件安装依赖：pip install -r

在新服务器、CI 节点或同事的工作站上，只需一步命令即可完成全量安装：

# 按照 requirements.txt 的内容批量安装
pip install -r requirements.txt

如果网络环境较慢，可临时或永久指定国内镜像源以提升下载速度：

# 通过国内 PyPI 镜像加速安装过程
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 验证环境健全性：pip check

安装完成后，使用 pip check 可以检验所有已安装包的依赖关系是否自洽：

# 校验环境依赖兼容性
pip check

若输出 No broken requirements found.，说明当前环境内所有包的上下游约束均得到满足；若存在冲突（如 A 包需要 urllib3<2.0，而 B 包安装了 urllib3==2.1.0），命令会明确输出冲突的具体包名及所需版本号。

四、版本控制策略与选型建议

在编写 requirements.txt 时，开发者常面临一个权衡：是写死版本号（==），还是保留灵活范围（>= 或 ~=）？不同的项目类型与使用场景适用不同的策略。

图 4：三种版本约束策略的优缺点与适配场景

五、企业级实战：依赖分层管理方案

在实际团队协作中，开发人员通常需要代码格式化工具（如 black、ruff）、测试框架（如 pytest）以及性能探针，而这些工具不应该打包进轻量化的生产 Docker 镜像中。此时，推荐采用文件拆分方案：

project/
├── requirements/
│   ├── base.txt        # 核心业务共用基础依赖
│   ├── development.txt # 本地开发与调试依赖
│   └── production.txt  # 生产环境专用或严格锁版依赖

各文件的具体书写规范如下：

1. requirements/base.txt（仅包含应用运行必需的核心组件）

# 核心业务框架与工具
fastapi ~= 0.104.0
sqlalchemy >= 2.0.0, < 3.0.0
alembic ~= 1.12.0
pydantic >= 2.4.0

2. requirements/development.txt（开发辅助工具，包含 base.txt）

# 引入基础依赖
-r base.txt

# 本地调试与测试
pytest >= 7.4.0
pytest-asyncio >= 0.21.0
ruff >= 0.1.0
ipdb >= 0.13.0

3. requirements/production.txt（部署环境依赖，引入 base.txt 并添加生产 WSGI/ASGI 服务器）

# 引入基础依赖
-r base.txt

# 生产级进程管理器
uvicorn[standard] == 0.24.0
gunicorn == 21.2.0

在开发环境中执行：

pip install -r requirements/development.txt

而在构建生产容器时，Dockerfile 只需写入：

RUN pip install --no-cache-dir -r requirements/production.txt

这样既精简了容器镜像体积，又避免了开发测试工具引入的安全攻击面。

六、总结

requirements.txt 作为 Python 生态中最经典的依赖管理形式，其规范性直接影响项目的可维护性与交付效率。总结其核心要点如下：

1. 必须基于虚拟环境操作：不论是生成还是安装依赖，严格在 venv 或对应虚拟隔离环境中执行，杜绝全局环境污染。
2. 生产环境严格锁定：交付产物建议锁定精确版本号（==），保证多次构建的完全一致性；而在平时维护中使用 ~= 或范围约束以适度兼顾安全补丁。
3. 合理利用分层拆分：通过 -r 语法划分基础依赖、开发依赖与生产依赖，保持依赖树结构清晰整洁。
4. 养成安装后自检习惯：每次完成批量依赖安装或升级后，运行 pip check 及时识别潜在的版本冲突，从根本上杜绝运行期隐患。