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。

实操建议：

• 装完立刻执行 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 默认不会自动收集，得手动干预。

Secure Python Code Sandbox

安全 Python 代码沙箱：在隔离的沙箱中执行任意 Python 代码，预装 requests、NumPy、pandas 库。返回 stdout、stderr。

下载

关键动作：

• 用 --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 工具都会撞上一次。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！