PyInstaller打包Kivy应用时出现hook模块导入失败报错

问题现象 #

使用PyInstaller将基于Kivy框架开发的Python应用打包为可执行文件时，流程中断抛出导入错误，具体报错信息如下：

PyInstaller.exceptions.ImportErrorWhenRunningHook: Failed to import module __PyInstaller_hooks_0_kivy required by hook for module /Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/PyInstaller/hooks/hook-kivy.py. Please check whether module __PyInstaller_hooks_0_kivy actually exists and whether the hook is compatible with your version of /Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/PyInstaller/hooks/hook-kivy.py: You might want to read more about hooks in the manual and provide a pull-request to improve PyInstaller.
761086 WARNING: stderr: PyInstaller.exceptions.ImportErrorWhenRunningHook: Failed to import module __PyInstaller_hooks_0_kivy required by hook for module /Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/PyInstaller/hooks/hook-kivy.py. Please check whether module __PyInstaller_hooks_0_kivy actually exists and whether the hook is compatible with your version of /Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/PyInstaller/hooks/hook-kivy.py: You might want to read more about hooks in the manual and provide a pull-request to improve PyInstaller.

核心报错原因 #

hook-kivy.py 依赖的 __PyInstaller_hooks_0_kivy 模块导入失败，通常由三类问题导致：

• PyInstaller版本与Kivy版本不匹配，内置的Kivy钩子不兼容当前安装的Kivy
• 之前打包生成的缓存文件损坏，干扰钩子加载流程
• Python版本过旧（如报错环境使用的Python3.7），新版PyInstaller不再对其做完整适配，导致钩子加载异常

修复步骤 #

按顺序执行以下操作，每步完成后可尝试重新打包验证：

• 升级核心依赖到兼容版本，在当前使用的Python环境中执行命令：

  pip install --upgrade pyinstaller kivy
  

  如果是macOS环境，额外安装Kivy的二进制依赖避免加载失败：

  pip install --upgrade kivy-deps-sdl2 kivy-deps-glew
  

• 清理旧打包缓存：删除项目根目录下的build、dist文件夹，以及和项目入口文件同名的.spec文件，避免旧缓存干扰新的打包流程。
• 如果升级后仍然报错，说明当前最新版PyInstaller和Python3.7兼容性不足，降级到适配Python3.7的最后一个稳定版PyInstaller即可：

  pip install pyinstaller==4.10
  

• 若上述操作都无效，打包时显式指定Kivy的资源路径，跳过钩子自动扫描逻辑：

  pyinstaller --windowed 你的入口文件名.py --add-data "$(python -c 'import kivy; print(kivy.__path__[0])')/data:kivy/data"
  

注意：执行所有pip命令前，确认当前终端激活的Python环境和你开发Kivy应用使用的环境一致，避免包装到其他环境导致不生效。

内容的提问来源于stack exchange，提问作者Anas