PyInstaller 要求 Python 3.8–3.11（PyInstaller 6.0+ 不支持 3.7 及更早，6.2 起才支持 3.12）；Windows 推荐官方 MSVC 版 Python，macOS 需注意 arm64 架构兼容性；环境错位、动态资源未收集、路径逻辑失效是三大高频问题。
PyInstaller 要求什么 Python 版本和系统环境
PyInstaller 不支持所有 Python 版本，尤其新旧版本兼容性差得明显。比如 PyInstaller 6.0+ 已经彻底放弃对 Python 3.7 及更早版本的支持；反过来，Python 3.12 在 PyInstaller 6.2 之前也跑不起来，会报 ModuleNotFoundError: No module named 'distutils.util' 这类错误。
常见踩坑点：
- 用
conda创建的环境默认可能带旧版setuptools或distutils补丁，导致打包时看似成功、运行时报找不到模块 - Windows 上用 MSVC 编译的 Python（如 python.org 官方安装包）没问题，但用 MinGW 或某些定制版 Python（如 WinPython）可能缺
vcruntime140.dll，生成的 exe 启动直接闪退 - macOS 上如果用了
arm64架构的 Python，但没加--target-architecture=universal2，打出来的 app 在 Intel Mac 上就打不开
pip install pyinstaller 之后为什么 import 失败或命令不存在
根本原因通常是环境错位：你用 pip install pyinstaller 装到了 A 环境，却在 B 环境里运行 pyinstaller 命令，或者 IDE 没刷新 shell 的 PYTHONPATH / PATH。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 装完立刻执行
which pyinstaller（macOS/Linux）或where pyinstaller（Windows），确认路径指向当前激活环境的bin/或Scripts/目录 - 在 VS Code 里改完环境后，必须重启终端，不能只关掉再开一个新 tab —— 新 tab 默认继承旧 shell 的环境变量
- 如果用
python -m PyInstaller替代pyinstaller命令，能绕过 PATH 查找问题，但要注意大小写：PyInstaller是模块名，首字母大写
打包含 tkinter / PyQt / matplotlib 的 GUI 程序总缺图标或启动黑窗
这类库依赖大量动态资源（图片、字体、插件 DLL、.so/.dylib），PyInstaller 默认不会自动收集，得手动干预。
关键动作：
- 用
--onefile打包 tkinter 程序时，务必加--add-binary把tcl和tk目录带进去，否则启动报can't find Tcl/Tk；路径得按实际 Python 安装位置找，比如--add-binary "/usr/local/lib/python3.9/tcl8.6:tcl8.6" - PyQt5/6 必须加
--collect-all PyQt5（或PyQt6），否则QApplication初始化失败，错误信息是qt.qpa.plugin: Could not load the Qt platform plugin "xcb"（Linux）或类似平台插件缺失提示 - macOS 上打包后图标显示为空白？不是图标格式问题，而是没加
--icon=app.icns，且app.icns必须是真·icns 格式（不能用 png 转换完就完事），可用iconutil命令验证
打包后程序运行报错 “failed to execute script xxx” 怎么快速定位
这个错误本身没信息量，本质是 PyInstaller 把异常吞掉了。真正原因藏在启动时的 stderr 里，而 --onefile 模式下这些输出默认被重定向或丢弃。
排查路径：
- 先去掉
--onefile，用--onedir打包，然后进生成的dist/xxx/目录，直接运行主程序（如./xxx或xxx.exe），终端就能看到原始 traceback - 如果必须用
--onefile，加--console（Windows）或确保没加--windowed，让错误堆栈打到控制台 - 常见隐形依赖：用
open()读配置文件却没用--add-data把文件打进包；用importlib.resources读包内资源，但 PyInstaller 5.0+ 需要额外加--collect-all或用hook
最麻烦的其实是相对路径逻辑——打包后 __file__ 指向临时解压目录，不是源码位置，很多脚本靠 os.path.dirname(__file__) 找资源，一打包就断链。这点没人提，但几乎每个 GUI 工具都会撞上一次。
