使用PyInstaller打包含QML的PyQt5程序遇崩溃问题求助

阿华AIGC实验室

2026-5-20

解决PyInstaller打包PyQt5+QML(Material主题)应用崩溃的问题

我帮你整理了一套实际踩坑后总结的解决方案，不管是Windows 10还是Ubuntu系统，都能搞定打包后崩溃的问题，核心就是解决QML依赖缺失、路径适配这两个常见坑。

一、先调整你的Python代码

首先得把代码里的路径逻辑改对，不然打包后程序根本找不到QML文件和Material主题资源。你原来的代码里os.environ的部分应该是用来设置QML路径的，我给你优化成打包前后都能自动适配的版本：

import os
import sys
from PyQt5.QtWidgets import QApplication
from PyQt5.QtCore import QUrl
from PyQt5.QtQml import QQmlApplicationEngine

if __name__ == "__main__":
    app = QApplication(sys.argv)
    
    # 关键：动态适配打包前后的QML模块路径
    # 先尝试找Python环境下的PyQt5 QML目录
    pyqt5_qml_path = os.path.join(os.path.dirname(sys.executable), "Lib", "site-packages", "PyQt5", "qml")
    # 如果是打包后的可执行文件，路径会变，就找当前目录下的qml文件夹
    if not os.path.exists(pyqt5_qml_path):
        pyqt5_qml_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "qml")
    
    # 设置QML导入路径，让Qt能找到Material主题
    os.environ["QML2_IMPORT_PATH"] = pyqt5_qml_path
    # 强制指定使用Material风格
    os.environ["QT_QUICK_CONTROLS_STYLE"] = "Material"

    engine = QQmlApplicationEngine()
    # 用绝对路径加载QML文件，避免打包后路径混乱
    qml_file_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "main.qml")
    engine.load(QUrl.fromLocalFile(qml_file_path))

    if not engine.rootObjects():
        sys.exit(-1)
    
    sys.exit(app.exec_())

二、Windows 10下的打包步骤

准备文件：确保你的material.py和main.qml（QML入口文件）在同一个文件夹，而且QML里正确导入了Material模块，比如import QtQuick.Controls.Material 2.15。
安装依赖：如果还没装pyinstaller和PyQt5，先跑命令：

pip install pyinstaller PyQt5 PyQt5-Qt5

生成并编辑spec文件：用spec文件打包比直接命令行可控太多，先生成基础模板：

pyi-makespec --onefile --windowed material.py

打开生成的material.spec，修改这两个部分：

datas字段：添加需要打包的QML资源，把PyQt5里的Material相关QML模块复制到打包后的目录：

import os
import sys

datas = [
    # 把你的QML文件复制到打包根目录
    ('main.qml', '.'),
    # 复制PyQt5的QML核心模块
    (os.path.join(sys.executable, 'Lib', 'site-packages', 'PyQt5', 'qml', 'QtQuick'), 'QtQuick'),
    (os.path.join(sys.executable, 'Lib', 'site-packages', 'PyQt5', 'qml', 'QtQuick.Controls'), 'QtQuick.Controls'),
    (os.path.join(sys.executable, 'Lib', 'site-packages', 'PyQt5', 'qml', 'QtQuick.Controls.Material'), 'QtQuick.Controls.Material'),
    (os.path.join(sys.executable, 'Lib', 'site-packages', 'PyQt5', 'qml', 'QtGraphicalEffects'), 'QtGraphicalEffects'),
]

hiddenimports字段：告诉PyInstaller不要漏掉PyQt5的QML相关模块：
```
hiddenimports = ['PyQt5.QtQml', 'PyQt5.QtQuick', 'PyQt5.QtQuick.Controls']
```

开始打包：

pyinstaller material.spec

测试程序：进入dist文件夹，双击material.exe。如果还是崩溃，别直接点图标，打开命令行运行它，就能看到具体的错误提示（比如找不到哪个QML模块），然后把对应的模块补充到datas里就行。

三、Ubuntu下的打包步骤

Ubuntu的逻辑和Windows差不多，但路径依赖系统环境，需要多一步系统库安装：

安装系统级Qt依赖：PyQt5可能依赖系统的Qt库，先装这些：

sudo apt install qt5-default qtquickcontrols2-5-dev qml-module-qtquick-controls2 qml-module-qtquick-controls2-material

生成spec文件：

pyi-makespec --onefile --windowed material.py

编辑spec文件：Ubuntu下PyQt5的QML路径分系统环境和虚拟环境，所以写个判断逻辑：

import os
import sys

# 自动识别PyQt5的QML路径
if sys.prefix == '/usr':
    # 系统级Python环境
    pyqt5_qml_dir = '/usr/lib/python3/dist-packages/PyQt5/qml'
else:
    # 虚拟环境
    pyqt5_qml_dir = os.path.join(sys.prefix, 'lib', sys.version.split()[0], 'site-packages', 'PyQt5', 'qml')

datas = [
    ('main.qml', '.'),
    (os.path.join(pyqt5_qml_dir, 'QtQuick'), 'QtQuick'),
    (os.path.join(pyqt5_qml_dir, 'QtQuick.Controls'), 'QtQuick.Controls'),
    (os.path.join(pyqt5_qml_dir, 'QtQuick.Controls.Material'), 'QtQuick.Controls.Material'),
    (os.path.join(pyqt5_qml_dir, 'QtGraphicalEffects'), 'QtGraphicalEffects'),
]

hiddenimports = ['PyQt5.QtQml', 'PyQt5.QtQuick', 'PyQt5.QtQuick.Controls']

打包并测试：

pyinstaller material.spec

进入dist目录运行./material，如果有错误，用命令行看提示，比如缺库就用ldd ./material检查依赖，然后安装对应的包。

四、常见崩溃排查技巧

QML模块找不到：这是最常见的，打包后运行会提示“module not found”，解决办法就是把对应的QML模块文件夹加到datas里。
路径混乱：代码里别用相对路径加载QML，一定要用绝对路径，不然打包后程序的工作目录不是你想的位置。
环境变量没设置：QML2_IMPORT_PATH必须指向QML模块的目录，不然Qt找不到Material主题。
系统库缺失：Ubuntu下容易缺系统Qt库，用apt装对应的开发包就行；Windows下如果缺PyQt5的库，手动从Python环境的Lib/site-packages/PyQt5里复制到dist文件夹。

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