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 都不解决“直接依赖本身选得对不对”,它们只保证记录准确。

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注