PyInstaller打包moderngl应用报缺失glcontext模块问题

问题复现 #

最小复现代码如下：

import moderngl as mgl
import pygame as pg

pg.init()
screen = pg.display.set_mode((800, 600), pg.DOUBLEBUF | pg.OPENGL)
gl_ctx = mgl.create_context(require=330)

clock = pg.time.Clock()
while True:
    for event in pg.event.get():
        if event.type == pg.QUIT:
            pg.quit()
            quit()
    clock.tick(30)

使用如下命令执行打包：

pyinstaller --onefile test_gl.py

打包完成后运行dist目录下生成的exe文件，未出现预期的空白窗口，反而抛出如下报错：

Traceback (most recent call last):
  File "test_gl.py", line 6, in <module>
  File "moderngl\context.py", line 1619, in create_context
ModuleNotFoundError: No module named 'glcontext'
[7428] Failed to execute script 'test_gl' due to unhandled exception!

复现所用环境版本：

• Python 3.10.4
• PyInstaller 4.10
• PyGame 2.1.2（配套SDL 2.0.18，适配Python 3.10.4）
• moderngl 5.6.4

故障原因 #

moderngl创建OpenGL上下文依赖的glcontext模块为运行时动态导入，PyInstaller默认的静态依赖扫描仅能识别代码中显式通过import/from ... import语法声明的模块，无法识别这类动态加载的隐式依赖，因此不会将glcontext打包进最终生成的可执行文件，触发模块找不到的报错。该场景完全支持正常打包，不存在版本兼容问题。

解决方法 #

• 先确认本地Python环境已正确安装glcontext依赖，执行如下命令避免本地环境缺包：

  pip install glcontext
  

• 打包时显式声明将glcontext作为隐藏依赖纳入打包范围，使用如下命令即可完成正常打包，生成的exe可直接运行弹出空白窗口：

  pyinstaller --onefile --hidden-import glcontext test_gl.py
  

• 若执行上述命令打包后仍存在加载异常（极个别情况会出现glcontext携带的平台相关二进制文件未被收集），直接将glcontext包下的所有文件全量收集进打包结果即可：

  pyinstaller --onefile --collect-all glcontext test_gl.py
  

注：PyInstaller不会自动收集项目的所有依赖，所有动态导入、插件式加载的模块都需要手动通过--hidden-import、--collect-all这类参数指定打包范围，这类问题在带C扩展、实现了插件系统的第三方库中非常常见。

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