pip freeze 输出太长:用 pip-tools 或 uv 只维护直接依赖
pip freeze > requirements.txt 是最常见的命令之一,但在装过几轮依赖的环境里,它给出的结果往往完全失控:明明只装了三个包,文件里却有二十多行。
为什么会长出一堆没见过的包
pip freeze 描述的是“当前环境里装了什么”,不是“这个项目声明了什么”。
它遍历已安装包的元数据,把每个包的名字和版本按字母序打印出来,不区分这个包是你主动装的,还是被别的包顺带拉进来的。装 requests 会连带装 urllib3、certifi、idna、charset-normalizer,这些都会出现在输出里。
问题在于维护成本:间接依赖的版本由上游决定,你没法控制;想升级某个直接依赖,还得判断哪些间接依赖能跟着动。
正确做法一:pip-tools
把直接依赖写进 requirements.in,由工具算出完整锁定文件:
# requirements.in 里只写你真正 import 的包
# requests==2.32.3
# flask==3.0.3
pip install pip-tools
pip-compile requirements.in # 生成 requirements.txt,含全部间接依赖并锁版本
pip-sync requirements.txt # 让环境与锁定文件完全一致
关键区别:requirements.in 是人维护的,requirements.txt 是机器生成的。前者只有直接依赖,后者是可复现的完整快照。改依赖时改 .in,重新 pip-compile。
正确做法二:uv
uv 用同样思路,但把两份文件分开存:
uv init myproject && cd myproject
uv add requests flask # 只写进 pyproject.toml 的 dependencies
uv sync # 按 uv.lock 安装
pyproject.toml 里的 dependencies 只有直接依赖,完整解析结果在 uv.lock。两者都不需要手动编辑锁文件。
怎么确认清单是干净的
# 看锁定文件里直接依赖之外的部分
grep -c '==' requirements.txt # 总条数
pip-compile --dry-run requirements.in # 不写入,预览变化
判断标准很简单:requirements.in 或 pyproject.toml 里应该只有你能说出用途的包。如果里面出现了 urllib3,说明你把锁定文件当成了声明文件。
常见误解
网上流传着 pip install --freeze 这个写法。它不存在,执行会直接报 no such option: --freeze。pip 从来没有在 install 子命令上提供过生成依赖清单的选项。任何声称用这个参数只导出直接依赖的说法,都不成立。
边界
pip freeze 并非没用——在已经干净的环境里(只装了项目需要的包),它依然是最快的方式,比如容器镜像内。它的问题只出现在长期使用、反复装包的环境。
另外 pip-tools 与 uv 都不解决“直接依赖本身选得对不对”,它们只保证记录准确。