使用PyInstaller打包Matplotlib与PySide2应用时出现cairo库缺失错误

一、错误原因拆解 #

你遇到的这个错误是Matplotlib初始化时的后端加载警告，核心逻辑是这样的：

• Matplotlib默认会尝试检测并加载系统中所有可用的渲染后端，GTK3Agg是其中一个依赖GTK3和cairo库的后端；
• 你的应用实际依赖的是PySide2对应的Qt5Agg后端，但打包过程中PyInstaller可能误引入了GTK3Agg的相关依赖项，而Windows环境下默认没有预装GTK3/cairo的系统级库，导致cairocffi加载失败，进而触发这个警告。

二、对应用的影响 #

目前你的打包程序能正常运行，说明：

• Matplotlib已经自动 fallback 到了兼容PySide2的Qt5Agg后端，实际渲染逻辑没有问题；
• 这个错误只是初始化阶段的非致命警告，不会影响现有功能。
  但存在两个潜在小问题：
• 打包后的程序体积可能冗余：因为PyInstaller可能打包了不需要的GTK3相关依赖；
• 如果后续代码中强制指定使用GTK3Agg后端，程序会直接崩溃。

三、具体解决方法 #

1. 显式指定Matplotlib后端（最直接） #

在你的Python代码最开头（导入Matplotlib之前）加上这段代码，强制Matplotlib使用Qt5Agg后端，避免它尝试加载其他不需要的后端：

import matplotlib
# 强制指定Qt5后端，适配PySide2
matplotlib.use('Qt5Agg')

2. 打包时排除冗余模块 #

使用PyInstaller打包时，通过命令行参数排除GTK3和cairo相关的冗余模块，减少体积并消除警告：

pyinstaller --exclude-module gtk3 --exclude-module cairo --exclude-module cairocffi your_script.py

如果使用spec文件打包，在Analysis部分的excludes列表中添加这些模块：

a = Analysis(
    ['your_script.py'],
    excludes=['gtk3', 'cairo', 'cairocffi'],
    # 其他参数...
)

3. （可选）补充系统级cairo库（不推荐，除非你确实需要GTK后端） #

如果你后续需要用到GTK3Agg后端，可以手动下载Windows版的cairo系统库，将相关DLL文件（libcairo-2.dll等）放到程序的打包目录中，但这个操作没必要，因为你已经在用PySide2的Qt后端了。

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