先说说最实际的场景本地开发环境调好的项目换台电脑、交给同事、部署到服务器结果一跑就报 ModuleNotFoundError。这时候你才意识到当初图省事没管依赖现在要一个一个去 pip list 里对版本那感觉真是一言难尽。所以“Python导出requirements.txt以及第三方库whl文件”这件事说白了就是给项目做一次“环境快照”把用到的第三方库清单和安装包一次性备份下来以后不管到哪台机器、什么网络环境都能照着原样还原。这篇内容适合所有写 Python 的人不管是刚入门的小白还是经常要交付项目的资深开发都值得花十分钟把这套流程捋清楚。我最早接触这需求是因为一个挺尴尬的事甲方给了台不能上外网的服务器让我把之前写的爬虫项目部署上去还说“你那个环境自己搞一下”。我人直接傻了项目里 import 了 requests、lxml、openpyxl还用了 scrapy这台机器啥都没有连 pip 装包都装不了。后来被逼着研究了一圈才发现官方早就有解决方案只是平时大家用不到就没在意。这篇文章我把整个流程拆开讲包括导出依赖列表、导出 whl 安装包、离线安装、跨平台部署顺便把容易踩的坑也列出来希望能帮大家少走弯路。1. 内容整体设计与思路拆解1.1 先分清两个概念依赖清单和安装包文件我们平时说的“导出依赖”其实包含两件不太一样的事。第一件是导出一个文本文件里面记录项目依赖了哪些第三方库以及对应版本号这就是 requirements.txt。它就像超市购物清单只告诉你“要买什么”但东西不在手边。第二件是把第三方库的实际安装包下载成 .whl 文件存到本地这才是真正的“货”拿到任何一台机器上都能直接装。很多教程会把这两件事混在一起讲但实际项目里它们是两种不同场景。requirements.txt 适合联网环境下的快速复现比如团队协作、CI/CD 流水线拿到清单后 pip install -r requirements.txt 就能装。而 whl 文件适合离线环境、内网部署、或者是那种网络特别不稳定的情况你把包提前下载好带走目标机器上完全不需要访问 PyPI。我在最初的方案设计时是把这两步拆开的先确定依赖范围再决定要不要下载离线包。如果目标环境能联网就只导出 requirements.txt 就完事如果目标环境是离线机那就必须把 requirements.txt 和 whl 文件一起准备好。这个判断决定了整个操作的复杂程度也是很多人一开始没想清楚导致后面折腾半天的地方。1.2 为什么不让同事/服务器直接 pip install 全部包有人可能会说直接让目标机器装项目根目录里所有 import 过的库不就行了问题在于你“项目里用到”的库和“这台机器上已安装”的库往往不是一回事。本地环境里可能装了 pandas、numpy 但项目根本没用也可能会因为早期实验装了一大堆奇怪版本的包这些都会被带过去轻则浪费时间重则版本冲突把环境搞坏。所以标准的做法是锁定一个“依赖边界”要么从当前环境快照pip freeze要么从项目代码里扫描 importpipreqs把边界内的依赖导出。然后如果目标是离线部署就把这些依赖对应的 whl 文件也一起拉下来。这套流程的核心思路就是“按需锁定、离线携带、还原验证”三个环节缺一个都会出问题。2. 核心细节解析与实操要点2.1 pip freeze 导出全量依赖最快但最“脏”pip freeze 是最常用的命令一条指令就能把当前 Python 环境里所有第三方包和版本号列出来。用法也简单pip freeze requirements.txt生成的文件长这样certifi2023.7.22 charset-normalizer3.2.0 idna3.4 requests2.31.0 urllib32.0.4适合的场景是这台机器的环境本身就很“干净”或者你是在虚拟环境里操作的环境里装的包就是项目需要的全部。我强烈建议在虚拟环境里做这件事不然很容易把系统级的一堆包全部冻结进去。它的缺点也明显不会区分“项目真正用到的”和“环境里多余的”。如果你是在全局环境里直接 freeze出来的清单可能洋洋洒洒几十上百行里面一半都没用。如果拿着这份清单到另一台机器上整轻则多装一堆无用包重则因为某几个包的版本与新系统不兼容直接安装失败。2.2 pipreqs 按项目扫描生成只留真正用到的如果项目代码结构相对规范我通常推荐用 pipreqs它自动扫描项目目录下所有 Python 文件的 import 语句再结合当前环境查出对应版本号生成一份只包含“项目实际需要”的清单。用法如下pip install pipreqs pipreqs ./ --encodingutf8 --force生成的文件也叫 requirements.txt但内容比 pip freeze 干净得多只保留代码里 import 过的库。最明显的感受是项目里可能用了 scrapy 这种重型框架但本地装了 numpy 只是顺手 pip install 的pip freeze 会把 numpy 也带进去pipreqs 就不会。需要注意几个细节。第一--encodingutf8 必须有尤其 Windows 下默认编码容易报 UnicodeDecodeError。第二--force 是覆盖已有 requirements.txt 的不写这个会提示文件已存在导致不生成。第三pipreqs 是纯静态扫描import 写在函数内部或者动态拼接模块名时它扫不到这种情况需要手动在生成的清单里补上。2.3 pip-tools 锁定间接依赖进阶方案的“稳”如果你遇到的情况更复杂比如项目可能用了某些只声明顶层依赖的库但它的底层依赖需要精确锁定版本那 pip freeze 可能过于冗长把所有间接依赖都带上了而 pipreqs 又可能缺失间接依赖。这个时候可以用 pip-tools 的 pip-compile 来做。pip install pip-tools # 先手写一个 requirements.in里面放项目直接依赖 # 然后编译生成锁定版本的 requirements.txt pip-compile requirements.inpip-compile 会根据你声明的顶层依赖去 PyPI 上拉取完整的依赖树并固定版本号生成一份既“干净”又“完整”的清单。这样做的好处是生成的 requirements.txt 不依赖当前环境装了什么包而是根据解析规则计算出来的理论上在任何机器上都能还原出一致的依赖环境。缺点是步骤相对繁琐日常小项目你用不上。2.4 三种方式怎么选一张表格给你说清楚方式命令包含范围适用场景缺点pip freezepip freeze requirements.txt当前环境所有第三方包虚拟环境整体迁移、快速快照会混入无关包依赖边界不清晰pipreqspipreqs ./ --encodingutf8 --force项目代码 import 过的包交付项目、代码结构清晰静态扫描可能漏掉动态导入pip-toolspip-compile requirements.in顶层依赖解析出的依赖树复杂项目、需要精准锁版本步骤较多需要额外安装工具我给个经验判断一两个文件的小脚本用 pip freeze 然后手动删掉明显无关的包就行正经项目交付用 pipreqs团队协作频繁换环境、或者要发到 PyPI 上的库用 pip-tools。3. 实操过程与核心环节实现3.1 单包导出 whl 文件pip download 的最基础用法假设我现在要把 requests 库以及它的所有依赖包下载成 whl 文件到本地命令如下pip download requests -d ./whls这里 -d 指定输出目录如果你不指定默认会下载到当前目录。执行完以后whls 文件夹里会出现 requests 以及它依赖的 urllib3、certifi、idna、charset-normalizer 等一堆 whl 文件。为什么要用 pip download 而不是去 PyPI 网站手工下载因为 pip download 会自动解析依赖关系把顶层库和所有间接依赖全部一起下载到本地手工下载你根本分不清哪些包是必须的。而且pip download 是 pip 自带的功能不需要额外安装什么工具Python 3.x 只要带了 pip 就能用。3.2 批量导出按 requirements.txt 把环境整体打包如果已经提前准备好了 requirements.txt那导出整个环境的 whl 包就变成一条命令的事pip download -r requirements.txt -d ./whls这条命令会逐行读取 requirements.txt把每一行指定的包和版本都下载到目录里。实际执行时你会看到 pip 在逐个下载并打印进度最后提示”Successfully downloaded requests-2.31.0 ...“之类的信息。我在实际项目里通常会先建一个单独目录比如 project_offline里面再分两个子目录requirements 放清单文件whls 放安装包。这样整个离线交付包的结构很清晰目标机器拿到手也不会一脸懵。3.3 跨平台导出在 Windows 上给 Linux 服务器准备离线包这一步是最容易出问题的但也是最有价值的部分。很多人第一次操作时会发现自己在 Windows 上导出的 whl 文件拿到 Linux 服务器上装不了报错提示“xxx.whl is not a supported wheel on this platform”。原因很简单每个 whl 文件名里其实都标注了适用的操作系统和 Python 版本。如果你想在一台机器上为目标平台准备另一套平台的 whl 文件就得给 pip download 指定平台参数。比如我在 Windows 电脑上想给 Linux x86_64 的 Python 3.10 环境准备离线包命令是pip download \ -r requirements.txt \ -d ./whls_linux \ --platform manylinux2014_x86_64 \ --python-version 310 \ --only-binary:all:几个参数逐个说。--platform 是指定目标机器平台manylinux2014_x86_64 覆盖大多数现代 Linux x86_64 服务器这是目前兼容面最广的标注。--python-version 指目标环境的大版本写 310 就是 Python 3.10没必要写完整小版本号。--only-binary:all: 意思是只下载 whl 格式的预编译包不下载 tar.gz 源码包因为源码包在目标机器上还需要编译工具链我们既然做离线包就要尽量避免这种不确定性。但这个方案有个前提你项目依赖的所有包都必须提供了对应平台的 whl 预编译版本。如果一个包只有源码包没有 wheel 包那加上 --only-binary:all: 之后会直接报错。我实际遇到过一个典型某个内部小工具库只在 PyPI 上发布了 sdist 源码包没有发 wheel用这个命令就会失败。这种情况的处理方式是去掉 --only-binary:all: 参数把源码包也下载下来让目标机器现场编译前提是目标机器得有编译环境这点在离线部署时往往很麻烦。3.4 目标机器离线安装pip install 的离线模式离线包准备好以后目标机器上的安装命令只有一条pip install --no-index --find-links./whls -r requirements.txt--no-index 的意思是不要访问 PyPI--find-links./whls 是指定从本地目录找安装包。这两条必须一起用否则 pip 可能会去联网检查最新版本又慢又不可控。我在服务器上实际执行时输出里会出现 “Looking in links: ./whls” 表示正在从本地目录检查然后逐个安装。如果缺了某个包会明确告诉你 “Could not find a version that satisfies the requirement xxx”这时候回本地电脑把缺的 whl 补下载一份拿到目标机器再装就行。3.5 一个完整迁移案例从开发机到离线服务器我把自己踩过坑之后总结的标准流程放这里照着做基本不会出问题。第一次先在自己开发机上确认项目能正常跑用虚拟环境激活命令进入环境。第二步用 pipreqs 扫描生成 requirements.txt。第三步检查清单把 pipreqs 漏掉的人工补进去。第四步执行 pip download -r requirements.txt -d ./whls 下载离线包。第五步把 requirements.txt 和 whls 文件夹打包发给目标机器。第六步在目标机器上建虚拟环境执行离线安装命令。第七步装完以后用 pip list 核对一下关键包版本然后跑项目验证。这七步每一步都有对应的验证点不要跳。尤其是第七步很多人在这一步偷懒结果上线后报错才回来看版本反而更浪费时间。4. 常见问题与排查技巧实录4.1 Windows 下 pip freeze 出现“file:///”或“本地路径”开头的包名这种情况我碰到过好几次。Windwos 上如果你用 pip 安装过本地 .whl 文件或者用了某些特殊的 index 地址pip freeze 的输出可能会出现类似package file:///D:/downloads/some_package.whl或者直接是本地路径。这种行写到 requirements.txt 里换到别的机器上执行 pip install -r 就废了因为它指向的是你本地磁盘路径。解决办法是要么手动把这一行改成正常的包名版本号格式要么干脆用 pipreqs 重新生成清单让 pip 去查当前环境的版本信息就不会有这个路径问题。踩过一次后我再没用纯 pip freeze 干过交付环境的活基本都是 pipreqs 生成后人工补漏。4.2 pipreqs 扫描不到动态导入的库pipreqs 是静态扫描 import 语句的如果你代码里用了 importlib.import_module() 动态加载模块或者在一个字符串里拼模块名再导入pipreqs 根本扫不到。我在一个数据采集项目里踩过这个坑项目用 entry_points 插件机制动态加载了几个采集器pipreqs 生成清单后什么都有就是少了核心的采集框架库等上了服务器才发现。碰到这种项目最可靠的方法是先用 pipreqs 生成一份基础清单然后看一遍代码里有没有 import 语句之外的可疑模块引用有不确定的就主动加进 requirements.txt。宁可多装一两个无关包也不能漏掉实际要用到的包。4.3 导出 whl 时提示某个包只有源码包没有 wheel这个问题我在 3.3 节已经提过这里再说一个实际判断方式当你看到下载日志里出现 Building wheel for xxxpyproject.toml而不是直接下载 whl 文件时说明这个包在 PyPI 上提供的是源码包。如果你没有加 --only-binary:all:pip download 会把 sdist 源码包下载下来后缀是 .tar.gz 而不是 .whl。这在离线环境里非常尴尬因为目标机器如果没有编译工具链源码包根本装不了。最省事的应对方案如果这个包有新版或老版提供了 whl就尝试指定对应版本如果没有就只能接受目标机器上要装编译工具的事实或者考虑换一个功能等价且有 wheel 的包。这种问题越早发现越好别等到交付前一天才发现有包没法离线装。4.4 不同 Python 版本导出的 whl 文件混用会报“not a supported wheel”每台机器的 Python 版本可能不一样3.9 和 3.10 的 ABI 接口有差异很多 C 扩展的 whl 文件不能跨版本使用。比如你在 Python 3.9 环境里跑 pip download拿到的 numpy whl 可能在 Python 3.10 的机器上装不了。离线导出前必须先确认目标机器的 Python 大版本。如果目标机器已经有 Python 3.10那导出时在开发机上执行 pip download 之前可以用 --python-version 310 参数来指定这样 pip 会去找兼容 Python 3.10 的包不管你当前执行命令的 Python 是哪个版本。当然最稳妥的还是直接在同样版本的 Python 环境里去下载。4.5 目标机器安装完成import 依然报 ModuleNotFoundError这个问题的排查思路要先看依赖树。有时候你确实把所有依赖都导出了但某个包的某个功能需要额外安装一个子依赖而这个子依赖只在运行时才被 importpip download 自动解析依赖时可能没抓到。排查方法是在目标机器上打开 Python执行 import xxx 看完整报错它会提示缺哪个模块然后回开发机用 pip download 下载这个缺失的模块再传到目标机器装上。这种问题往往出现在一些功能比较复杂的库上比如 psycopg2 在一些环境下还依赖 psycopg2-binary或者 lxml 在某些版本下还依赖 html5lib。4.6 常见问题速查表问题原因解决办法requirements.txt 里有 file:/// 开头的路径之前用本地 whl 安装过手动改版本号或用 pipreqs 重新生成pipreqs 漏包动态导入没被静态扫描到人工检查 importlib 和字符串拼接导入目标机器装不了某个 whl平台或 Python 版本不匹配检查文件名里的 cp310/manylinux 标记离线安装时提示缺包依赖解析漏了子依赖回开发机补下对应 whlpip download 提示只有 sdist包没有发布 wheel换版本或准备编译工具链同一份 whl 放不同机器结果有的能装ABI 不兼容按目标机器的 Python 版本分别导出5. 给新手的几条额外建议我在实际项目里反复踩重复的坑把几条最重要的心得说在前面。第一做依赖导出和离线包之前务必先建一个全新的虚拟环境在这个干净环境里把项目跑通再导依赖。不然你的开发机上残留的那些无关包会混进清单里导致离线包体积大、装起来也容易冲突。第二requirements.txt 和 whls 目录一定要一起打包交付缺一个都不行。如果只给别人 requirements.txt对方就还得联网如果只给别人 whls 却没有清单对方也不知道该装哪个版本。最好在交付文档里写清楚两条命令一条是离线安装命令一条是联网快速安装命令让对方自己选。第三用 pip download 的时候强烈建议加上 -i https://pypi.org/simple 或者你常用的国内镜像源尤其在国内网络环境下默认源下载速度可能无法接受。指定镜像源不会影响 whl 文件的内容只影响下载速度。pip download -r requirements.txt -d ./whls -i https://pypi.tuna.tsinghua.edu.cn/simple第四导出完以后建议顺手统计一下 whl 文件总数和总大小心里有数。我之前交付过一个项目requirements.txt 里只有十来行结果 pip download 下来发现还带了一层很深的传递依赖总共 40 多个 whl 文件十几个 MB。你提前知道这些数据在跟对方沟通交付内容时会更从容。第五把这套流程写成一个 shell 脚本或者 PowerShell 脚本以后每次交付都直接跑一遍比每次手动敲命令可靠得多。脚本的核心就三行生成 requirements.txt、准备目录、执行 pip download然后把 requirements.txt 复制进交付目录。我记得自己第一次手动操作时漏掉了其中一个子包导致交付现场手忙脚乱从那以后再没手动执行过。6. 这个内容后续还能怎么扩展如果你经常做离线部署可以在这个基础上进一步研究离线安装私有 PyPI 源比如用 devpi 或者 bandersnatch 搭一个本地镜像这样团队内部的所有项目都能通过配置 pip.conf 指向内网源来安装依赖不用每个人手动维护 whl 文件目录。还可以把这一套流程和 Docker 结合起来写一个 Dockerfile在构建阶段把 requirements.txt 和 whls 目录打进镜像配合多阶段构建把体积控制到最小。我之前负责的一个项目就是这么优化的基础镜像只装 Python 运行环境项目依赖用离线包一次性安装镜像构建速度反而比在容器里现场 pip install 快不少。如果你是用 Poetry 或者 uv 这些现代包管理工具它们也都有导出 requirements.txt 的能力。Poetry 对应 poetry export -f requirements.txt -o requirements.txtuv 对应 uv pip compile底层语义和 pip-tools 类似。用它们管理依赖的项目导出离线包的核心逻辑不变只是前面生成清单的环节换成对应命令就行。最后再分享一个小技巧在导出 whl 文件以后别急着删掉留着在开发机上也是一个很好的“依赖缓存”。以后重建环境时可以先用 --find-links./whls 从本地装装不上的再联网能省不少时间。尤其是网络不稳定的情况下这个本地目录就像个小型包仓库整个开发体验会顺畅很多。