使用PyInstaller打包KivyMD应用遇FactoryException：找不到MDTopAppBar类

开发者阿泽

2026-7-21

问题描述

使用PyInstaller为Windows系统打包Python/KivyMD应用时，已按Kivy文档修改spec文件，但运行生成的exe报错：

kivy.factory.FactoryException: No class named <MDTopAppBar> in module <kivymd.uix.toolbar>
[20136] Failed to execute script 'MyScriptName' due to unhandled exception!

未在.py文件中直接导入该依赖，仅在KV字符串定义UI时使用了MDTopAppBar组件。当前主要包版本：

kivy                      2.1.0
kivy-deps-angle           0.3.3
kivy-deps-glew            0.3.1
kivy-deps-gstreamer       0.3.3
kivy-deps-sdl2            0.4.5
kivy-examples             2.1.0
kivy-garden               0.1.5
kivymd                    1.1.1
pyinstaller               5.5
pyinstaller-hooks-contrib 2022.10
python                    3.7.10
python-dateutil           2.8.2
python_abi                3.7

解决方法

显式导入组件模块：在主Python文件开头直接导入MDTopAppBar所在模块，PyInstaller会识别到该依赖并打包：
```
from kivymd.uix.toolbar import MDTopAppBar
```
也可以批量导入模块：
```
from kivymd.uix import toolbar
```

修改spec文件添加隐藏导入：若不想在代码中添加冗余导入，可修改spec文件的hiddenimports列表，加入对应模块路径：

a = Analysis(
    ['MyScriptName.py'],
    pathex=[],
    binaries=[],
    datas=[],
    hiddenimports=['kivymd.uix.toolbar'],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    noarchive=False,
)

之后用修改后的spec文件重新打包：

pyinstaller MyScriptName.spec

检查并更新PyInstaller钩子：PyInstaller的hooks-contrib理论上包含KivyMD相关钩子，但部分组件可能未覆盖。若上述方法无效，可尝试更新pyinstaller-hooks-contrib至最新版本，或手动确认钩子文件是否包含kivymd.uix.toolbar的导入配置。