PyInstaller打包后ModuleNotFoundError的根源是动态导入未被自动识别，需用--hidden-import显式声明；推荐开发用--onedir、交付用--onefile并配合--add-data；Windows双击无响应应先禁用--windowed查错，macOS/Linux注意二进制依赖和系统环境一致性。
pyinstaller 打包后运行报错 ModuleNotFoundError 怎么办
根本原因不是代码写错了，而是 pyinstaller 没自动找到你用的模块。它只扫描 import 语句，但像 importlib.import_module、配置文件里写的模块名、甚至 __import__ 这种动态导入，它都看不见。
实操建议：
- 用
--hidden-import显式告诉它哪些模块必须打包进去，比如用了pkg_resources或yaml，就得加--hidden-import=yaml --hidden-import=pkg_resources - 如果项目用了
setuptools的 entry_points 或插件机制，大概率要配合--collect-all，例如--collect-all mypackage - 打包前先跑
pyinstaller --onefile --debug=all your_script.py，看日志里有没有WARNING: Hidden import提示，那是最直接的线索
打包成单文件（--onefile）还是目录（--onedir）
--onefile 看起来干净，但实际运行时会把所有东西解压到临时目录（Windows 是 %TEMP%，macOS/Linux 是 /tmp），首次启动慢、杀软可能误报、且无法热更新资源文件；--onedir 更贴近真实部署逻辑，调试也方便。
实操建议：
- 开发和测试阶段一律用
--onedir，打包完直接进生成的目录点开your_script就行，路径、图标、数据文件全都能对上 - 交付给终端用户才考虑
--onefile，但务必加--add-data把非 Python 文件带上，格式是--add-data "src;dst"（Windows 用分号，macOS/Linux 用冒号） - 如果脚本依赖本地配置或日志目录，
--onefile下__file__指向的是临时路径，得用sys._MEIPASS判断是否在打包环境里
Windows 上双击没反应、黑窗一闪而过
这是最典型的“程序启动就退出”表现，通常因为异常没被捕获，或者缺少控制台等待逻辑。尤其当你用 --windowed（即不弹命令行窗口）又没做 GUI 初始化时，进程直接结束。
实操建议：
- 先去掉
--windowed，用默认带控制台的方式打包，看看报什么错——90% 的情况是某处抛了未捕获异常 - 如果确实不需要控制台，又想看到错误，可以在入口加一段兜底：
try:
main()
except Exception as e:
import traceback
with open("error.log", "w") as f:
f.write(traceback.format_exc())
input("Press Enter to exit...")
- 检查是否用了相对路径读取文件，
--onefile下工作目录不等于可执行文件所在目录，要用os.path.dirname(sys.executable)或sys._MEIPASS定位资源
打包后 macOS/Linux 权限不足或找不到 libc
macOS 上常见 OSError: dlopen(...): image not found，本质是二进制依赖没被识别；Linux 上则容易遇到 ./your_app: No such file or directory，其实是动态链接器路径不对，不是文件真丢了。
实操建议：
- macOS：用
otool -L your_app查看依赖库路径，再用install_name_tool修正，但更省事的是打包时加--codesign-identity="-"和--osx-entitlements-file=ent.plist（哪怕空文件）来绕过 Gatekeeper 干预 - Linux：优先用与目标环境相同版本的系统打包（比如目标机是 CentOS 7，就在 CentOS 7 容器里打包），避免 glibc 版本不兼容；必要时加
--exclude-module=tkinter等非必需模块减小体积和依赖面 - 所有平台都建议加
--clean参数，避免旧缓存干扰新构建
真正麻烦的从来不是打包命令本身，而是你脚本里那些没显式 import 却在运行时才加载的东西，还有路径、权限、环境变量这些看不见的上下文——它们不会报错，只会让程序静默失败。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
