简介这份 pyinstaller依赖包.zip 面向需要在 Windows 平台离线部署 Python 应用的开发者与运维人员核心是提供 PyInstaller 及其最小化依赖帮助在无法联网或目标机器缺少 Python 环境时完成可执行文件打包压缩包约 6.21MB文件总数与类型明细暂未提供已有 878 人学习或下载。包内围绕依赖图分析、Windows API 调用封装、PE 文件读写和 Python 2/3 兼容等环节组织组件可支撑将脚本转为独立可执行程序、排查缺失依赖以及理解打包链路组件用途覆盖打包前依赖收集与打包后可执行文件解析两类场景。读者可据此搭建离线安装环境结合命令行选项定制图标、控制台显示等输出形态同时留意大型数据文件导致的体积膨胀并借助依赖分析思路定位打包异常。整体适合希望减少联网安装阻碍、快速验证 PyInstaller 打包流程的中级 Python 使用者。1. 从一次闪退说起pyinstaller 依赖包装在哪一层决定你后面折腾多久第一次在一台不能连外网的构建机上装 pyinstaller 依赖包我把 zip 解开、pip install一把梭终端全程绿字我以为是收工了。pyinstaller --version也确实能打出版本号可真正打出来的 exe 双击就闪退控制台一行No module named pkg_resources连堆栈都没留全。后来才发现包是装上了但依赖包里的 hook 集合没进虚拟环境PyInstaller 在分析阶段压根没把动态导入的模块收进去。这类“装完能跑、打包才炸”的情况太常见了——pyinstaller 依赖包不是一个“装上就行”的轮子集合它决定了分析器认不认得你的代码。这篇笔记写给正在内网、离线机或者一堆老项目里配打包环境的人从版本对齐、离线安装、spec 配置到跑通验证一步步来装坏了也知道回哪一步救。2. 环境对齐Python 版本、位数与虚拟环境的三重核对装 pyinstaller 依赖包最容易翻车的地方不在安装命令本身而在装之前的三个前提Python 版本够不够、解释器位数对不对、是不是装进了一个干净的虚拟环境。这三项只要错一个后面出现的报错都长得像“依赖缺失”排查方向直接跑偏。2.1 先看 wheel 文件名再决定用哪个 PythonPyInstaller 自己的 wheel 是平台相关、Python 版本无关的——文件名大致形如pyinstaller-版本-py3-none-win_amd64.whl那个win_amd64是它内嵌的 bootloader 二进制而依赖包里其他成员比如altgraph、pefile、pywin32-ctypes、pyinstaller-hooks-contrib基本都是py2.py3-none-any的纯 Python 包。所以判断兼容性不能只看“有没有 cp311 这种标签”而要分两步走。文件名里的标识含义判断要点py3-none-win_amd64平台相关含 64 位 Windows bootloader必须与解释器位数一致32 位 Python 装不上py3-none-manylinux_x86_64Linux 64 位 bootloader与 glibc 环境相关跨发行版要留意py2.py3-none-any纯 Python与平台无关任何解释器都能装cp3xx绑定 CPython ABI依赖包里出现它说明有 C 扩展版本必须严格对齐看到win_amd64这类平台标签第一件事是确认你的 Python 是不是同位数python -c import sys,platform;print(sys.version);print(platform.architecture())。32 位解释器配 64 位 bootloaderpip 会直接拒绝安装并提示 “not a supported wheel on this platform”这反而是好事更麻烦的是反过来——位数对了但版本太老装完打包时会报语法错误或者干脆打不出产物。第二步看包内元数据的Requires-Python。解压后每个 wheel 里都有一份.dist-info/METADATA直接 grep 一下# 在解压目录里逐个大包检查 Python 版本下限 for f in deps/*.whl; do echo $f unzip -p $f *.dist-info/METADATA 2/dev/null | grep -i ^Requires-Python done这段循环把每个 wheel 的元数据抽出来只留Requires-Python一行。为什么要这么做依赖包往往是给某个固定项目配的里面的 PyInstaller 版本可能只支持到某个 Python 区间装在更新的解释器上不会立刻报错而是在分析阶段抛AssertionError或者生成一个跑不起来的产物。我一般会把这条输出贴到构建机的 README 里换机器时不用重新猜。2.2 虚拟环境不要在系统 Python 上直接装离线依赖包最怕的就是“装到全局去”。理由很实际依赖包里的 wheel 版本是固定的一旦装进系统 site-packages跟你机器上其他项目已有的版本打起来pip 会做一次隐式降级把你别的工具的依赖顺手改掉事后很难复原。# 在项目根目录建一个独立环境目录名固定为 .venv方便 .gitignore python -m venv .venv # Windows PowerShell 激活 .venv\Scripts\Activate.ps1 # Linux / macOS 激活 source .venv/bin/activate # 确认当前 pip 指向的是虚拟环境内的解释器 python -m pip -Vpython -m venv后面不加参数时用的是当前解释器的同版本如果你机器上有多个 Python务必写成python3.11 -m venv .venv这样的显式形式否则很容易出现“我在 3.12 上装的包打包时用的是 3.10 的解释器”。最后一行的python -m pip -V是关键自检输出里应该带上.venv的路径。这一步看起来啰嗦但我见过太多次“明明装了却 import 不到”最后发现是 pip 和 python 指向了两个不同的环境。提示不要在激活虚拟环境之后再用裸pip命令。统一写成python -m pip可以规避 PATH 顺序带来的玄学问题尤其是在 Windows 上同时装了多个 Python 的情况。2.3 解压依赖包先把清单读一遍再动手不要解压完直接pip install deps/*.whl。先列目录确认包是不是齐的特别是 hook 集合和两个底层依赖在不在。# 解压到一个固定目录避免中文路径和空格打包工具对此很敏感 unzip pyinstaller依赖包.zip -d ./deps # 只列 wheel按名字排序方便肉眼核对 ls -1 ./deps | grep -i \.whl$ | sort解压目录建议放在纯英文路径下例如D:/build/deps或/opt/build/deps。中文路径和带空格的路径在 PyInstaller 分析阶段偶发报错不是每次都炸属于典型的“玄学问题”能避就避。清单核对的重点是三类主包PyInstaller 本体、hook 集合决定第三方库能不能被自动识别、底层依赖altgraph负责依赖图、pefile解析 Windows PE 头、pywin32-ctypes提供 Windows API 绑定。如果发现只有主包没有 hook 集合先别急着装八成是压缩包没传全重新取一份比事后排查ModuleNotFoundError划算得多。3. 离线安装把 zip 里的 wheel 装成能用的环境环境对齐之后安装动作本身其实很短。真正需要想清楚的是装的时候要不要禁用网络索引、版本冲突怎么收敛、装完怎么确认这份包树是完整的。3.1 用 --no-index 锁死安装源离线机的标准装法是让 pip 只在本地目录里找包绝不出去请求索引避免它卡在超时上干等。# 进入项目根目录确保虚拟环境已激活 cd /opt/build/myapp # 关键参数--no-index 禁用远程索引--find-links 指定本地 wheel 目录 python -m pip install \ --no-index \ --find-links./deps \ pyinstaller # 如果依赖包里有多个版本显式指定要用哪一个避免 pip 挑错 python -m pip install --no-index --find-links./deps pyinstaller包内版本--no-index的作用是彻底关掉 PyPI 查询--find-links告诉 pip 去哪里翻 wheel两者组合等于“只准从本地装”。很多人只写--find-links不写--no-index在有网机器上测试没问题一挪到内网就变成几十秒的超时重试最后报一个看起来毫不相干的ReadTimeoutError。如果依赖包里的 wheel 版本比较旧、构建元数据不完整pip 可能尝试走 PEP 517 构建流程这时候加上--no-build-isolation让它复用当前环境里的 setuptools能省掉一次失败的构建。安装完成后立刻做一次python -m pip check它会检查已安装包之间的版本约束是否互相冲突输出为空才算干净。3.2 版本冲突用约束文件收敛不要在命令行里逐个 pin依赖包里带的 wheel 是某个时间点的快照和你项目原有的requirements.txt撞车是常态。手动一个一个降级是血泪经验级的低效做法正确姿势是写一个约束文件。# constraints.txt —— 只约束版本不主动安装 altgraph0.17 pefile2022.5.30 pyinstaller-hooks-contrib2023.0# 应用约束文件安装pip 会在满足约束的前提下选依赖包里的版本 python -m pip install \ --no-index \ --find-links./deps \ -c constraints.txt \ pyinstaller约束文件和requirements.txt的区别要分清楚-c指定的文件只限制版本上限下限不会把里面列出的包装进来-r才会主动安装。离线场景下用-c更安全能避免把约束文件里顺手写的某个包也拖进环境。如果 pip 报ResolutionImpossible说明本地目录里的可用版本区间和环境里已装版本没有交集。这时候先python -m pip list看清现状再决定是清空环境重装还是在约束文件里放宽区间。我的习惯是直接删掉.venv重建——离线环境重建成本很低比在冲突里做微调靠谱。3.3 装完核对包树别只看 pip 的绿字pip 说 Successfully installed 只代表文件落地了不代表依赖完整。装完至少跑三个检查。# 检查一主包能否 import版本号是否符合预期 python -c import PyInstaller; print(pyinstaller, PyInstaller.__version__) # 检查二hook 集合是否可见离线包最容易漏这个 python -c import PyInstaller.utils.hooks as h; print(hooks ok) # 检查三导出当前环境的精确快照作为后续比对基线 python -m pip freeze requirements.lock.txt第一个检查验证主包可导入第二个检查验证 hook 机制可用——很多第三方库能不能被自动收集全靠这个模块去遍历 site-packages 里的 hook 定义。第三个检查生成的requirements.lock.txt是后面排查“为什么这台机器能打、那台打不出”的比对依据比凭记忆可靠得多。如果PyInstaller.utils.hooks导入时报ModuleNotFoundError: No module named PyInstaller.utils.hooks说明装的不是完整的 PyInstaller 包常见于压缩包被截断或者手动解压时漏了子目录。重新解压一份别在原环境上打补丁。4. 打包配置让依赖真正被收进去的三个地方装完只是准备真正决定产物能不能跑的是配置。PyInstaller 的分析过程是静态扫描 hook 补全动态导入、插件式加载、运行时读取的资源文件它默认都看不见。4.1 先跑一条最短命令建立基线任何改动之前先确认最基础的打包链路是通的。用一个只有print的脚本试水报错信息会非常干净。# 写一个最小脚本 cat hello.py EOF # 最小验证脚本只打印一行避免引入任何第三方依赖 print(hello from packaged app) EOF # --noconfirm 覆盖旧产物--clean 清缓存--onedir 目录模式便于排查 python -m PyInstaller --noconfirm --clean --onedir hello.py三个参数各有分工--noconfirm让工具直接覆盖上次的build/和dist/不用交互确认--clean清掉分析缓存——这一步在依赖包换过版本之后必须做否则会拿旧缓存去打新环境产出莫名的报错--onedir输出的是一个目录而不是单文件后续缺什么模块可以直接往目录里补排查效率比 onefile 高一个量级。第一次打包失败时优先看build/脚本名/warn-脚本名.txt。这个文件列了所有“扫描到但没能导入”的模块是分析阶段的黑匣子比控制台输出有用得多。里面大部分条目是无害的可选导入但如果出现你项目里实际用到的模块名那就是漏收了。4.2 spec 文件里必须改的四个字段命令行参数能覆盖的场景有限一旦涉及数据文件、隐藏导入、排除项就得生成并编辑 spec。# 先生成 spec 模板后续所有构建都基于它 python -m PyInstaller --noconfirm --onedir hello.py # 产物在 hello.spec改完用 spec 重新构建 python -m PyInstaller --noconfirm hello.spec# hello.spec —— 重点关注 Analysis 里这四个字段 a Analysis( [hello.py], pathex[], # 额外的模块搜索路径放项目源码根目录 binaries[], # 手动指定的动态库一般由 hook 自动处理 datas[(config/*.json, config)], # (源路径, 产物内相对目录) hiddenimports[encodings.idna], # 静态扫描看不到的动态导入 hookspath[], # 自定义 hook 目录 excludes[tkinter, matplotlib], # 明确排除控制体积 noarchiveFalse, )字段什么时候必须动常见误用pathex源码不在 spec 同级目录写绝对路径换机器就失效datas运行时要读配置文件、模板、图标只写源路径忘了写目标目录hiddenimports用importlib、__import__、插件机制加载的模块把整个包名写进去实际子模块没被收excludes明确知道不用的重量级库排除掉运行期真会用到的包报错很隐蔽datas里那个二元组是最容易写错的地方左边是构建机上的真实路径右边是产物内部的相对目录名写反了或者漏了右边程序启动时会报“找不到文件”但打包过程一点错都不报。另外路径分隔符在 Windows 上是;、在 Linux 和 macOS 上是:如果坚持用命令行的--add-data跨平台构建脚本里要分平台拼接改成 spec 就没这个烦恼。4.3 隐藏导入与数据文件三类漏收的典型场景第一类是动态导入。比如按名字反射加载的模块静态扫描完全看不见必须靠hiddenimports补或者在hookspath下自己写 hook 文件。第二类是包内的数据文件比如某些库自带.json字典、.bin模型、.mo翻译文件这些不在datas里就进不去产物。第三类是命名空间包和子模块父包被收了子模块因为没有被直接 import 到而漏掉。针对第二类和第三类PyInstaller 提供了两个收集开关比手写一长串列表省事# 收集某个包的全部子模块和随包数据适合依赖树复杂的库 python -m PyInstaller --noconfirm --onedir \ --collect-submodules yourlib \ --collect-data yourlib \ main.py--collect-submodules递归收集指定包下的所有子模块--collect-data收集包目录里的非 Python 文件。这两个开关的代价是体积会涨所以只对确实用到的库开不要图省事给整个 site-packages 开扫描——那会让打包时间从几十秒变成十几分钟产物里还会塞进一堆无关的东西。5. 常见问题排查五类装完才暴露的坑5.1 现象打包成功运行时报 ModuleNotFoundError现象很典型构建日志干干净净dist/目录也生成了双击运行直接退出控制台只有一行ModuleNotFoundError: No module named xxx而这个模块在开发机上import完全正常。原因基本只有两种。一是该模块属于动态导入静态分析器根本没扫到引用二是模块被装在了一个不在sys.path里的位置比如用pip install --target装到别处或者项目用了非标准的src布局而 spec 里的pathex没配。判断方法很直接去build/脚本名/xref-脚本名.html里搜这个模块名搜得到说明被扫描过但依赖链断了搜不到就是压根没被识别。解决上优先补hiddenimports把完整子模块路径写进去而不是只写父包名。如果模块数量多改用--collect-submodules一次性收。补完记得删掉build/和dist/重新构建只删dist/会复用旧的分析缓存改了等于没改。5.2 现象pip 安装时抛 ResolutionImpossible现象是安装命令跑到一半pip 打印一大段 “The conflict is caused by”最后终止环境里可能还留下了装了一半的残局。原因是依赖包里某个 wheel 的版本区间和环境中已安装的其他包没有交集。离线环境特别容易撞上因为依赖包快照的时间点和你项目当前依赖的时间点不一致。这时候别在命令行里逐个试版本先python -m pip list把现状打出来对照报错里提到的包名找冲突点。解决分两条路小冲突用-c constraints.txt放宽区间冲突面大就直接删掉.venv重建先装依赖包里的 PyInstaller 全套再装项目自己的依赖顺序反过来往往更顺。装完一定跑python -m pip check复核。5.3 现象exe 启动即闪退什么都不输出现象是双击之后窗口一闪而过连错误信息都看不到只能靠任务管理器确认进程起过。原因九成是consoleFalse把标准输出和标准错误全吞了——窗口模式的产物没有控制台任何启动期异常都无处可去。剩下的一成是资源路径问题代码里用相对路径读文件而打包后工作目录变成了 exe 所在目录路径解析失败。解决办法分两步。第一步把 spec 里EXE(...)的console临时改成True重新打包跑一遍让堆栈打出来第二步定位到具体原因后再改回去。资源路径统一改用sys._MEIPASS拼接或者在入口处把工作目录切到可执行文件所在目录二选一别混用。5.4 现象产物被安全软件拦下或直接删除现象是构建成功但产物刚生成就被清理或者分发到其他机器上被拦截用户反馈“打不开”。原因多半是 onefile 模式的自解压行为特征太明显加上没有签名被启发式规则命中了。这不是代码问题改代码没用。常见做法是改成--onedir目录模式分发把一个自解压包变成一堆普通文件命中率会明显下降同时对产物做代码签名走正常的签名流程。另外构建机上如果装了某些监控软件也可能在写入时锁文件导致打包报“拒绝访问”这种情况换一个输出目录就能排除。5.5 现象打包时间从几十秒涨到十几分钟产物体积翻倍现象是同一份代码换了个环境打包时间暴涨dist目录大了一个数量级。原因是分析器把整个 site-packages 都纳入了扫描——通常是虚拟环境里装了太多无关的重量级库或者有人为了图省事加了全量收集参数。PyInstaller 会顺着 import 链一路扫扫到科学计算类的库就顺带把底层二进制全拖进来。解决靠excludes精确排除把确定不用的 GUI 框架、绘图库、测试框架写进 spec 的excludes列表重新构建后对比体积变化。同时检查虚拟环境是不是干净的python -m pip list里出现跟项目毫无关系的包说明这个环境被污染过重建比清理快。6. 装完怎么验证三步确认这套依赖真能打出能跑的包装完依赖、配完 spec别急着交付。我固定走三步验证任何一步不过就退回上一章重来。第一步是环境自检把关键信息一次性打全出问题时直接拿这份输出比对# 一条命令把解释器、位数、PyInstaller 版本、hook 可见性全部打出来 python - EOF import sys, platform print(python:, sys.version.split()[0]) print(arch:, platform.architecture()[0]) import PyInstaller print(pyinstaller:, PyInstaller.__version__) import PyInstaller.utils.hooks # 能导入说明 hook 机制完整 print(hooks: ok) EOF第二步是打一个最小样例并在干净的目录里运行产物。这一步的意义是把“构建机能跑”和“产物本身能跑”分开——很多问题是因为运行时还能读到开发目录里的文件看起来正常一换机器就崩。# 构建最小样例 python -m PyInstaller --noconfirm --clean --onedir hello.py # 把产物拷到一个空目录再运行切断对源码目录的隐式依赖 mkdir -p /tmp/smoke cp -r dist/hello/* /tmp/smoke/ cd /tmp/smoke ./hello第三步是把真实项目的关键路径跑一遍尤其是读配置文件、加载插件、访问数据库这几类操作。只验证“程序能启动”是不够的启动成功但读不到配置分发出去照样是一堆工单。验证项通过标准失败时先看哪环境自检三项输出齐全hooks 显示 ok依赖包是否解压完整最小样例空目录下能正常输出spec 的console与运行目录真实项目配置读取、插件加载均正常warn-*.txt与datas配置从那以后我每次换构建机都强制先跑这三步再动真实项目哪怕只是换了个 Python 小版本也要重新走一遍。依赖包这东西装的时候省下的十分钟后面往往要用一整天来找。希望帮到你。本文还有配套的精品资源点击获取