1. 项目概述为什么我们需要一个requirements.txt如果你写过Python项目尤其是和别人协作过大概率遇到过这样的场景你本地跑得好好的代码发给同事或者部署到服务器上一运行就报错提示“ModuleNotFoundError: No module named ‘xxx’”。问题十有八九出在依赖包上——你的环境里装了某个库的特定版本而对方的环境里没有或者版本不匹配。requirements.txt文件就是解决这个问题的“项目依赖清单”。简单来说它是一个纯文本文件里面按行记录了你项目运行所必需的所有第三方Python包及其精确版本。有了它其他人或者未来的你只需要一条命令就能在你的项目根目录下一键复现出完全一致的Python运行环境。这不仅仅是团队协作的基石更是项目可维护性、可复现性的生命线。无论是开发Web应用、数据分析脚本还是机器学习模型管理好依赖都是第一步。从最近的热搜词也能看出大家被环境问题折腾得不轻“pip : 无法将‘pip’项识别为...”、“conda创建虚拟环境”、“vscode python环境配置”... 这些问题很多都能通过规范使用requirements.txt和虚拟环境来避免。接下来我就结合自己多年的踩坑经验把requirements.txt从生成、使用到进阶管理的全流程掰开揉碎讲清楚。2. 核心思路与最佳实践设计在深入具体操作之前我们先要建立一个正确的认知框架。管理Python依赖不是简单记下包名它是一套组合拳核心思路是“隔离”与“锁定”。2.1 虚拟环境依赖管理的基石为什么一定要用虚拟环境想象一下你的电脑是一个大厨房所有Python项目都共用这个厨房的调料第三方库。项目A需要盐库X的1.0版本项目B需要盐的2.0版本。如果你直接在厨房里操作安装2.0版本就会覆盖1.0导致项目A无法运行。虚拟环境的作用就是为每个项目单独开辟一个“小厨房”里面的调料互不干扰。常见的虚拟环境工具有venv Python 3.3 自带轻量、无需额外安装是大多数场景的首选。virtualenv 第三方工具比venv功能更丰富一些比如可以指定不同版本的Python解释器但在Python 3.3之后venv已足够好用。Conda 更重量级的跨平台环境管理工具不仅能管理Python包还能管理非Python的二进制依赖比如某些C库在数据科学和机器学习领域非常流行。注意对于纯Python项目我强烈建议新手从venv开始。它简单、直接没有Conda那些复杂的通道channel概念能让你更专注于Python包管理本身。很多“conda切换环境后不显示”的问题都源于对Conda环境激活机制的不熟悉。2.2 依赖的层次“必须” vs “只需”一个专业的项目依赖清单应该分为至少两个层次生产环境依赖项目运行所必需的最小包集合。比如你的Web应用需要Flask,requests,pandas等。开发环境依赖仅用于开发阶段的工具如代码格式化工具black、测试框架pytest、代码检查工具flake8等。将两者混在一个文件里会导致部署的生产环境安装了许多不必要的包既增加安全风险也浪费资源。成熟的实践是使用两个文件requirements.txt生产依赖和requirements-dev.txt或dev-requirements.txt开发依赖。2.3 版本锁定的艺术精确与灵活requirements.txt里应该写flask还是flask2.3.3这取决于你的目的。精确锁定使用指定确切版本。这是确保环境完全一致的最安全方式常用于生产环境部署或需要绝对复现的科研场景。范围限定使用,,~等操作符。例如flask2.0.0,3.0.0表示接受2.x系列的任何版本。这能在保证基础功能的同时允许在次版本号内自动更新修复一些安全漏洞。不锁定只写flask。这会安装最新版本可能导致未来某天构建突然失败是最不推荐的做法。一个平衡的做法是在项目稳定期使用精确锁定在长期维护的项目中可以结合使用pip-tools这样的工具生成一个锁定文件同时维护一个只写包名和最低版本要求的requirements.in文件。3. 实操全流程从零生成与使用requirements.txt理论说再多不如动手做一遍。我们以一个简单的Flask项目为例走完整个流程。3.1 第一步创建并激活虚拟环境在任何操作之前先为项目创建一个干净的“小厨房”。# 进入你的项目目录 cd my_awesome_project # 使用Python自带的venv创建虚拟环境环境文件夹命名为.venv python -m venv .venv创建完成后需要激活这个环境在Windows上PowerShell:.\.venv\Scripts\Activate.ps1如果遇到执行策略错误可以先以管理员身份运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。在macOS/Linux上:source .venv/bin/activate激活后你的命令行提示符前通常会显示环境名如(.venv)表示你现在安装的任何包都只作用于这个隔离环境。3.2 第二步在虚拟环境中安装项目依赖现在在你的虚拟环境里通过pip install安装项目需要的包。假设我们要开发一个Flask应用。# 激活虚拟环境后安装核心依赖 pip install flask2.3.3 pip install pandas2.0.3 pip install sqlalchemy2.0.19 # 安装开发工具依赖这些不会进入最终的requirements.txt pip install black pip install pytest3.3 第三步生成requirements.txt当所有依赖安装妥当项目运行正常后就是“快照”当前环境的时候了。# 生成包含所有已安装包及其精确版本的清单 pip freeze requirements.txt打开生成的requirements.txt你会看到类似这样的内容blinker1.7.0 click8.1.7 flask2.3.3 itsdangerous2.1.2 jinja23.1.2 markupsafe2.1.3 numpy1.24.3 pandas2.0.3 python-dateutil2.8.2 pytz2023.3 six1.16.0 sqlalchemy2.0.19 werkzeug2.3.7你会发现除了你直接安装的flask、pandas、sqlalchemy文件里还列出了它们的所有间接依赖如click、jinja2、numpy。这是pip freeze的特点它记录当前环境下pip list中的所有包确保环境的完全复现。3.4 第四步使用requirements.txt复现环境现在将你的项目代码和这个requirements.txt文件一起分享给同事或部署到服务器。对方需要做的是克隆或下载你的项目代码。在项目根目录下创建并激活一个新的虚拟环境步骤同3.1。使用一条命令安装所有依赖pip install -r requirements.txt-r参数告诉pip去读取一个需求文件。pip会按照文件中的列表依次安装指定版本的每一个包。完成后他的环境就和你生成这个文件时的环境一模一样了。3.5 第五步生成开发环境依赖文件为了分离生产与开发依赖我们可以再生成一个开发专用的需求文件。# 假设我们只需要记录black和pytest作为开发依赖 # 我们可以手动创建 requirements-dev.txt并写入 # -r requirements.txt # black23.9.1 # pytest7.4.3 # 或者也可以用pip freeze配合grepLinux/macOS来筛选但手动维护更清晰-r requirements.txt这一行表示“首先安装requirements.txt中的所有依赖”这是一种优雅的继承方式。团队新成员只需要运行pip install -r requirements-dev.txt就能一键获得完整的开发环境。4. 进阶技巧与深度管理掌握了基础操作我们来看看如何更专业地管理依赖处理那些令人头疼的边缘情况。4.1 处理复杂的依赖来源私有仓库与本地包有时依赖包不在PyPI上可能来自公司的私有仓库或者是你自己开发的、尚未上传的本地包。对于私有仓库可以在requirements.txt中使用--index-url或--extra-index-url指定源但更规范的做法是在用户家目录或项目根目录配置pip.conf文件。不过直接在requirements.txt中指定也是一种方式--extra-index-url https://your-private-repo.com/simple/ flask2.3.3 your-private-package1.0.0对于本地包可以使用-e可编辑模式安装这在开发另一个关联库时非常有用。# 安装本地位于../my_library目录下的包 pip install -e ../my_librarypip freeze会将其记录为-e githttps://github.com/you/my_library.gitabcdef#eggmy_library # 或者对于本地路径 -e file:///Users/you/projects/my_library注意这种路径是绝对路径迁移到其他机器时会失效。通常可编辑安装的包更适合记录在开发依赖中生产环境应使用版本化的包。4.2 依赖冲突的排查与解决当你运行pip install -r requirements.txt时最常遇到的错误就是“依赖冲突”。例如包A需要numpy1.20而包B需要numpy1.24pip无法找到一个同时满足两个条件的版本。解决策略查看错误信息pip通常会给出非常详细的冲突报告指出是哪些包在哪个依赖上产生了冲突。回溯依赖树使用pip show package_name查看某个包的具体依赖要求或用pipdeptree工具需安装可视化整个依赖关系。pip install pipdeptree pipdeptree尝试升级或降级冲突包找到冲突的核心包尝试在requirements.txt中将其固定到一个能兼容其他依赖的版本。这可能需要一些试错。使用pip-compile来自pip-tools这是更高级的解法。你只在一个requirements.in文件里写下直接依赖如flask、pandas然后运行pip-compile requirements.in它会自动计算出一个兼容所有子依赖的、锁定的requirements.txt。当你想更新时修改.in文件再重新编译即可。4.3 保持依赖的更新与安全长期项目不能永远锁死版本需要定期更新依赖以获得新功能和安全补丁。安全更新可以使用pip list --outdated查看有哪些包有可用更新。对于只修复bug和安全漏洞的“补丁版本”更新如从2.3.3到2.3.4通常可以比较放心地更新。批量测试更新创建一个虚拟环境的副本在其中运行pip install --upgrade -r requirements.txt然后运行你的全套测试单元测试、集成测试。确保所有测试通过后再生成新的requirements.txt并应用到主环境。使用依赖分析工具像safety、dependabotGitHub集成或renovate这样的工具可以自动扫描你的依赖已知的安全漏洞并提示甚至自动创建更新PR。5. 常见问题与避坑指南实录这里记录了我自己和团队在多年实践中踩过的坑和总结出的经验。5.1 问题pip freeze生成的文件包含无关的系统级包场景你没有在虚拟环境中操作直接在全局Python环境下运行了pip freeze导致生成的requirements.txt包含了操作系统或其他项目需要的包文件臃肿且可能引发冲突。根因与解决这绝对是新手最高频的错误。务必、务必、务必先激活虚拟环境再执行pip freeze。每次操作前看一眼命令行提示符是否有(.venv)之类的字样。一个良好的习惯是在项目根目录的README.md中明确写出创建和激活虚拟环境的命令。5.2 问题部署时安装超时或速度极慢场景在生产服务器上执行pip install -r requirements.txt因为网络连接到PyPI速度慢而失败或耗时极长。解决方案使用国内镜像源这是最有效的提速方法。在安装命令后添加-i参数指定镜像。pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple常用的国内镜像有清华、阿里云、豆瓣等。你也可以将镜像源配置为默认一劳永逸# Linux/macOS: ~/.pip/pip.conf # Windows: %USERPROFILE%\pip\pip.ini # 内容 [global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn使用pip download预先下载在构建机或本地网络好的环境先将所有依赖包下载到wheelhouse目录。pip download -r requirements.txt -d ./wheelhouse然后将整个wheelhouse目录上传到服务器从本地目录安装pip install --no-index --find-links./wheelhouse -r requirements.txt这种方式也适用于完全离线的内网部署环境。5.3 问题跨平台兼容性问题场景你在macOS上开发生成了requirements.txt里面包含了一些包的特定版本。同事在Windows上安装时某个包没有提供Windows平台的预编译轮子wheel需要从源代码编译而编译依赖的C/C库在Windows上缺失导致安装失败。根因有些包特别是包含C扩展的如numpy,pandas,cryptography早期版本会为不同平台提供预编译的.whl文件。pip freeze记录的版本可能对应一个只有你当前平台有预编译轮的版本。解决方案尽量使用“宽松”的上限在requirements.in或手动维护的requirements.txt中对于底层核心库可以只写最低版本要求让pip在目标平台上选择最适合的、有预编译轮的版本。使用--platform标志下载通用轮子在CI/CD流水线中可以指定为manylinuxLinux、win32Windows等平台下载轮子。文档说明在README中明确指出项目依赖并提示在Windows上可能需要安装Visual C Build Tools或相应的编译环境。5.4 问题依赖文件臃肿包含大量间接依赖争议点pip freeze会把所有依赖包括间接依赖都打平列出导致文件很长且难以区分哪些是项目的直接依赖。我的经验对于中小型项目或应用部署我仍然推荐使用pip freeze。因为它提供了最强的环境确定性。虽然文件看起来臃肿但确保了百分百的复现。区分直接/间接依赖是开发者的责任可以通过维护一个简洁的README或requirements.in文件来实现。对于大型库Library项目情况不同。库的requirements.txt通常放在requirements文件夹下用于测试可以包含间接依赖但它在setup.py或pyproject.toml中声明的安装依赖install_requires应该只包含其直接、必须的依赖并且版本范围应尽可能宽松以免给使用者带来冲突。5.5 一个被忽视的细节python_version约束如果你的项目同时支持Python 3.8和3.9但某个依赖在3.8和3.9上需要不同的版本怎么办在requirements.txt中你可以使用环境标记Environment Markers。requests2.31.0 typing-extensions4.8.0; python_version 3.8上面这行表示只有当Python版本小于3.8时才安装typing-extensions4.8.0。这在维护需要兼容多个Python版本的项目时非常有用。不过更现代的做法是在pyproject.toml中使用project.optional-dependencies来定义不同环境下的依赖组。6. 现代项目管理从requirements.txt到pyproject.toml随着Python打包标准的演进社区正逐渐从传统的setup.pyrequirements.txt模式转向使用pyproject.toml文件PEP 621。这个文件不仅能定义项目元数据和构建系统还能声明项目依赖。一个简单的pyproject.toml依赖声明如下[project] name my-project version 0.1.0 dependencies [ flask2.3.0, pandas2.0.0, ] [project.optional-dependencies] dev [ black23.0, pytest7.0, ] test [ pytest7.0, ]优势单一文件元数据和依赖定义合一。声明式只声明直接依赖和宽松版本更清晰。工具生态pip、pdm、poetry、hatch等现代工具都支持它。那么requirements.txt过时了吗并没有。pyproject.toml定义了“需要什么”而requirements.txt通常由工具根据pyproject.toml生成锁定了“具体是什么”。在CI/CD或生产部署中使用锁定的requirements.txt来安装依然是最可靠的做法。你可以用pdm或poetry这样的工具来生成锁文件pdm.lock/poetry.lock它们比pip freeze生成的requirements.txt包含更多解析信息也能更好地处理依赖关系。我个人在实际项目中的混合策略是使用pyproject.toml管理项目元数据和直接依赖声明使用pdm或pip-tools来生成一个锁定的requirements.txt或requirements.lock用于部署。这样既享受了现代标准的清晰也保留了传统工作流的稳定和广泛兼容性。