简介这份 pyinstall 安装包面向需要把 Python 脚本转换为独立可执行文件的开发者可用于了解 PyInstaller 类工具在依赖分析、脚本冻结与跨平台分发中的基本实现思路适合具备一定 Python 基础、想研究打包流程或搭建本地测试环境的人群。压缩包共 19 个文件约 37KB以 10 个 txt 说明/测试文本、5 个 py 源码脚本为主并含 pkg-info、cfg 与 regen-docs 等配置和文档辅助文件整体体量轻便便于快速查阅源码结构、测试用例与打包配置。已有 589 人学习或下载可作为旧版打包工具的参考资料。读者可从中获得安装包组织方式、核心脚本与测试样例辅助理解 Python 程序打包时需要关注哪些模块与依赖并据此做小规模验证、排错和二次研究。1. pyinstaller 安装包并不是一键生成 exe先搞清楚它替你做了什么在搜索框里输入 pyinstaller 安装包的人多半不是想研究 Python 打包原理而是手里有个脚本要交给不会装环境的人用。我见过最常见的场景是脚本在本机跑得好好的压缩包发给同事对方双击之后黑框一闪就没了或者弹一句ModuleNotFoundError直接退出然后微信上飘来一句“你这东西是不是有毒”。这份资源就是围绕 PyInstaller 把 Python 程序变成可直接分发的可执行文件这条流程整理的包含环境准备、spec 配置、依赖收集、体积优化和产物验证几个部分适合需要把内部工具交付出去的后端、算法、自动化岗也适合第一次接触打包、被 spec 文件里那几个参数卡住的开发者。它的价值不在于替你省掉一行命令而在于把“为什么打包会翻车”这件事讲清楚。2. 把打包流程跑通隔离环境、三条命令与两种产物形态搭好环境再按三条命令走一遍基本能出产物。这一步的目标是拿到“能跑起来的最小版本”后面所有优化和排错都以它为基线。先别急着加参数、加图标、改 spec一个干净的基线能让你在出问题时明确知道是哪次改动引入的。2.1 打包前先隔离环境这一步决定后面所有返工量PyInstaller 的工作方式是从入口脚本出发沿 import 图做静态分析把命中的模块从 site-packages 里复制出来再把 Python 解释器和运行时一起塞进产物目录。它不会判断这个包是不是你真正要的也不管你全局环境里装了多少与业务无关的东西。因此全局环境里只要装着体积大的库产物就会跟着膨胀全局环境里装了冲突版本的包打包时也不报错等到目标机器上运行才暴露出来。我一般会为每个需要打包的项目单独建一个虚拟环境requirements.txt只保留运行期依赖pytest、ruff、mypy 这些开发工具放到另一个环境里安装。这一步看似麻烦但能挡掉后面一大半“本地能跑、打包就废”的问题。# 建一个干净的虚拟环境路径用项目内的 .venv便于整体删除重建 python -m venv .venv # Windows 用 .venv\Scripts\activateLinux/macOS 用 source source .venv/bin/activate # 先把 pip 抬到较新版本避免解析旧式依赖元数据时出错 python -m pip install --upgrade pip # 只装运行期依赖开发依赖不要写进这个文件 pip install -r requirements.txt # 打包工具本身装进同一个环境版本写进 requirements-dev.txt 锁住 pip install pyinstaller这段的重点在最后一行注释PyInstaller 的版本需要固定下来。不同大版本之间spec 文件的字段名和 hook 的行为都变过同一个项目换台机器重新打包出的结果可能不一样排查起来会非常费劲。我的习惯是在开发环境里把它单独记一条版本约束上线打包时照着这条约束装不跟着最新版走。2.2 三条命令生成第一个可执行文件先跑一个最小命令参数尽量少确认基础流程是通的。# -D 生成一个目录onedir-c 保留控制台窗口-n 指定产物名 pyinstaller -D -c -n tool main.py # 出问题重来时加 --clean 清掉 build 缓存--noconfirm 跳过覆盖确认 pyinstaller -D -c -n tool --clean --noconfirm main.py几个参数在这里的含义需要说清楚。-D和-F是互斥的选择前者产出一个包含可执行文件和依赖库的文件夹后者产出一个单文件-c和-w也是互斥的-c保留控制台-w在 Windows 上等于用窗口模式启动、不弹黑框-n决定产物文件夹名和可执行文件名最好跟项目名对得上不要用中文或者带空格的字符串。执行完之后工程目录下会多出build/、dist/和tool.spec三个东西。build/是中间产物和日志可以随便删dist/是最终要分发的内容tool.spec是这次命令生成的配置文件一旦你开始手工改它后续就不该再用命令行参数构建了这点在第 3 章展开。2.3 第一次运行别双击控制台是唯一的黑匣子产物拿到手很多人第一反应是双击 exe 看效果。这个习惯会让排查难度翻倍程序崩溃的瞬间窗口就关闭了报错信息一个都看不到剩下的只有“闪退”两个字。正确做法是从命令行启动产物让 stdout 和 stderr 都留在终端里。# 直接跑产物报错会打印在当前终端 ./dist/tool/tool # 或者用 cmd 在 Windows 上跑路径按实际替换 dist\tool\tool.exe # 打包阶段也可以打开详细日志观察依赖收集过程 pyinstaller -D -c -n tool --log-levelDEBUG main.py跑起来之后如果报ModuleNotFoundError基本可以确定是动态导入的模块没被静态分析扫到处理方式在 3.3 节。如果报的是某个.dll或.so加载失败多半是二进制依赖没被收进去看第 3.4 节。还有一份文件值得每次打包后翻一眼build/tool/warn-tool.txt。它记录了分析阶段所有“看着像依赖但没找到”的模块里面大部分是无害的可选导入但只要有你业务代码里实际用到的东西出现在里面就必须处理。2.4 onedir 和 onefile 怎么选取决于谁用两种形态没有绝对优劣选错了会在交付环节反复折腾。维度onedir-Donefile-F启动速度快直接加载慢每次启动先解压到临时目录分发形态一整个文件夹要打包压缩单个文件便于传输杀软误报相对低相对高自解压行为容易被拦截增量更新只替换变化的文件整体替换适合场景内部分发、体积大、启动频繁外发给非技术用户、文件数量要求少给团队内部用的工具我一律选 onedir。它启动快出问题时能直接进目录看依赖到底收没收进去升级也只用一个文件覆盖。真要做成“双击就能装”的形态正确路径是在 onedir 产物外面再套一层安装器而不是硬用 onefile 换来一个启动慢、还容易被安全软件拦下的单文件。3. spec 文件配置datas、hiddenimports、binaries 各管什么命令行参数能覆盖的场景很有限。只要项目带配置文件、模板、字体、外部可执行程序或者用到了动态导入就必须打开 spec 文件。它是 PyInstaller 真正的配置入口命令行参数只是它的快捷方式。3.1 什么时候该从命令行切换成 spec判断标准很简单当你要传的参数超过三个或者需要表达“把某个目录整个带进去”这类结构时就该切换了。用下面这条命令生成一份初始 spec然后所有构建都走它。# 生成 spec不再直接打包-D 决定基础形态 pyi-makespec -D -n tool main.py # 后续所有构建都基于 spec 文件命令行只留少量覆盖参数 pyinstaller --clean --noconfirm tool.spec生成出来的文件是标准 Python 语法里面Analysis、PYZ、EXE、COLLECT四段分别对应分析、字节码打包、可执行文件生成和目录收集。日常改动九成集中在Analysis这一段datas、binaries、hiddenimports、excludes四个字段都在这里。3.2 datas 的三元组写法与运行时路径datas里每一项是一个三元组源路径、产物内的目标目录、可选的目标文件名。常见写法是把整个目录带到产物里的同名目录下。# tool.spec 片段 a Analysis( [main.py], pathex[], binaries[], datas[ (assets/config.yaml, assets), # 单文件 - assets/config.yaml (assets/fonts, assets/fonts), # 整个目录递归带入 (templates, templates), ], hiddenimports[], hookspath[], runtime_hooks[], excludes[], noarchiveFalse, )带进去只是第一步代码里怎么找到它才是真正的坑。开发时用__file__拼相对路径没问题打包后这套逻辑会失效因为 onefile 形态下资源被解压到临时目录onedir 形态下可执行文件和源码的相对位置也完全不同。统一做法是写一个定位函数把sys._MEIPASS作为基准目录。import sys from pathlib import Path def resource_path(rel: str) - Path: 开发态和打包态都能定位到资源文件。 # PyInstaller 运行时会把资源解压目录挂到 sys._MEIPASS 上 base Path(getattr(sys, _MEIPASS, Path(__file__).resolve().parent)) return base / rel # 读取只读配置用这个函数写用户数据请用可写目录见下方说明 cfg resource_path(assets/config.yaml)这里有一条必须记住的边界sys._MEIPASS指向的目录是只读的、临时的程序退出后会被清理。日志、缓存、用户设置这类需要持久化的东西必须写到用户目录常见做法是Path.home() / .tool或者%APPDATA%并且首次启动时创建。曾经有项目把 SQLite 数据库路径写进resource_path本地测试一切正常交付后用户的配置每次重启都丢排查了很久才定位到这一行。3.3 hiddenimports静态分析扫不到的那部分PyInstaller 靠读字节码里的import语句建依赖图。凡是绕过语句的加载方式它都看不见importlib.import_module(myapp.plugins.foo)、__import__(name)、插件目录扫描、pkg_resources按入口点加载都属此列。表现是打包过程无报错运行时报某个模块找不到。手工一个个列hiddenimports很痛苦标准做法是用 PyInstaller 自带的收集工具按包名批量拉。# tool.spec 顶部 from PyInstaller.utils.hooks import collect_submodules, collect_data_files # 把插件包下所有子模块都显式声明绕开动态导入的扫描盲区 hidden collect_submodules(myapp.plugins) # 有些库的模块代码里还带数据文件一并收集 extra_datas collect_data_files(myapp.plugins) a Analysis( [main.py], datas[(assets/config.yaml, assets)] extra_datas, hiddenimportshidden, # ... )collect_submodules会把整个包展开代价是产物变大所以只对确实采用动态加载的包使用不要图省事对全项目跑一遍。另外有些第三方库自带官方 hookPyInstaller 里已经有对应处理常见于 GUI 框架和科学计算库这类不需要你手工补遇到时优先确认它有没有随包提供 hook别急着往hiddenimports里塞。3.4 binaries 与 runtime hook外部程序和 C 扩展binaries用于显式携带动态库三元组格式与datas一致区别在于它会被当作二进制放进产物并在启动时参与加载路径。多数情况下依赖会被自动收集只有那些通过ctypes.CDLL运行时拼路径加载的库需要手工补。如果你的程序调用了外部可执行文件比如调命令行工具做转码注意两点一是把可执行文件放进datas而不是binaries二是打包后要确认它有执行权限Linux/macOS 上需要额外chmod。这类外部依赖我更倾向放在程序安装目录旁边用配置项指定路径而不是塞进产物内部否则每次换版本都得重新打包。runtime_hooks解决的是“程序主逻辑开始前需要设置环境变量”的问题典型场景是把库需要的路径指向产物解压目录。# hook_env.py —— 在入口脚本执行前运行 import os import sys # 让依赖库能在打包后的临时目录里找到自己的资源 base getattr(sys, _MEIPASS, os.path.dirname(sys.executable)) os.environ.setdefault(MYAPP_HOME, base)写好后在 spec 里挂上runtime_hooks[hook_env.py]。这个文件会被编译进产物在main.py之前执行适合做环境变量初始化、路径注册这类前置动作。别在里面写耗时逻辑它会影响启动速度。4. 体积与启动速度excludes、UPX 和临时目录的三组取舍打包产物动辄几百兆是常见抱怨但体积从来不是靠一个参数解决的。得先知道空间花在哪再决定砍哪一块砍错了就是功能缺失或者启动变慢。4.1 先看清体积构成再动手拿到一个偏大的产物第一步是看里面到底装了什么不要凭感觉删模块。# 以交互方式查看产物打包内容能列出每个归档里的文件 pyi-archive_viewer dist/tool/tool # 目录形态的产物更简单直接按大小排序看 du -sh dist/tool/* | sort -rh | head -20常见的大头集中在几个方向科学计算库自带的二进制后端、GUI 框架的插件目录、绘图库的示例和测试数据、以及通过依赖链被动引入的完整框架。把它们列出来之后选择就清楚了——真正用到的留着被动带进来的用excludes排除。4.2 excludes 与虚拟环境裁剪的配合excludes是黑名单写进去的模块不会被收集。它的风险在于排多了会在运行时崩所以每加一项都要跑一次冒烟测试。a Analysis( [main.py], excludes[ tkinter, # 没用 GUI 就不要带 Tk matplotlib.tests, # 测试包永远不需要 numpy.f2py, # 不用 Fortran 接口可以去掉 IPython, # 交互式环境相关 pytest, ], # ... )比excludes更彻底的做法是回到 2.1 节的虚拟环境环境里根本不存在的东西打包器也收不进去。所以真正有效的体积治理顺序是——先保证环境干净再用excludes处理那些被依赖链硬拉进来的模块。顺序反了你会发现排除列表越写越长还是压不下去。4.3 UPX 的收益和它的代价UPX 是对产物里的二进制做压缩能在目录形态下再挤出可观的空间。启用方式是指定 UPX 可执行文件所在目录。# 指定 upx 所在目录构建时自动压缩可执行文件和 dll pyinstaller --clean --noconfirm --upx-dir /opt/upx tool.spec要不要用取决于分发环境。UPX 压缩过的二进制在部分安全软件眼里特征更可疑误报率会上升而且压缩和解压本身要花时间对启动速度有小幅影响。我的习惯是在 spec 里把几个关键库排除掉不压其余照压。# spec 中与 Analysis 同级 upx_exclude[vcruntime140.dll, qwindows.dll, python3*.dll]这几个是启动路径上的关键文件压缩收益不大但会影响加载。真正该压的是那些体积大、加载频次低的第三方库。4.4 启动速度onefile 的隐性成本onefile 形态每次启动都要把内部归档解压到临时目录程序越大、文件越多这段等待越明显。用户感知到的就是“点了图标要愣两秒才出界面”。缓解手段有三个。一是改用 onedir直接把解压成本消掉这是最有效的二是用--runtime-tmpdir指定一个固定目录避免每次落到系统临时目录里被清理策略干扰但要注意多用户场景下的权限问题三是减少hiddenimports的滥用收集进来的每个模块都会增加启动时的导入开销。# onefile 下指定解压目录路径要提前存在且可写 pyinstaller -F -c -n tool --runtime-tmpdir ./runtime main.py我的实际选择是启动频繁的工具一律 onedir只在“必须单文件传输”的场合用 onefile并提前告知使用者首次启动会慢一些。这个取舍提前说清楚比事后解释“为什么这么卡”省事得多。5. 避坑与排查五个让打包白干的血泪现场这一节记录的是反复出现、每次都让人想砸键盘的几类问题。按“现象 → 原因 → 解决”整理遇到时可以直接对照。5.1 打包成功双击一闪就退现象命令行里跑产物一切正常双击 exe 窗口闪一下消失没有任何提示。原因用了-w窗口模式但程序里还有未捕获的异常或者入口脚本在初始化阶段就崩了。窗口模式下没有控制台接管 stderr错误信息无处输出看起来就是“什么都没发生”。解决临时改回-c重新打包从终端启动看完整堆栈。定位到具体异常后再改回窗口模式并在入口处加全局异常捕获把 traceback 写到用户目录下的日志文件里。这个日志文件是交付后唯一的排查依据不能省。5.2 开发能读到配置打包后报文件不存在现象FileNotFoundError: assets/config.yaml但产物目录里明明能看到这个文件。原因代码里用的是相对__file__或者相对当前工作目录的路径。打包后工作目录变成用户双击时所在的目录__file__也不指向源码位置两种写法都会失效。解决统一走 3.2 节的resource_path。顺带检查所有open(xxx)、Path(xxx)的字面量路径这类写法在打包场景里全是隐患。改完之后用 onedir 产物在另一个目录下启动验证一次别在原地测。5.3 产物被安全软件拦截或直接删除现象产物刚生成就被隔离或者用户那边下载完打不开。原因onefile 的自解压行为、UPX 压缩后的二进制特征、缺少数字签名三者叠加会显著提高被判定为可疑的概率。解决优先改 onedir减少自解压行为关掉 UPX 对关键文件的压缩有条件的话对最终产物做代码签名。没有签名条件时至少在交付说明里写清楚文件来源和校验值让接收方能自行核对。5.4 用到多进程打包后疯狂弹窗或卡死现象程序启动后不断弹出新的进程窗口或者直接卡在启动阶段。原因Windows 上创建子进程的方式是 spawn子进程会重新执行入口脚本。打包后sys.executable指向产物本身如果没有正确声明入口就会无限递归启动自己。解决在入口脚本最外层加一行冻结支持调用位置必须在任何业务逻辑之前。import multiprocessing if __name__ __main__: # 打包后必须调用否则子进程会重新执行整个入口脚本 multiprocessing.freeze_support() main()这一行在开发态几乎无感打包后是硬性要求。凡是代码里出现Process、Pool、concurrent.futures.ProcessPoolExecutor的项目都要加上。5.5 目标机器缺少运行时库现象在自己机器上跑得好好的产物拷到另一台机器上报缺少某个 dll或者直接无法启动。原因目标机器没装对应的 Visual C 运行库或者系统版本较老缺少通用 C 运行库。这类依赖不会自动打进产物因为打包机上有收集器认为没必要带。解决把运行时库作为交付物的一部分随安装包一起分发或者在安装脚本里检测并提示。另一个常被忽略的点是目标机器的系统架构32 位和 64 位产物不能混用打包机的 Python 位数决定了产物位数交付前要确认清楚。6. 发布前的验证用 version_info 和冒烟脚本守住最后一关打包最后一步不是生成产物是确认产物在别人的机器上能跑。这一步做扎实能省掉后面大量的远程沟通。先补版本信息。默认产物在文件属性里什么信息都没有用户看到的是一个来路不明的 exe。用一份版本信息文件把它填上内容包括产品名、版本号、描述和版权声明。# version_info.py —— 供 spec 的 EXE 段引用 VSVersionInfo( ffiFixedFileInfo(filevers(1, 4, 0, 0), prodvers(1, 4, 0, 0)), kids[ StringFileInfo([StringTable(080404b0, [ StringStruct(CompanyName, 内部工具组), StringStruct(FileDescription, 数据整理工具), StringStruct(FileVersion, 1.4.0.0), StringStruct(ProductName, tool), ])]), VarFileInfo([VarStruct(Translation, [2052, 1200])]) ] )在 spec 的EXE(...)里挂上versionversion_info.py重新构建后产物属性里就有完整信息了。这东西看着是小事但在企业内网分发时没有版本信息的可执行文件经常被直接拦下。然后是冒烟脚本。手工点一遍不够尤其是每次改 spec 之后。写一个脚本把产物跑起来检查退出码和关键输出构建完自动执行。import subprocess import sys from pathlib import Path exe Path(dist/tool/tool.exe) if not exe.exists(): sys.exit(产物不存在构建可能失败) # 用 --selftest 这类自定义参数触发无副作用的启动路径 proc subprocess.run([str(exe), --selftest], capture_outputTrue, timeout120) if proc.returncode ! 0: sys.exit(f冒烟失败退出码 {proc.returncode}\n{proc.stderr.decode(errorsignore)}) print(冒烟通过)关键在--selftest这个约定在程序里留一个不触发实际业务、只做初始化和依赖检查的启动分支。有了它每次打包后都能自动验证“依赖收全了没有、资源能不能读到”不用人肉点界面。检查项检查方式不通过的典型表现依赖完整性冒烟脚本退出码启动即报 ModuleNotFoundError资源可读selftest 里读取一份配置文件不存在或内容为空版本信息查看产物文件属性属性页空白干净机器在无 Python 环境的机器上跑缺 dll、缺运行库权限用普通用户账户启动写临时目录失败最后一行是我踩过最多次的管理员账户下测试全过普通用户一启动就崩原因是程序试图往安装目录里写文件。从那以后我每次交付前都强制用一个普通账户在干净机器上走一遍完整流程包括写配置、导出文件这些会落盘的操作一个都不跳。希望帮到你。本文还有配套的精品资源点击获取