Pyinstaller打包Qml+Qt3D程序运行报错Unable to find renderer plugin for opengl

该报错本质是PyInstaller打包过程中没有自动捕获Qt3D依赖的OpenGL渲染插件，本地开发环境运行时可以直接读取Python站点包内的Qt插件目录，打包后的隔离运行环境缺失对应插件，因此触发加载失败。

报错信息：Unable to find renderer plugin for opengl

• 第一步定位你的Qt插件路径，不同绑定版本的默认路径如下（替换为你自己的Python环境路径）：
  • PyQt5：{你的Python根目录}/Lib/site-packages/PyQt5/Qt/plugins
  • PySide2/PySide6：{你的Python根目录}/Lib/site-packages/PySide2/Qt/plugins
    进入该目录后可以找到renderers文件夹，内部包含openglrenderer.dll（Windows）就是需要打包的核心插件。
• 第二步修改PyInstaller打包配置，添加插件拷贝规则：
  直接使用命令打包的话，添加--add-data参数，示例（Windows环境）：

  pyinstaller -F -w main.py --add-data "C:/Python39/Lib/site-packages/PyQt5/Qt/plugins/renderers;renderers"
  

  如果你使用spec文件配置打包，修改spec文件的datas字段：

  datas = [
      ("C:/Python39/Lib/site-packages/PyQt5/Qt/plugins/renderers", "renderers"),
      # 如果需要加载stl文件，建议同时打包sceneparsers插件，避免后续解析错误
      ("C:/Python39/Lib/site-packages/PyQt5/Qt/plugins/sceneparsers", "sceneparsers"),
  ]
  

• 部分环境下需要手动指定Qt插件加载路径，在代码入口最开头添加以下逻辑：

  import os
  import sys
  from PyQt5.QtCore import QCoreApplication
  
  # 打包运行状态下强制指定插件路径
  if getattr(sys, "frozen", False):
      QCoreApplication.addLibraryPath(sys._MEIPASS)
  

打包完成后运行生成的exe文件前，先检查打包目录下是否存在renderers/openglrenderer.dll文件，确认插件已经被正确拷贝到对应路径，即可排除该报错。

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