Python项目导出&导入依赖库全指南

在做Python项目开发、部署、交接代码的时候，经常会遇到：换一台机器运行代码，报一堆包找不到。原因就是缺少项目依赖库，我们需要导出当前环境的依赖列表，在别的环境一键安装。

下面讲解几种常用方式：pip freeze、pipreqs，以及虚拟环境下最佳实践，坑点和避坑。

一、pip freeze（最常用）

导出依赖

pip freeze会把当前整个Python环境所有安装的包全部输出。

导出到 requirements.txt 文件

pip freeze > requirements.txt

执行完成后，项目目录就会生成 requirements.txt，内容格式示例：

Flask==3.0.0requests==2.31.0numpy==1.26.2secrets==1.0.2

在另一台机器导入安装依赖

拿到这个requirements.txt，执行下面命令批量安装全部库：

pip install -r requirements.txt

⚠️ pip freeze 的重大缺点

pip freeze导出的是整个环境全部包，不是当前项目真正用到的包。如果你本地环境装过很多乱七八糟的库，导出的文件会包含大量项目没有用到的冗余包。

• 虚拟环境中使用：✅ 推荐，环境干净，导出的就是本项目依赖。
• 本机全局环境直接使用：❌ 不推荐，会导出大量无关库。

✨最佳实践：开发项目一定要使用虚拟环境，再执行pip freeze。

二、pipreqs：只导出项目真正用到的依赖【强烈推荐】

pipreqs会扫描你的项目代码文件，分析import导入，只提取代码真正使用的第三方库，过滤掉没有用到的包。适合全局环境开发，不想创建虚拟环境的场景。

1. 安装pipreqs

pip install pipreqs

2. 导出项目依赖

进入你的项目根目录执行

# windowspipreqs . --encoding=utf8# linux/macpipreqs . --encoding=utf-8

• .
  代表扫描当前整个项目文件夹执行完成，根目录自动生成requirements.txt。

如果已经存在requirements.txt会报错，需要覆盖旧文件：

pipreqs . --encoding=utf8 --force

3. 新环境安装，同样命令

pip install -r requirements.txt

pipreqs缺点

1. 静态扫描代码，如果动态导入（__import__()），识别不到依赖；
2. 部分库导入名和pip安装名字不一致，会识别出错，需要手动修改txt。

例如：import PIL，但是pip安装命令是pip install pillow，pipreqs有可能识别错误，需要手动修正。

三、虚拟环境完整工作流（生产标准流程）

真实项目开发标准流程，避免依赖混乱：

1. 创建虚拟环境

# python3内置模块 venvpython -m venv venv

1. 激活虚拟环境

# windows cmdvenv\Scripts\activate# windows powershellvenv\Scripts\Activate.ps1# linux / macsource venv/bin/activate

激活成功，命令行前面出现 (venv)标识。

1. 在虚拟环境安装项目需要的库

pip install flask requests numpy

1. 导出依赖，此时环境纯净，没有多余包

pip freeze > requirements.txt

1. 项目交付时，只需要交付代码 + requirements.txt，不需要把venv虚拟环境文件夹发给别人！> ❗不要提交venv文件夹，体积巨大，一般加入.gitignore忽略。
2. 别人拿到代码，新建虚拟环境，执行：

pip install -r requirements.txt

四、Poetry / Pipfile（现代项目管理工具）

现在很多新项目不再用简单的requirements.txt。

Poetry

#导出，自动生成pyproject.tomlpoetry export -f requirements.txt --output requirements.txt

Pipenv

pipenv lock -r > requirements.txt

五、常见踩坑汇总

坑1：pip和pip3混淆

机器同时装python2、python3，使用：

python -m pip freeze > requirements.txtpython -m pip install -r requirements.txt

使用python -m pip保证使用当前运行的python对应的pip，避免版本错乱。

坑2：导出包含系统库、平台特定包

Windows导出的requirements.txt直接放到Linux会报错，部分包版本不兼容。跨平台部署建议使用docker。

坑3：requirements.txt上传git

把requirements.txt提交git，但是不要提交venv虚拟环境文件夹。

坑4：镜像源下载慢

安装依赖的时候国内下载慢，可以加清华源

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

总结对比

💡小建议：

1. 小型项目，优先使用虚拟环境 + pip freeze；
2. 不方便建虚拟环境，使用pipreqs；
3. 交付代码务必带上requirements.txt，别人拿到代码才可以一键复原环境。