venv 依赖管理实战:pip 与 requirements.txt
开篇:依赖管理是 venv 的下半场
上一篇我们把 venv 虚拟环境建好、激活、退出都走了一遍,环境隔离的问题解决了。但真正到了写项目的时候,麻烦往往出在依赖上:本地跑得好好的代码,换台机器就报 ImportError;三个月前装的包,今天重装变成了另一个版本,行为还不一样;同事拉下代码,第一句问的就是"你都装了哪些包"。
这些问题的答案都收敛到同一件事上:把依赖写下来、锁住版本、能一键还原。Python 生态给出的标准工具就是 pip 加 requirements.txt。本文把这条链路完整走一遍:激活环境后先升级 pip,pip 装包卸包查包的基本功,用 pip freeze 冻结依赖清单、用 pip install -r 一键还原,版本号 ==、>=、~= 三种写法的区别,用 pip check 排查依赖冲突,国内镜像源的临时与持久两种配法,最后是生产依赖与开发依赖分文件、pip-tools 进阶,以及换机器上线时验证环境一致的方法。
示例统一使用 requests、flask 这类真实通用包名,命令在 Linux/macOS 下以 bash 演示,Windows 差异处用 PowerShell 标注。默认你已经按上一篇的方法建好并激活了名为 .venv 的虚拟环境,命令提示符前能看到 (.venv) 标记。
前置条件
开始之前,确认三件事:
- 虚拟环境已激活。没激活时 pip 装的包会落到系统 Python 里,本文所有操作都失去意义。判断标准是提示符前的 (.venv) 前缀,或执行 which python(Windows 用 Get-Command python)看路径是否指向项目里的 .venv 目录。
- 知道当前 pip 的版本和位置,用 python -m pip --version 查看,输出里会同时给出 pip 版本和它所属的 Python 路径。
- 项目目录下准备好一个空文件夹放实验代码即可,本文的包都装进 .venv,不污染系统环境,随便折腾。
还有一个习惯要先立起来:本文所有 pip 命令都写成 python -m pip 的形式,原因下一节就讲。
分步操作
一、激活环境后,第一件事是升级 pip
venv 新建环境时自带的 pip 往往是 Python 发行时打包的旧版本。旧 pip 有几个实际问题:解析依赖的速度慢、遇到新格式的安装包(wheel 元数据版本较新)可能直接报错、依赖冲突时的提示信息含糊。所以每个新环境建好后,先把 pip 本身升级到最新:
# 查看当前版本
python -m pip --version
# 升级 pip 本身
python -m pip install --upgrade pip
# 升级后再次确认
python -m pip --version
为什么推荐 python -m pip 而不是直接敲 pip?三个原因。第一,指向明确:一台机器上可能装了多个 Python,直接敲 pip 时它到底属于哪个 Python 取决于 PATH 顺序,装错环境是新手最常见的事故;python -m pip 则保证用的是当前这个 python 对应的 pip,绝不会串。第二,Windows 上的自举问题:pip 升级自己时需要替换正在运行的 pip 可执行文件,Windows 下文件被占用会失败,而 python -m pip 方式绕开了这个坑,官方文档也明确推荐。第三,习惯一致:在 venv 里 python 指向的就是环境内的解释器,命令天然落在正确的环境里。把 python -m pip 练成肌肉记忆,后面所有命令都省心。
二、pip 基本功:装、卸、查、看
日常用得最多的就四个动作。先装两个示例包:
# 安装最新版
python -m pip install requests
# 安装指定版本
python -m pip install flask==3.0.3
# 一次装多个
python -m pip install requests flask
# 升级某个包到最新
python -m pip install --upgrade requests
# 卸载(会要求确认,加 -y 直接确认)
python -m pip uninstall flask
python -m pip uninstall -y flask
查和看用 list 与 show。list 列出环境里所有已装包及版本,是排查"到底装了什么"的第一手段;加 --outdated 还能列出哪些包有新版本可升。show 看单个包的详情:版本、安装位置、它依赖谁、谁依赖它(Requires 和 Required-by 两行最有用,判断一个包能不能卸就看 Required-by 是否为空)。
# 列出全部已装包
python -m pip list
# 只看有新版本可升级的包
python -m pip list --outdated
# 查看某个包的详细信息
python -m pip show requests
show 的典型输出长这样,注意 Requires 一行:requests 自己还依赖 urllib3、certifi 等包,这些"间接依赖"后面冻结清单时也会一并出现,先有个印象。
Name: requests
Version: 2.32.3
Summary: Python HTTP for Humans.
Location: /path/to/project/.venv/lib/python3.12/site-packages
Requires: certifi, charset-normalizer, idna, urllib3
Required-by:
三、冻结与还原:requirements.txt 全流程
项目写了一阵子,环境里装了十几个包。现在要把这份环境"存档",发给同事或部署到服务器。命令只有一条:
# 把当前环境全部包及精确版本写入 requirements.txt
python -m pip freeze > requirements.txt
# 看看冻结出来的内容
cat requirements.txt
freeze 的输出会把直接依赖和间接依赖一视同仁地全部列出,且全部用 == 锁死精确版本,大致如下:
blinker==1.8.2
certifi==2024.8.30
charset-normalizer==3.3.2
click==8.1.7
Flask==3.0.3
idna==3.10
itsdangerous==2.2.0
Jinja2==3.1.4
MarkupSafe==2.1.5
requests==2.32.3
urllib3==2.2.3
Werkzeug==3.0.4
你只手动装了 flask 和 requests 两个包,清单里却有十二个——多出来的都是它们的间接依赖。这正是 freeze 的价值:还原时连间接依赖的版本都一模一样,最大限度复现原环境。把 requirements.txt 提交到 Git 仓库里,它就是这个项目依赖的"账本"。
还原是反向操作。在一台新机器(或新克隆的项目目录)里,先建好并激活一个干净的 venv,然后一条命令按清单装齐:
# 新机器上:建环境并激活
python3 -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
# 按清单一键还原全部依赖
python -m pip install -r requirements.txt
这套"freeze 出清单、install -r 还原"的组合,就是 Python 项目交付依赖的标准姿势,后面讲的上线验证也建立在它之上。
四、版本号写法:==、>=、~= 的区别
requirements.txt 不一定非要 freeze 生成,也可以手写。手写时每行一个包加版本约束,写法不同,语义差别很大:
requests==2.32.3 # 精确锁定,只装 2.32.3 这一个版本
requests>=2.28 # 下限约束,装 >=2.28 的最新版(可能是 2.32、也可能是将来的 3.x)
requests~=2.32.3 # 兼容版本,>=2.32.3 且 <2.33,即只允许补丁号变动
flask # 不写约束,永远装当前最新版
三者的取舍:== 是复现之王,freeze 生成的全是 ==,部署、交付、CI 里用它,保证每次装出来的环境分毫不差,代价是升级要手动改。>= 只设下限,看似灵活,实则把版本决定权交给了"安装那一天的最新版",今天装和下月装结果不同,还可能被某个大版本的不兼容更新打个措手不及,正式项目里慎用。~= 是折中,~=2.32.3 允许 2.32.x 系列内的补丁更新(安全修复能跟上),又挡住 2.33 的功能变更,适合手写维护的长期项目。不写约束等于裸奔,只在临时实验时用。经验法则:部署用的清单一律 ==,手写顶层依赖时可用 ~= 并配合下一节的 pip-tools 收敛。
五、pip check:把依赖冲突查出来
包越装越多,冲突迟早会出现:A 包要求 urllib3 小于 2.0,B 包又要求大于等于 2.0,pip 安装时虽然会给出警告,但环境可能已经处于"装上了却互相打架"的状态。事后体检用 pip check:
# 检查当前环境是否存在依赖不满足的情况
python -m pip check
# 一切正常时输出:No broken requirements found.
有问题时它会逐条列出谁要求什么、实际装的什么版本。处理冲突的思路是:找到冲突双方,把版本约束收敛到两者都接受的区间(通常升级或降级其中一方),改完后重装并再跑一次 pip check 确认干净。把 pip check 加进你的交付检查单——每次 freeze 之前、部署之后各跑一次,能拦下大部分"在我机器上是好的"式故障。
六、国内镜像源:下载慢先换源
pip 默认从 PyPI 官方源下载,国内网络下经常慢到超时。换国内镜像是最有效的解法,分临时和持久两档。临时换源只在单条命令上加 -i 参数,适合偶尔装个包:
# 本次安装走清华镜像
python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple requests
# 还原清单时同样可以临时换源
python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
天天用就写进配置文件一劳永逸。推荐用 pip config 命令写入,它会自动找到正确的配置文件位置:
# 持久设置全局镜像源
python -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 查看当前生效的配置
python -m pip config list
配置文件也可以手动编辑,内容就是一个 ini 风格的片段。Linux/macOS 的位置是 ~/.config/pip/pip.conf,Windows 是 %APPDATA%\pip\pip.ini(即 C:\Users\你的用户名\AppData\Roaming\pip\pip.ini,目录不存在就新建):
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
几点说明:本文以清华大学镜像为例,你也可以换成阿里云、中科大、华为云等任一可信镜像,地址替换即可;公司有内网私服(如 Nexus、Artifactory 搭的 PyPI 代理)时填内网地址同理。另外注意作用域:在 venv 激活状态下执行 pip config set,配置仍写在用户级配置文件里,对所有环境生效;如果只想给某个项目单独配,可以在项目目录放一份 pip.conf 并用 --config-file 指定,或设置环境变量 PIP_INDEX_URL,优先级高于配置文件。切回官方源时把 index-url 改回 https://pypi.org/simple 或直接删掉该行。
七、依赖分文件:生产与开发分开
项目里的包分两类:一类是程序运行必需的(flask、requests),叫生产依赖;另一类只在开发时用(测试框架 pytest、格式化工具 black、类型检查 mypy),叫开发依赖。把开发依赖也装进生产服务器,只会让镜像变大、攻击面变广、部署变慢。标准做法是拆成两个文件:
# requirements.txt —— 生产依赖,只放运行必需的包
flask==3.0.3
requests==2.32.3
# requirements-dev.txt —— 开发依赖
# 第一行用 -r 引入生产依赖,开发环境一次装齐两边
-r requirements.txt
pytest==8.3.3
black==24.8.0
用法随之分开:开发机上装 python -m pip install -r requirements-dev.txt,一次得到完整开发环境;生产部署只装 python -m pip install -r requirements.txt,干净利落。注意 freeze 时要小心:在开发环境里执行 freeze 会把开发依赖也冻进去,所以冻结生产清单前,想清楚当前环境里装的到底是哪一类;更稳妥的做法是下一节的 pip-tools。
八、进阶:pip-tools 只记顶层依赖
freeze 有个固有毛病:它把间接依赖和直接依赖混在一起全量导出。过段时间回头看清单,没人分得清哪几个包是自己真正需要的,哪几个是被带进来的,删也不敢删。pip-tools 的思路是把"人写的"和"机器生成的"分开:你在一个 .in 文件里只写顶层依赖(可以带 ~= 这类弹性约束),运行 pip-compile 后,它解析出包含全部间接依赖、全部 == 锁死的 requirements.txt。
# 安装 pip-tools(它提供 pip-compile 命令)
python -m pip install pip-tools
# requirements.in 里只写顶层依赖,例如 flask、requests 两行
# 编译生成锁死的 requirements.txt
pip-compile requirements.in
# 升级某个包后重新编译即可
pip-compile --upgrade-package requests requirements.in
生成的 requirements.txt 里还会用注释标明每个间接依赖"是被谁带进来的",可读性远胜 freeze 的裸清单。团队协作和长期维护的项目值得上这套;个人小项目用 freeze 也完全够用,别为工具而工具。
九、换机器与上线:还原后这样验证
清单交出去只是第一步,还原后必须验证环境真的对齐,三板斧:
# 1. 依赖完整性:应输出 No broken requirements found.
python -m pip check
# 2. 版本对账:把新环境的冻结结果与仓库里的清单 diff
python -m pip freeze > /tmp/freeze-new.txt
diff requirements.txt /tmp/freeze-new.txt && echo "版本完全一致"
# 3. 冒烟测试:关键包能正常导入
python -c "import flask, requests; print(flask.__version__, requests.__version__)"
三步都过,再跑项目自己的启动命令或测试套件。若 diff 有差异,多半是还原时混用了系统 pip、或没在 venv 里执行安装,回看命令历史里 python -m pip 的 python 指向即可定位。
验证
把全流程自己走一遍确认掌握:新建一个临时 venv,装 requests 和 flask,freeze 出 requirements.txt;再删掉这个 venv,重建一个干净的,用 install -r 还原,最后 pip check 加 diff 对账。两个环境的冻结结果逐行一致、pip check 无报错、示例代码能 import 成功,依赖管理这条链路就算通了。
常见问题
freeze 出来的清单里有 pip、setuptools 之类我没装过的包?不同 Python 版本行为不同,新版本 venv 默认不再把 pip、setuptools 列入 freeze;若看到 pkg-resources 这类残留行,删掉该行即可,它是旧 setuptools 的历史包袱。
install -r 时某个包死活装不上、报编译错误?多半是该包没有适配当前 Python 版本或操作系统的 wheel,需要本地编译而机器缺编译工具链。先确认新机器的 Python 版本与原环境一致(3.11 的环境别拿 3.13 还原),再考虑给问题包放宽版本约束单独升级。
换了镜像源还是慢,或者报 SSL 错误?先检查 index-url 是否写对(结尾的 /simple 不能少);公司网络有代理时 pip 需要单独配 proxy(pip config set global.proxy);个别老镜像同步延迟会导致"找不到某版本",换一个镜像或切回官方源对比即可判断。
requirements.txt 要不要提交 Git?要。它和代码同等重要,版本变更时还能通过 Git 历史追溯"哪次提交升级了哪个包",出问题回滚依赖也有据可依。
直接在系统 Python 上装包、不建 venv 行不行?行,但迟早还债:系统工具、多个项目会互相抢版本。本文整套方法的前提就是每个项目一个 venv,先隔离,再谈管理。
小结
本文把 venv 的依赖管理闭环走完了:激活环境先升级 pip,并养成 python -m pip 的习惯;装卸查用 install/uninstall/list/show;用 freeze 把环境冻结成 requirements.txt、用 install -r 一键还原;版本约束部署用 ==、手写可用 ~=、>= 慎用;pip check 定期查冲突;下载慢就换国内镜像,-i 临时、pip config set 持久;生产与开发依赖分文件放,需要更干净的顶层清单时上 pip-tools 的 pip-compile;换机器和上线后,用 pip check、freeze diff、导入冒烟三步验证环境一致。把 requirements.txt 当成代码一样提交、审查、维护,"在我机器上是好的"这类问题就少了一大半。下一篇我们解决代码交付的另一半:如何把项目结构组织好并打包分享。







