简介：这份PDF教程面向需要在Windows平台发布Python程序的开发者与运维人员，系统讲解PyInstaller的安装与打包流程，帮助把Python源码转化为无需环境即可双击运行的.exe文件，兼顾源码保护与交付便利。资源包共1个PDF文件，大小约444KB，内容以图文步骤与命令实例为主，涵盖-F、-D、-w、-c、-p、-i、-v、-h等常用参数说明，并给出从源码包解压、setup.py安装到版本验证的完整路径。教程还以PyQt5界面程序为例，演示如何生成带自定义图标的独立可执行文件，并说明__pycache__、build、dist、app.spec等生成物的作用与最终exe的定位。目前已有946人学习下载，适合希望快速掌握Windows下Python打包技能、排查依赖缺失与打包异常的读者参考。
1. 把 Python 脚本变成 exe：为什么 Win 下 PyInstaller 是绕不开的那条路
在 Windows 上写完一个 Python 小工具，双击运行的前提是对方机器上装了 Python 和一堆依赖，这件事在真实交付场景里几乎不可接受。PyInstaller 解决的就是这个痛点：把解释器、字节码、第三方库和资源文件一起打包成单个 exe，目标机器不装 Python 也能跑。它支持 Windows、Linux、macOS 三端，但在 Win 下的使用频率最高，因为大量内部工具、批处理脚本、GUI 小软件最终都要以 exe 形式发给非技术同事。这篇笔记面向两类人：刚写完脚本想打包的新手，以及打过几次包但总被体积、闪退、缺 DLL 折磨的熟手。下面从安装、最小打包、参数调优、资源处理一路讲到排错，全部基于命令行实操。
2. 安装与最小可运行打包：先把第一个 exe 跑起来
2.1 环境准备与安装命令
PyInstaller 本身是纯 Python 包，安装没有编译环节，但有几个前置条件必须确认。第一，Python 版本建议 3.8 到 3.12，太老的版本对新版 PyInstaller 支持不好，太新的版本可能遇到 hook 未跟进。第二，确认 pip 可用且指向正确的解释器，多 Python 环境是翻车重灾区。第三，如果打包的是 GUI 程序，提前确认 GUI 库版本，tkinter 随 Python 自带，PyQt/PySide 需要单独装。
# 确认当前 pip 绑定的 Python 版本和路径 python -m pip --version # 安装 PyInstaller，指定国内镜像加速 python -m pip install pyinstaller -i https://pypi.tuna.tsinghua.edu.cn/simple # 验证安装，输出应为 PyInstaller: x.x.x pyinstaller --version这里用python -m pip而不是直接pip，是为了避免 PATH 里 pip 指向另一个 Python 环境。镜像地址只是加速下载，不影响包内容。安装完成后pyinstaller命令会进入 Scripts 目录，如果提示找不到命令，说明 Scripts 没加进 PATH，此时用python -m PyInstaller代替即可，效果完全一样。
2.2 最小打包：一条命令生成 exe
准备一个最简单的脚本作为验证对象，比如打印一行文字并暂停，避免窗口一闪而过看不清结果。
# demo.py import time def main(): print("packed exe is running") time.sleep(3) # 暂停 3 秒，方便观察控制台输出 if __name__ == "__main__": main()执行打包命令：
# -F 打包成单个 exe，-c 保留控制台窗口 pyinstaller -F -c demo.py命令跑完后目录里会多出 build、dist 和 demo.spec 三部分。dist 里就是最终产物 demo.exe，双击应弹出控制台并显示文字。build 是中间缓存，spec 是打包配置描述文件，后续要改参数优先改 spec 而不是反复敲命令行。-F表示 onefile 模式，所有东西压进一个 exe，启动时会先解压到临时目录再运行，所以首次启动比多文件模式慢。-c表示保留控制台，GUI 程序应换成-w。
2.3 onefile 与 onedir 的取舍
很多人默认用-F，但 onefile 并不总是最优。onefile 启动时要解压到%TEMP%下的临时目录，杀毒软件对这个行为敏感，容易误报；同时每次启动都有解压开销，大项目可能多等两三秒。onedir 模式生成一个文件夹，exe 和依赖平铺在一起，启动快、误报少，缺点是分发时要整个文件夹一起给。
| 模式 | 命令参数 | 启动速度 | 分发形式 | 适用场景 |
|---|---|---|---|---|
| onefile | -F | 较慢 | 单个 exe | 小工具、临时分发 |
| onedir | -D（默认） | 快 | 文件夹 | 大型项目、频繁启动 |
我的习惯是：内部工具用 onedir，对外交付的小工具用 onefile。如果对方只想要一个文件，再考虑 onefile，并提前做好杀毒误报的心理准备。
3. 参数调优与资源打包：让 exe 体积和路径都可控
3.1 常用参数逐个说清
PyInstaller 的参数不少，但日常真正要调的就这么几个。下面这张表是我反复用过之后留下的核心集合。
| 参数 | 作用 | 典型用法 |
|---|---|---|
| -F / -D | 单文件 / 文件夹模式 | 小工具 -F |
| -c / -w | 保留 / 隐藏控制台 | GUI 用 -w |
| -n | 指定 exe 名称 | -n MyTool |
| -i | 指定图标 | -i app.ico |
| --add-data | 打包额外资源 | --add-data "cfg;cfg" |
| --hidden-import | 强制导入模块 | --hidden-import pkg.mod |
| --exclude-module | 排除无用模块 | --exclude-module tkinter |
| --clean | 清理缓存后打包 | 排错时加 |
--add-data的写法在 Windows 上用分号分隔源和目标，Linux/macOS 用冒号，这是跨平台打包时最容易写错的地方。--hidden-import用于那些动态导入、PyInstaller 静态分析扫不到的模块，比如通过importlib加载的插件。--exclude-module是减小体积的利器，把明确用不到的库排掉，比如纯命令行工具可以排除 tkinter、matplotlib。
3.2 资源路径：打包后找不到文件的根因
新手最常见的翻车是：脚本里用相对路径读配置文件，开发时正常，打包后报 FileNotFoundError。原因是 onefile 模式下运行时会把资源解压到临时目录，__file__指向的位置和开发时完全不同。正确做法是用sys._MEIPASS判断运行环境。
# resource_path.py import os import sys def resource_path(relative): # 打包后 PyInstaller 会把资源解压到 sys._MEIPASS base = getattr(sys, "_MEIPASS", os.path.abspath(".")) return os.path.join(base, relative) # 使用示例：读取同目录下的 config.json cfg = resource_path("config.json") with open(cfg, "r", encoding="utf-8") as f: print(f.read())getattr(sys, "_MEIPASS", ...)的意思是：打包环境下取_MEIPASS，开发环境下退回到当前目录。这样同一份代码在开发和打包后都能找到资源。注意--add-data的目标路径要和resource_path里的相对路径对齐，否则依然找不到。
3.3 用 spec 文件固化打包配置
命令行参数一多就容易漏，正确姿势是第一次用命令行生成 spec，之后改 spec 再执行pyinstaller xxx.spec。spec 本质是一个 Python 脚本，可以写逻辑。
# demo.spec 关键片段 a = Analysis( ['demo.py'], pathex=[], binaries=[], datas=[('config.json', '.')], # 把 config.json 放到根目录 hiddenimports=['pkg.mod'], # 动态导入的模块 excludes=['tkinter', 'matplotlib'], # 排除无用库 hookspath=[], ) pyz = PYZ(a.pure) exe = EXE(pyz, a.scripts, a.binaries, a.datas, name='MyTool', console=False, icon='app.ico')datas里每个元组是「源路径, 打包内目标路径」，目标路径用点表示根目录。excludes直接砍掉不需要的库，对体积影响立竿见影。改完 spec 后执行pyinstaller demo.spec --clean，--clean会清掉 build 缓存，避免旧缓存导致的玄学问题。
4. 避坑与排查：那些让 exe 闪退、误报、体积爆炸的坑
4.1 双击闪退，命令行却正常
现象：双击 exe 窗口一闪而过，用 cmd 手动运行却能看到报错。原因：程序启动早期就抛异常，控制台来不及显示。解决：先用-c保留控制台打包，在 cmd 里运行看完整堆栈；定位到具体异常后再改代码。如果是 GUI 程序，把主逻辑包在 try/except 里写日志到文件，别让异常静默吞掉。
4.2 杀毒软件误报或直接删除 exe
现象：exe 生成后被杀毒软件隔离，或运行时弹窗拦截。原因：onefile 模式的自解压行为、无签名、以及 PyInstaller 引导程序的特征，都容易触发启发式查杀。解决：优先改用 onedir 模式；给 exe 加图标和版本信息；对交付场景考虑代码签名证书；把产物目录加入白名单。这是行业普遍现象，不是代码有问题。
4.3 打包体积几百 MB
现象：一个几十行的脚本打出来 200MB 以上。原因：PyInstaller 会把分析到的整个依赖树打进去，numpy、pandas、matplotlib 这类库体积巨大，即使只用了其中一小部分。解决：用--exclude-module排除确认不用的库；检查是否误引入了重量级依赖；用虚拟环境打包，避免把全局环境里的无关包带进去。虚拟环境这一条最有效，强烈建议每个项目单独建 venv 再打包。
4.4 缺少 DLL 或模块导入失败
现象：运行时报ImportError或DLL load failed。原因：某些库用动态方式加载模块或 DLL，PyInstaller 静态分析扫不到。解决：用--hidden-import补模块，用--add-binary补 DLL；先查该库有没有官方 hook，PyInstaller 自带大量 hook，但新库可能没覆盖。遇到这类问题，去 build 目录看 warn 文件，里面会列出未找到的模块，是排查的第一手线索。
4.5 中文路径或空格路径导致失败
现象：项目放在含中文或空格的目录下，打包报错或运行异常。原因：部分工具链对非 ASCII 路径和空格处理不完善。解决：把项目移到纯英文、无空格的短路径下再打包，比如D:\proj\demo。这是血泪经验，很多莫名其妙的报错换个路径就消失了。
5. 进阶技巧：用虚拟环境加自动化脚本把打包变成一条命令
打包这件事做多了就会发现，真正费时间的不是敲命令，而是环境不干净导致的体积膨胀和依赖冲突。我的固定做法是：每个项目建独立 venv，只装运行必需的包，然后用一个批处理脚本把「建环境、装依赖、打包、清理」串起来，一条命令出结果。
# build.bat 放在项目根目录 @echo off REM 1. 创建并激活虚拟环境 python -m venv .venv call .venv\Scripts\activate.bat REM 2. 只装运行必需依赖 python -m pip install --upgrade pip python -m pip install -r requirements.txt python -m pip install pyinstaller REM 3. 用 spec 打包并清理缓存 pyinstaller demo.spec --clean --noconfirm REM 4. 退出虚拟环境 deactivate echo build done, check dist folder这个脚本的价值在于可复现：换一台机器、换一个同事，跑同一个 bat 得到同样的产物。--noconfirm表示覆盖输出目录时不询问，适合自动化。requirements.txt里只写运行必需的包，开发用的 pytest、flake8 不要写进去，否则会被打进 exe。
再进一步，如果打包频繁，可以把版本号、图标、输出名都参数化，用 spec 里的变量控制。验证打包是否成功，不要只看 exe 生成了没有，要在一个干净的、没装 Python 的环境里实际跑一遍，这才是真正的验收。我吃过亏：本机测试全过，发到同事电脑上因为缺 VC++ 运行库直接崩，后来养成习惯，交付前一定找一台干净机器验证。
最后一个具体技巧：如果 exe 启动慢，用 onedir 模式并把整个文件夹做成自解压包分发，既保留启动速度，又满足「一个文件」的交付要求。打包没有银弹，核心就是环境干净、路径正确、按需排除，剩下的交给反复验证。希望帮到你。
本文还有配套的精品资源，点击获取
