简介：PyInstaller 安装包面向需要将 Python 脚本打包为独立可执行文件的开发者，尤其适合希望把项目分发给未安装 Python 环境用户的初中级工程师。资源包共 19 个文件，以 10 个 txt 说明与测试文本、5 个 py 脚本、2 个 pkg-info 元数据、1 个 cfg 配置及 1 个 regen-docs 文档生成脚本为主，整体约 37KB，体积轻量，便于快速查阅源码结构与打包逻辑。内容涵盖 setup.py 安装入口、pyinstall.py 主程序、egg-info 依赖与顶层模块清单，以及 tests 目录下的基础打包、冻结与代理相关测试用例，可帮助读者理解 PyInstaller 早期版本的隐式依赖分析、静态链接与多平台输出机制。已有 588 人学习下载，适合作为研究打包工具实现原理、排查动态库依赖与非 Python 资源处理问题的参考素材。
1. 从脚本到可执行文件：pyinstaller 安装包到底解决了什么问题
你写了一个 Python 小工具，在自己电脑上跑得好好的，发给同事却直接报错——对方没装 Python，或者版本不对，或者缺了某个第三方库。这种场景几乎每个用 Python 做过交付的人都遇到过。pyinstaller 安装包就是用来终结这类尴尬的：它把 Python 解释器、依赖库和你的脚本一起打包成一个可执行文件，目标机器上不需要任何 Python 环境就能双击运行。听起来很美好，但实际操作中，打包出来的东西动辄几百兆、启动慢、杀毒软件误报、路径找不到文件，这些问题一个比一个让人头疼。这篇笔记面向的是需要把 Python 脚本交付给非技术用户的一线开发者，我会把 pyinstaller 的打包逻辑、参数配置、常见翻车场景和排查手段拆开讲清楚，让你拿到一个能直接抄的打包方案。
2. pyinstaller 打包机制与最小可复现流程
2.1 打包到底做了什么：从 .py 到 .exe 的链路
pyinstaller 的工作流程可以拆成三个阶段。第一阶段是分析阶段，它会从你的入口脚本开始，递归扫描所有 import 语句，构建一棵依赖树，把用到的模块、包、动态库都找出来。第二阶段是打包阶段，它把 Python 解释器（一个精简过的运行时）、依赖库的字节码、以及一个引导加载器（bootloader）塞进一个可执行文件或者一个目录里。第三阶段是运行时阶段，当你双击生成的 exe 时，引导加载器会先解压运行时环境到一个临时目录，然后启动 Python 解释器执行你的脚本。
这里有个关键点：pyinstaller 默认生成的是单文件模式（--onefile），它会把所有东西压缩进一个 exe，运行时先解压到系统临时目录再执行。这意味着每次启动都要经历一次解压过程，文件越大启动越慢。另一种模式是单目录模式（--onedir），它生成一个文件夹，里面包含 exe 和一堆依赖文件，启动时不需要解压，速度快很多，但交付时得把整个文件夹打包发给对方。
选哪种模式取决于你的交付场景。如果对方只需要一个文件、不介意多等几秒启动，用--onefile；如果追求启动速度、或者程序需要频繁启动，用--onedir更合适。我一般会先出--onedir版本做调试，确认没问题后再切--onefile做最终交付。
2.2 最小可复现打包流程：五条命令跑通
下面是一个从零开始的打包流程，假设你的入口脚本叫main.py，项目里用到了requests和pandas。
# 第一步：创建干净的虚拟环境，避免把系统里无关的包打进去 python -m venv venv # Windows 下激活 venv\Scripts\activate # macOS/Linux 下激活 source venv/bin/activate # 第二步：只安装项目真正需要的依赖 pip install requests pandas pyinstaller # 第三步：先用 --onedir 模式打一个调试版，方便看报错 pyinstaller --onedir --console main.py # 第四步：运行 dist/main/main.exe 测试功能是否正常 # 如果报错，看控制台输出，定位缺失的模块或路径问题 # 第五步：确认无误后，打单文件版做交付 pyinstaller --onefile --console --name MyTool main.py这几条命令里，--onedir和--onefile控制打包模式，--console表示保留控制台窗口（调试阶段必须加，否则报错信息看不到），--name指定生成的 exe 名称。第三步和第五步之间一定要做功能验证，不要直接跳到单文件模式，否则出了问题你连日志都找不到。
2.3 spec 文件：比命令行更可控的打包配置
命令行参数适合快速测试，但真正要精细控制打包行为，得靠 spec 文件。pyinstaller 第一次运行时会自动生成一个.spec文件，它本质上是一个 Python 脚本，描述了打包的完整配置。你可以直接编辑它，然后运行pyinstaller main.spec来打包。
# main.spec 关键字段说明 a = Analysis( ['main.py'], # 入口脚本路径 pathex=[], # 额外的模块搜索路径 binaries=[], # 需要额外打包的二进制文件 datas=[], # 需要打包的数据文件，格式为 (源路径, 目标路径) hiddenimports=[], # 隐式导入的模块，pyinstaller 扫描不到的 hookspath=[], # 自定义 hook 脚本路径 excludes=[], # 排除不需要的模块，减小体积 noarchive=False, # 是否将依赖打包成压缩归档 )datas和hiddenimports是两个最常改的字段。datas用来打包配置文件、图标、模板等非代码资源；hiddenimports用来手动补充那些通过动态导入（比如importlib.import_module）加载、pyinstaller 静态扫描不到的模块。比如你用到了pkg_resources或者某些插件的动态加载机制，就得在这里补上。
excludes也值得关注。如果你用了pandas，它会连带把numpy、scipy等一堆东西拉进来，但你可能只用到了read_csv。在excludes里排除掉matplotlib、scipy、PyQt5这类用不到的重量级库，能把打包体积从 300MB 压到 80MB 左右。
3. 资源文件、图标与隐藏导入：三个最容易翻车的地方
3.1 资源路径问题：为什么打包后找不到文件
这是 pyinstaller 最经典的坑。开发时你用open('config.json')能正常读取，打包后直接报FileNotFoundError。原因在于单文件模式下，运行时会把文件解压到一个临时目录，而你的代码用的是相对路径，工作目录变了，自然找不到。
解决办法是用sys._MEIPASS动态获取资源路径。pyinstaller 在运行时会把临时目录路径赋给这个属性，你需要写一个兼容函数：
import sys import os def resource_path(relative_path): """获取资源的绝对路径，兼容开发环境和 pyinstaller 打包环境""" if hasattr(sys, '_MEIPASS'): # 打包后，资源被解压到 sys._MEIPASS 指向的临时目录 base_path = sys._MEIPASS else: # 开发环境下，使用当前文件所在目录 base_path = os.path.abspath('.') return os.path.join(base_path, relative_path) # 使用示例 config_path = resource_path('config.json') with open(config_path, 'r', encoding='utf-8') as f: config = f.read()同时在 spec 文件的datas里声明资源文件：datas=[('config.json', '.')]，表示把项目根目录下的config.json打包到运行时根目录。注意目标路径写'.'而不是'/'，写错了文件会跑到奇怪的目录里去。
3.2 图标与版本信息：让 exe 看起来不像病毒
不加图标的 exe 用的是 pyinstaller 默认图标，很多杀毒软件会对这种“无名无姓”的可执行文件提高警惕。加上自定义图标和版本信息，能显著降低误报率。
# 准备一个 .ico 格式的图标文件（Windows 必须用 ico，不能用 png 直接改后缀） # 用 --icon 指定图标 pyinstaller --onefile --windowed --icon=app.ico --name MyTool main.py--windowed表示不显示控制台窗口，适合 GUI 程序。但注意，加了--windowed之后，所有print输出和未捕获的异常都不会显示，调试阶段千万别加。版本信息需要通过 spec 文件里的version参数指定一个版本资源文件，格式比较复杂，常见做法是用pyinstaller --version-file=version.txt生成模板后再改。
3.3 隐藏导入：那些 pyinstaller 看不见的模块
有些库的导入方式很隐蔽，比如通过字符串动态加载、或者在__init__.py里用exec导入。pyinstaller 的静态分析扫不到这些，打包后运行时报ModuleNotFoundError。
典型的例子包括pkg_resources、sqlalchemy的方言模块、pandas的某些可选后端。解决办法是在 spec 文件的hiddenimports里手动加上：
hiddenimports=[ 'pkg_resources', 'sqlalchemy.dialects.sqlite', 'pandas._libs.tslibs.base', ],怎么知道缺了哪个模块？看报错信息里的ModuleNotFoundError: No module named 'xxx'，把xxx加进去重新打包就行。如果报错信息被--windowed吞了，先用--console模式跑一遍，拿到完整错误再改。
4. 避坑与排查：五条血泪经验
4.1 打包体积异常膨胀
现象：一个几百行的脚本，打包出来 500MB 以上。
原因：虚拟环境不干净，或者依赖库连带拉入了大量用不到的子模块。比如pandas会拉入numpy、pytz、dateutil，如果还装了matplotlib、scipy，体积直接起飞。
解决：在干净的虚拟环境里打包，只装必要依赖；在 spec 的excludes里排除确认用不到的库；用--onedir模式先看dist目录里哪些文件夹最大，针对性排除。
4.2 杀毒软件误报
现象：生成的 exe 被 Windows Defender 或某数字杀毒软件直接隔离。
原因：pyinstaller 的引导加载器行为特征和某些恶意软件相似，加上没有签名和版本信息，触发启发式检测。
解决：加图标和版本信息；用--onedir模式代替--onefile（单文件模式解压行为更容易触发检测）；如果面向企业交付，考虑购买代码签名证书对 exe 签名。个人项目的话，把 exe 加到杀毒软件白名单是最省事的办法。
4.3 启动速度慢到无法接受
现象：双击 exe 后要等 5 到 10 秒才出现界面。
原因：单文件模式每次启动都要把几百兆内容解压到临时目录，机械硬盘上尤其明显。
解决：改用--onedir模式；或者用--onefile但配合--runtime-tmpdir指定一个固定目录，避免每次解压到不同的随机临时目录（但要注意多实例冲突）。如果必须单文件且追求速度，可以考虑用 Nuitka 替代，但那是另一个话题了。
4.4 打包后中文乱码
现象：程序里的中文输出变成乱码，或者读取中文文件报编码错误。
原因：Windows 控制台默认编码是 GBK，而 Python 3 默认用 UTF-8，两者不一致时就会乱码。
解决：在代码开头强制设置标准输出编码：
import sys import io sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8') sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')读取文件时始终显式指定encoding='utf-8'，不要依赖系统默认编码。
4.5 多进程程序打包后无限重启
现象：用了multiprocessing的程序，打包后一运行就不断弹出新窗口，直到系统卡死。
原因：Windows 下multiprocessing使用 spawn 方式启动子进程，子进程会重新执行入口脚本，而打包后的 exe 没有if __name__ == '__main__':保护，导致无限递归创建进程。
解决：确保所有多进程代码都在if __name__ == '__main__':块内调用，并且在入口处加上multiprocessing.freeze_support()：
import multiprocessing if __name__ == '__main__': multiprocessing.freeze_support() # 必须在任何多进程操作之前调用 # 你的主逻辑这个坑在开发阶段不会出现，只有打包后才会暴露，属于典型的“打包玄学”问题。
5. 进阶技巧：用 hook 机制解决复杂依赖与体积优化
当你打包的库越来越复杂，spec 文件里的hiddenimports和datas会越堆越多，这时候该考虑写自定义 hook 了。hook 是 pyinstaller 的扩展机制，它告诉 pyinstaller 某个特定库需要额外打包哪些文件、导入哪些模块。pyinstaller 自带了一批常用库的 hook，但冷门库或者你自己写的包就需要手动补。
hook 文件的命名规则是hook-<模块名>.py，放在项目目录下，然后在 spec 里通过hookspath指定搜索路径。一个典型的 hook 长这样：
# hook-mylib.py from PyInstaller.utils.hooks import collect_data_files, collect_submodules # 收集 mylib 包下所有数据文件 datas = collect_data_files('mylib') # 收集所有子模块，解决动态导入问题 hiddenimports = collect_submodules('mylib')collect_data_files会自动扫描包目录下的非 Python 文件（模板、配置、静态资源等），collect_submodules会递归找出所有子模块。这两个函数能省掉大量手动列举的工作。写完 hook 后，在 spec 里加上hookspath=['.']，pyinstaller 打包时就会自动加载。
另一个进阶方向是体积优化。除了excludes，还可以用 UPX 压缩。UPX 是一个开源的可执行文件压缩工具，pyinstaller 支持在打包时调用它压缩二进制文件。安装 UPX 后，在 spec 里设置upx=True，或者命令行加--upx-dir指定 UPX 路径。实测能把体积再压 30% 到 50%，但注意 UPX 压缩后的 exe 更容易被杀毒软件误报，需要权衡。
验证打包结果是否可靠，我习惯用一个 checklist 走一遍：在一台没装 Python 的干净机器上运行；测试所有涉及文件读写的功能；测试网络请求（如果有）；检查启动时间是否可接受；用杀毒软件扫描一遍。这套流程走下来，基本能覆盖 90% 的交付问题。
从那以后我每次打包前都强制走一遍干净虚拟环境加--onedir调试的流程，再也没出现过“在我电脑上好好的”这种尴尬。希望帮到你。
本文还有配套的精品资源，点击获取
