Python依赖管理神器requirements.txt从安装到实战完全指南

前言

在 Python 开发中，你是否遇到过这样的窘境：本地跑通的项目，部署到服务器就报错？同事传的代码，在你电脑上却因 “缺少模块” 无法运行？这些问题的根源，大多是依赖环境不一致。而requirements.txt，就是 Python 生态中解决依赖管理的 “标准配置”。今天这篇文章，从基础概念到实战操作，带你彻底掌握它的使用。

一、先搞懂：什么是 requirements.txt？

requirements.txt是一个纯文本文件，用于记录 Python 项目所依赖的所有第三方包及其精确版本号。它的核心作用是：

• 统一环境：确保开发、测试、生产环境使用完全相同的依赖版本，避免 “本地能跑，线上崩了” 的问题。
• 简化协作：新人接手项目时，无需手动逐个安装依赖，一条命令即可搞定所有依赖。
• 方便部署：在服务器或容器中部署项目时，快速还原依赖环境。

简单来说，它就像项目的 “依赖清单”—— 有了这份清单，无论在哪个环境，都能快速复刻出项目需要的 “运行土壤”。

二、准备工作：确保 pip 已安装（核心工具）

requirements.txt的使用完全依赖 Python 的包管理工具pip（Python Package Installer），所以第一步要确保pip已正确安装并升级到最新版。

1. 检查 pip 是否安装

打开终端（Windows 用 “命令提示符” 或 PowerShell，macOS/Linux 用 “终端”），输入以下命令：

pip --version  # 或 pip3 --version（区分Python2和Python3）

如果输出类似pip 24.0 from /usr/local/lib/python3.11/site-packages/pip (python 3.11)，说明pip已安装；若提示 “命令不存在”，则需要先安装pip。

2. 安装 / 升级 pip

pip通常随 Python 3.4 + 版本默认安装，若未安装或版本过旧，按以下步骤操作：

• Windows/macOS/Linux 通用升级命令：

  # 升级pip到最新版
  python -m pip install --upgrade pip
  # 若系统同时有Python2和Python3，用python3指定Python3
  python3 -m pip install --upgrade pip

三、核心操作：生成 requirements.txt

根据项目状态，生成requirements.txt有两种常见场景：新项目手动创建、已有项目自动生成。

场景 1：新项目（从零开始）

如果项目刚起步，依赖较少，可直接手动创建requirements.txt文件：

• 在项目根目录下，新建一个名为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 的步骤：

• 安装 pipreqs：

  pip install pipreqs
  

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

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

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

使用requests生成：

使用pipreqs生成：

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

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

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

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

步骤 2：安装所有依赖

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

pip install -r requirements.txt

常用扩展参数

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

  pip install --upgrade -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

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

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

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

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

plaintext

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）。解决方案：

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

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

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

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

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

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

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

七、总结

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

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

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

到此这篇关于Python依赖管理神器requirements.txt从安装到实战的文章就介绍到这了,更多相关Python依赖管理神器requirements.txt内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

最新评论