简介这是PyInstaller 4.7的官方源码压缩包面向需要将Python脚本转换为独立可执行程序的开发者尤其适合在分布式、云原生等环境中交付Python应用。资源共404个文件以Python源码319个py为主辅以C源文件与头文件23个c、25个h以及exe、icns、ico等平台相关文件同时包含构建脚本、配置文件和文档说明压缩后仅2.65MB结构精炼完整。已有631人下载学习。通过阅读源码可以深入理解PyInstaller的分析、编译、打包三阶段工作机制动态追踪import依赖、生成捆绑包、处理非Python资源C实现部分覆盖启动器、归档解压、异常对话框等底层模块适合想二次开发或排查打包问题的中高级开发者。该版本针对新Python版本提供支持并优化了多依赖场景下的处理能力对于使用Zookeeper等协调服务的Python应用也能借助它生成无需预装解释器的交付产物提升部署效率。1. 拿到 pyinstaller-4.7.tar.gz 之后为什么还要自己从源码装PyPI 下载页上那个pyinstaller-4.7.tar.gz很多老手也是一扫而过毕竟平时一条pip install pyinstaller就能拿到预编译好的 wheel。但这个 tar.gz 才是 PyInstaller 最原始的形态里面pyi_launch.c、pyi_archive.c、pyi_pythonlib.c这些 C 源码才是真正决定打包产物能不能启动的 bootloader。需要从源码包开始装的人通常是被 wheel 坑过的那批Python 刚升到新版本官方还没出配套 wheel内网 PyPI 源不完整拉不到包又想改启动画面、改解压策略只能在源码层动手。下面就用 4.7 这个版本把下载、构建、打包、避坑整条链路讲透。2. 从源码包开始装PyPI 下载与本地构建2.1 PyPI 官网定位 tar.gz文件名版本号背后的含义在 PyPI 上搜 pyinstaller进入 Download files 页面能看到pyinstaller-4.7.tar.gz和一堆 wheel 文件并列。文件名结构是项目名版本号格式但信息量不小tar.gz 代表源码包没有平台限制装上以后为你当前平台重新编译 bootloaderwheel 则带有 cp39-cp39-win_amd64 这种标签只能装到对应 Python 版本和系统架构上。如果你打算修改 bootloader 源码或者遇到 wheel 与当前 Python 不兼容源码包是唯一可走的路。4.7 这个版本号也值得留意。PyInstaller 每个版本都会针对 Python 新版本做支持4.7 发布时正好卡在 Python 3.10 刚出道的阶段对 3.10 的支持还在磨合期。你的环境如果是 Python 3.8 或 3.9直接装 wheel 最省事但如果是刚升级的 Python 3.10wheel 可能装不上这时候下载 tar.gz 从源码构建反而可控。下载源码包我通常用 pip download而不是在浏览器里点链接因为 pip 会校验哈希并放到指定目录pip download pyinstaller4.7 --no-binary :all: -d ./src sha256sum ./src/pyinstaller-4.7.tar.gz tar -tzf ./src/pyinstaller-4.7.tar.gz | head -20--no-binary :all:是让 pip 忽略 wheel强制拿源码包-d ./src把文件存到当前目录下 src 文件夹。sha256sum 用来核对 PyPI 页面提供的哈希这一步在内网分发时不能省。tar -tzf 列出包内顶层结构重点看有没有 bootloader 和 PyInstaller 目录这两个是硬指标缺了后面必编译失败。2.2 本地安装源码包pip install 指定本地路径拿到 tar.gz 后最稳妥的安装方式是把它直接交给 pippip install ./src/pyinstaller-4.7.tar.gzpip 会把源码包走一遍构建流程生成临时 wheel 再装进当前环境。如果之前装过其他版本的 PyInstaller先pip uninstall pyinstaller否则可能因为已安装的 dist-info 冲突导致模块指向混乱。PyInstaller 4.7 在 Windows 上依赖 pywin32-ctypes在 Linux 上依赖 altgraph这些 pip 会自动装上不用自己处理。如果你打算改 C 源码就先解压再以开发模式安装tar -xzf ./src/pyinstaller-4.7.tar.gz cd pyinstaller-4.7 pip install -e .开发模式下Python 层代码修改后立刻生效但 bootloader 的 C 源码改动需要重新构建。PyInstaller 的构建逻辑是打包时如果发现当前环境缺少匹配的 bootloader会调用本机编译器自动编译一次。这意味着 Windows 上要有 Visual Studio Build ToolsLinux 上要有 gcc 和 Python 开发头文件。如果缺编译器通常会看到Python.h not found或command gcc failed之类的报错装好环境后重新执行打包即可。装完确认版本时我建议不要只敲pyinstaller --version因为 PATH 里可能有多个 Python 环境。用下面两行对比pyinstaller --version python -m PyInstaller --version第一行走 PATH第二行走当前解释器。如果输出不一致说明环境串了。我的习惯是后面所有打包都统一用python -m PyInstaller这样模块版本和 Python 解释器一定匹配不会出现用 Python 3.9 的 pyinstaller 去打包 Python 3.8 项目这种乌龙。2.3 装完先验证bootloader 文件与平台绑定版本号正确只是第一步真正决定成败的是 bootloader 是否被正确编译。你可以用一段 Python 找到安装目录再检查里面的引导文件python -c import PyInstaller; print(PyInstaller.__file__) python -c import PyInstaller, os; print(os.path.join(os.path.dirname(PyInstaller.__file__), bootloader)) find $(python -c import PyInstaller, os; print(os.path.dirname(PyInstaller.__file__))) -path */bootloader/* -type f | head在 Windows 上bootloader 目录下应看到 run.exe 与 runw.exeLinux 上应看到名为 run 的 ELF 文件。如果找不到 bootloader说明安装时构建步骤被跳过或失败。可以手动执行一次构建cd pyinstaller-4.7/bootloader python waf configure build注意 waf 是 bootloader 的构建脚本只有源码包里才有。执行python waf configure build会把所有平台相关的引导文件编出来。这一步需要网络访问因为 waf 会下载一些辅助头文件内网环境要提前配好 pip 源和 HTTPS 代理。如果不需要定制 bootloader其实用默认的预编译引导文件就够了不必手动执行 waf。还要验证平台匹配。用file命令看一眼引导文件的格式file $(python -c import PyInstaller, os; print(os.path.join(os.path.dirname(PyInstaller.__file__), bootloader, Linux-64bit, run)))输出ELF 64-bit表示这是 Linux 版本在 Windows 上对应的是 PE32 格式。很多新人把源码包从 Linux 下载后拿到 Windows 上装装完发现 pyinstaller 命令行能用但打出来的 exe 根本不是 Windows 应用程序。PyInstaller 平台绑定的特性要求单平台打包必须在对应操作系统上完成交叉编译只能靠 CI 多平台任务。3. 把脚本打包成 exe命令参数与 spec 文件的真实结构3.1 最简单的一行命令-F 与 -D 的取舍命令行工具就绪后开始打包一个真正的脚本。PyInstaller 的打包过程官方叫三步分析、编译、捆绑听起来复杂实际操作就是一行命令加一个 spec 文件。假设入口是 app.pypython -m PyInstaller --onefile --clean app.py--onefile等价于-F--clean清掉 build 目录的历史缓存。跑完后 dist 里只有一个 appWindows 上是 app.exe看起来非常干净。这里立刻会遇到第一个决定单文件还是目录模式。单文件模式的优点是交付物只有一个文件发给别人不需要带目录缺点是启动时要由 bootloader 把整个程序解压到系统临时目录文件越大启动越慢。目录模式--onedir或-D生成一个包含 exe 和依赖文件的目录启动快便于单独替换动态库但交付时要整目录打包。我一般这样选给非技术同事的内网小工具用-F要打进 Docker 镜像或做 CI 部署的服务端应用用-D因为少一层解压且出问题能直接看依赖文件是否缺失。--onefile的一个冷门参数是--runtime-tmpdir可以指定解压目录。默认在%TEMP%/_MEIxxxxxx如果系统 temp 在机械盘启动会明显变慢。有需求的场景可以指定到本地 SSD 路径但不建议写死到固定绝对路径因为目标机器未必有同样的目录。通常让它默认就够。3.2 spec 文件Analysis、PYZ、EXE、COLLECT 各管什么用命令行打包只是第一步稍微复杂一点就要改 spec。先用--name指定产物名PyInstaller 会生成同名 specpython -m PyInstaller --onefile --name app --clean app.py生成的 app.spec 本质是 Python 脚本里面四个核心结构是关键。Analysis 是整个依赖分析的中心。它读取入口脚本追踪所有 import把结果拆成 pure、binaries、datas 三组。下面这个 spec 是从实际项目简化的a Analysis( [app.py], pathex[/project/src], binaries[], datas[(config.ini, .)], hiddenimports[handler_a], hookspath[./hooks], runtime_hooks[], ) pyz PYZ(a.pure) exe EXE( pyz, a.scripts, [], exclude_binariesTrue, nameapp, consoleTrue, iconapp.ico, ) coll COLLECT( exe, a.binaries, a.datas, nameapp, )参数说明pathex是额外搜索路径datas每个元素是 (源文件, 目标目录)目标目录相对于最终产物的根hiddenimports是手动补充在分析阶段没扫到的模块hookspath指向自定义 hook 脚本目录用于扩展分析逻辑。EXE 的consoleTrue表示保留控制台窗口GUI 程序改成 False。exclude_binariesTrue只出现在-D模式它告诉构建器不要在 EXE 里重复嵌入动态库由 COLLECT 统一收集。改完 spec 后重复执行的命令不再是 app.py而是 spec 文件python -m PyInstaller app.specPyInstaller 看到参数里有 .spec 就直接按 spec 执行不会再做初始分析。这种方式的收益是固定的数据文件路径、隐藏导入和资源文件都写在同一份版本可控的文本里多人维护时不会因为命令行参数不一样而打出不同结果。3.3 数据文件、动态导入与隐藏导入的配置PyInstaller 对静态 import 的分析很准但对动态加载无能为力。比如这段代码# 插件按需加载 plugin_name plugin_ user_selection plugin __import__(plugin_name)PyInstaller 看到的 import 是字符串拼接不可能知道 plugin_a、plugin_b 需要被打包。解决办法是在 spec 的 hiddenimports 里显式列出hiddenimports[plugin_a, plugin_b]数据文件也一样。代码里open(config.json)不会让 PyInstaller 自动把 config.json 放进产物因为它只跟字节码和二进制打交道。命令行可以用 --add-data 一次性传递python -m PyInstaller --add-data config.json:. --onefile app.py注意不同平台的分隔符Windows 用分号Linux 和 macOS 用冒号。如果分隔符用错PyInstaller 不一定报错但运行时会在临时目录找不到文件。我的建议是数据文件多于两个时直接在 spec 的 datas 列表里写避免跟 shell 转义搞在一起。另一个隐藏问题是第三方库自己的动态导入。PyInstaller 通过 hook 机制为流行库打补丁hook 文件会额外收集那些靠__import__或 pkg_resources 加载的子模块。4.7 自带了大量 hook比如 kazoo、requests、lxml 都有对应 hook。如果你发现某个库打包后提示缺模块先看 PyInstaller 安装目录下hooks/stdhooks有没有对应文件有的话通常是版本不匹配升级或降级该库可以解决没有的话才需要写自定义 hook。4. 打包避坑指南六类高频翻车现场打包报错分三类构建时报错、启动时闪退、运行时导入失败。前两类可以从控制台和临时目录的日志里拿到线索第三类要下点功夫。下面这几条是我在 Windows 和 Linux 上都栽过的案例按现象、原因、解决的顺序写。4.1 中文路径导致 exe 启动闪退现象exe 在自己机器正常发给同事后闪退双击无任何提示。最后发现路径里有中文比如D:\项目\软件包\app.exe。原因PyInstaller 4.7 的 bootloader 在解析命令行和临时目录时对非 ASCII 路径支持不完善。C 层调用的是窄字符 API中文路径被截断或转乱码。解决交付时统一改成英文路径如果产品名有中文只在窗口标题体现安装路径仍用英文。也可以修改 bootloader 源码里的路径处理函数后重新编译但维护成本高不如直接约束交付目录。注意 Windows 用户名是中文时%TEMP%也可能包含中文此时单文件模式解压也会失败。可以把--runtime-tmpdir指到一个英文路径规避。4.2 ModuleNotFoundError动态 import 没被扫到现象构建过程没有报错运行 exe 后提示ModuleNotFoundError。常见于 pkgutil、importlib 动态加载的插件。原因静态分析器只能看到字面量 import字符串拼接不可解析。解决把动态导入的模块名写进 spec 的hiddenimports。另一种做法是在入口文件顶部加import handler_a之类的显式引入让分析器扫到。注意如果模块名本身也是动态生成的比如getattr(__import__(module), handler)还得检查该模块是否依赖其他内部模块可能需要一并 hiddenimports。排查时用pyi-archive-viewer dist/app.exe看模块列表确认缺失项。4.3 单文件模式启动慢与“程序无响应”假象现象-F打包的 exe 双击后半天没窗口任务管理器显示无响应。体感像是死了。原因单文件模式启动时bootloader 把整个包解压到临时目录。包体积越大解压越慢看起来像假死。解决换成-D目录模式或减小打包体积如果仍要单文件用--runtime-tmpdir指定一个位于内存盘的路径并检查杀软是否临时扫描解压文件导致延迟。启动后可以先显示一个启动画面PyInstaller 支持 splash image但 4.7 里需要额外配置。4.4 Linux 打的包到 Windows 跑不了现象在 Linux CI 上打包产物拷到 Windows 双击提示不是有效的 Win32 程序。原因PyInstaller 不跨平台编译Linux 生成 ELFWindows 需要 PE。bootloader 也是平台相关。解决每个目标平台分别打包。Windows 上可以装 PyInstaller 后直接打包Linux 上只能生成 Linux 可执行文件。云原生的 CI 可以配置多个 runnerWindows job 和 Linux job 各自构建产物。macOS 场景同理需要 macOS runner。4.5 UPX 压缩后直接崩溃现象打包后的 exe 在某些机器上启动即崩溃事件日志里是 0xc0000005或者干脆静默退出。原因系统里装了 UPXPyInstaller 检测到后自动对引导文件和动态库做了压缩。UPX 版本与 bootloader 不兼容时解压后代码段被破坏。解决打包加--noupx。在 4.7 中如果系统里有 upx默认就会启用所以出现莫名崩溃时优先检查是不是 UPX 干的。也可以卸载 upx 或设置 PATH 不包含 upx。upx 省下的空间对 Python 程序而言通常只有几 MB收益不大风险却不小。4.6 杀软误报与加壳的取舍现象exe 刚生成就被 Windows Defender 拦截或者压缩包发出去被安全网关标记为病毒。原因PyInstaller 产物自带自解压特征行为有点像常见的恶意下载器杀软对无签名的自解压程序误报率高。解决商用分发给 exe 做 Authenticode 签名内网使用可以在打包机上加白名单。签名能显著降低误报但签名证书有成本。另一个可选思路是用--key加密 Python 字节码但这只是增加逆向门槛不改变自解压特征。最实际的是在 README 里附上 SHA256 哈希和构建环境说明遇到误报配合安全团队验证。以上六类问题里至少三类的排查方式是把构建日志和运行日志打开、把产物用 pyi-archive_viewer 列一遍。很多坑不是 PyInstaller 本身有问题而是环境不一致放大了问题。5. 在 Zookeeper/云原生场景下用 PyInstaller依赖打包与配置分离5.1 kazoo 客户端为什么能被 PyInstaller 识别PyInstaller 4.7 对 Zookeeper 生态的支持主要体现在 Python 客户端 kazoo 上。kazoo 为了保证跨平台连接稳定性内部使用了动态选择 handler 的机制底层依赖 gevent、eventlet 或 threading 模型。如果只依赖静态分析PyInstaller 很可能只抓到 kazoo.client 一个顶层模块等代码运行到zk.start()时才去实例化 handler这时找不到对应实现程序直接抛异常。PyInstaller 4.7 的 hooks 目录里带了hook-kazoo.py它会把这个动态选择过程补全把 kazoo 的 handlers、components 等相关子模块一并收进 Analysis。这也正好印证了一个排查思路遇到第三方库打包后缺模块先看自带 hook 有没有覆盖而不是盲目加 hiddenimports。如果你自己维护了一个类似 kazoo 这样带动态加载的库可以仿照官方 hook 格式写一个自定义 hook。一个典型的验证方式是打包一个使用 kazoo 的最小脚本然后用pyi-archive-viewer检查模块列表里是否包含 kazoo.handlers、kazoo.recipe 等子模块。如果列表里只有 kazoo.client说明 hook 没有生效大概率是 kazoo 版本比 4.7 期望的版本新hook 内的匹配规则失效此时可以把 kazoo 降级到 2.8 左右的旧版测试。5.2 把 Zookeeper 地址和节点配置塞进 spec运行时再覆盖Zookeeper 脚本通常有多个环境开发测试、预发、生产。每套环境的 ZK 地址、根节点路径都不一样。如果把配置写死进 Python 代码每次换环境都要重新打包这个做法不推荐。正确做法是运行时从环境变量读取配置spec 里只带一份默认配置作为兜底。代码示例import os from kazoo.client import KazooClient hosts os.environ.get(ZK_HOSTS, localhost:2181) root os.environ.get(ZK_ROOT, /app/demo) zk KazooClient(hostshosts) zk.start() children zk.get_children(root) print(children) zk.stop()打包时把默认配置作为数据文件一起打进产物python -m PyInstaller --onedir --name zk_app --add-data zk_default.ini:etc zk_app.py这里的zk_default.ini是开发环境默认值etc是产物里的目标目录。运行时程序读取配置文件的路径要注意单文件模式下程序解压在sys._MEIPASS指到的临时目录配置文件也在那里目录模式下配置文件就在 exe 同级目录下。所以读取逻辑一般写成import os import sys base getattr(sys, _MEIPASS, os.path.dirname(os.path.abspath(__file__))) cfg_path os.path.join(base, etc, zk_default.ini) print(config path:, cfg_path)sys._MEIPASS是 PyInstaller 在运行时注入的变量指向解压目录。在源码环境下没有这个变量代码就会 fallback 到当前脚本目录这样开发与打包后都能读到同一个文件。这个技巧在处理数据文件时非常实用。5.3 云原生环境下的执行体容器镜像里只放一个可执行文件云原生部署的诉求是镜像里不要装一堆运行时依赖最好只放一个启动命令。PyInstaller 能够把 Python 解释器与依赖全打进去所以 Dockerfile 可以非常简洁FROM debian:stable-slim COPY dist/zk_app/ /opt/app/ CMD [/opt/app/zk_app]注意这里用的是 debian 而不是 alpine。PyInstaller 4.7 打包出来的 libpython 和第三方库通常链接的是 glibc而 Alpine 默认用 musl直接跑大概率报错。如果你确实要在 Alpine 里用必须在打包环境也基于 Alpine 构建并且 PyInstaller 的 bootloader 要针对 musl 重新编译这条路成本高不建议新手走。另一个云原生场景的注意点是动态库依赖。比如 kazoo 依赖其他 C 库打包时 PyInstaller 会把 .so 复制到产物目录但系统级依赖不会复制。启动镜像时如果提示缺 libssl、libcrypto就在 Dockerfile 里用 apt 补上RUN apt-get update apt-get install -y libssl3 libc6如果目标镜像需要最小化可以用 multipart 构建先用 python-slim 镜像打包出 dist 目录再把 dist 拷贝到干净的 debian 运行镜像。这样运行镜像里没有 pip、没有源码攻击面更小多进程环境下的安全暴露也少很多。还有一点关于多进程如果你的 Zookeeper 应用用 multiprocessing 同时起多个进程注意 PyInstaller 打包后的程序在 Windows 上没有现成的 forkspawn 模式会重新执行主模块。此时if __name__ __main__:必须是单独入口否则子进程会把整个逻辑重复跑一遍。这个坑在分布式脚本里经常出现打包后和源码环境下的行为完全不一样。6. 交付前的最后一步验证产物与启动自检6.1 pyi-archive_viewer 看捆绑包打包完成不等于可以交付。我拿到 dist 里的产物第一件事是验证里面装的东西对不对。pyi-archive_viewer dist/zk_app/zk_app这个工具会打开交互式界面输入l列出归档内容输入x 模块名可以提取某个文件到当前目录输入q退出。检查的关键点有两个一是 kazoo 相关模块是否齐全二是数据文件是否在归档里。如果发现缺东西回 spec 补 hiddenimports 再重新打包。6.2 启动日志自检验证 Zookeeper 连接接下来在干净环境里做一次真实启动。我会临时把 ZK_HOSTS 指向测试集群运行产物并观察日志。用环境变量覆盖配置确认程序从环境变量读值而不是用默认值。ZK_HOSTSzk-test.internal:2181 ./dist/zk_app/zk_app等程序跑完检查三件事进程能正常启动并停留在监听状态Zookeeper 连接日志显示成功拿到节点列表CtrlC 能优雅退出。如果退出时出现 segfault不要忽略多半是 bootloader 或某个动态库的适配问题不是业务代码的小毛病。从那以后我每次交付前都在一个没装 Python 的全新容器或虚拟机里走一遍归档检查和启动自检。第一次觉得多此一举直到有一次在干净环境里发现产物依赖了开发机上才有的某个 DLL才知道打包产物根本不干净。现在这套流程已经是肌肉记忆了希望帮到你。本文还有配套的精品资源点击获取