pip freeze > requirements.txt导出的是当前环境所有已安装包(含依赖、开发工具等),非项目真实依赖;应优先用pipreqs . --force扫描代码import语句生成精简清单,并手动补全动态导入项。

直接用 pip freeze > requirements.txt 导出、pip install -r requirements.txt 安装,能跑通但大概率不是你想要的“项目依赖”——它导出的是整个环境快照,包含你根本没用过的包,甚至 pip 自身。
为什么 pip freeze 导出的包比代码里 import 的多
因为 pip freeze 不看你的代码,只看当前 Python 环境里装了什么。比如你只写了 import requests,但它依赖的 urllib3、chardet、idna 全都会被列进去;更糟的是,如果你在全局环境或混用虚拟环境,pip、setuptools、black、mypy 这类开发工具也会躺进 requirements.txt。
- 这不是 bug,是设计定位:它是「环境备份」,不是「项目依赖清单」
- 虚拟环境能缓解但不能根治——只要环境里装过临时包(比如某次调试装的
httpx),它就永远在列表里 - 生产部署时装上
pytest或jupyter,轻则浪费空间,重则引发冲突或启动失败
怎样导出真正被代码用到的依赖(pipreqs)
用 pipreqs 扫描 .py 文件里的 import 语句,只抓实际引用的包,跳过传递依赖和开发包。
- 先安装:
pip install pipreqs - 确保你在项目根目录(即所有
.py文件所在目录),运行:pipreqs . --encoding=utf8 --force -
--force表示覆盖已存在的requirements.txt;不加的话会报错 - 它不识别动态导入(如
importlib.import_module("xxx")),这类得手动补到文件末尾 - 如果项目用了
setup.py或pyproject.toml,优先执行pip install -e .再跑pipreqs,结果更准
离线环境下怎么批量安装(不联网也能装)
核心是两步:先在有网机器下载所有 .whl 或 .tar.gz 包,再传到离线机本地安装。
立即学习“Python免费学习笔记(深入)”;
- 下载命令:
pip download -r requirements.txt -d ./offline_pkgs(会自动拉取所有依赖,包括子依赖) - 把
requirements.txt和offline_pkgs/整个文件夹拷到离线机同一目录下 - 在离线机执行:
pip install -r requirements.txt --no-index --find-links=./offline_pkgs -
--no-index是关键,它禁用 PyPI;漏掉这个,pip 仍会尝试联网找包 - 注意 Python 版本和系统架构必须一致——macOS ARM64 上下载的
torch包,在 Linux x86_64 上直接报Could not find a version
容易被忽略的细节
很多人卡在最后一步,不是命令写错,而是没意识到这些隐性约束:
-
requirements.txt里带--index-url https://xxx这种私有源地址?换环境就得同步配置,否则--no-index下直接跳过整行 - 用
pip freeze生成的文件,如果含pkg-resources==0.0.0(常见于某些 Ubuntu 系统),安装会失败,得手动删掉 - 版本号写法影响行为:
requests>=2.28.0在离线安装时可能找不到满足条件的本地包,推荐用==锁死 - 多个环境(dev/staging/prod)别硬写三份文件,用分层方式:
base.txt放共用包,prod.txt只写-r base.txt,避免漏同步


















