PyInstaller打包GTK应用后缺失cairo依赖致图形绘制失败

问题根源 #

PyInstaller无法自动检测到GTK通过GI间接调用的cairo绑定依赖，导致打包后的程序找不到cairo.Context的转换器。

解决方案 #

1. 显式导入cairo模块 #

在主程序文件（App.py）开头添加以下代码（即使你没有直接使用cairo），让PyInstaller能扫描到这个隐式依赖：

import gi
gi.require_version('Gtk', '3.0')  # 替换为你实际使用的GTK版本
gi.require_version('cairo', '1.0')
from gi.repository import Gtk, cairo

2. 使用--hidden-import参数强制包含依赖 #

如果不想修改代码，直接在打包命令中添加隐藏导入参数：

sudo pyinstaller App.py --onefile --hidden-import gi.repository.cairo --hidden-import gi._gi_cairo

3. 自定义.spec文件配置 #

如果上述方法无效，通过spec文件更精确控制打包流程：

1. 生成spec文件：

   pyinstaller App.py --onefile --specpath .
   

2. 打开生成的App.spec，找到hiddenimports字段，添加缺失的依赖：

   a = Analysis(
       ['App.py'],
       # 保留其他原有配置
       hiddenimports=['gi.repository.cairo', 'gi._gi_cairo'],
       # 保留其他原有配置
   )
   

3. 用spec文件重新打包：

   sudo pyinstaller App.spec
   

4. 验证打包结果 #

运行打包后的可执行文件，检查自定义图形是否正常渲染，控制台是否还出现TypeError: Couldn't find foreign struct converter for 'cairo.Context'错误。

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