后端 (Backends)

什么是后端？

后端用于在屏幕上显示 Matplotlib 图形（参见 图形简介），或将其写入文件。网站和邮件列表中的许多文档都提到了“后端”，很多新用户对这个术语感到困惑。Matplotlib 针对许多不同的使用场景和输出格式。有些人从 Python shell 交互式使用 Matplotlib，并在输入命令时弹出绘图窗口。有些人运行 Jupyter 笔记本并绘制内联图形以进行快速数据分析。另一些人则将 Matplotlib 嵌入到像 PyQt 或 PyGObject 这样的图形用户界面中，以构建功能丰富的应用程序。还有一些人在批处理脚本中使用 Matplotlib 从数值模拟中生成 PostScript 图像，甚至还有人运行 Web 应用服务器来动态提供图表。

为了支持所有这些用例，Matplotlib 可以针对不同的输出，这些能力中的每一个都被称为后端；“前端”是面向用户的代码，即绘图代码，而“后端”则在幕后完成所有艰苦的工作来生成图形。后端有两种类型：用户界面后端（用于 PyQt/PySide、PyGObject、Tkinter、wxPython 或 macOS/Cocoa；也称为“交互式后端”）和用于制作图像文件（PNG、SVG、PDF、PS；也称为“非交互式后端”）的硬拷贝后端。

选择后端

有三种配置后端的方法

• matplotlibrc 文件中的 rcParams["backend"] 参数

• MPLBACKEND 环境变量

• matplotlib.use() 函数

以下是更详细的说明。

如果存在多个配置，则列表中最后一个配置优先；例如，调用 matplotlib.use() 将覆盖 matplotlibrc 文件中的设置。

如果没有显式设置后端，Matplotlib 会根据系统可用情况以及是否已经运行了 GUI 事件循环，自动检测可用的后端。以下列表中的第一个可用后端将被选中：MacOSX, QtAgg, GTK4Agg, Gtk3Agg, TkAgg, WxAgg, Agg。最后一个 Agg 是一个非交互式后端，只能写入文件。如果在 Linux 上 Matplotlib 无法连接到 X 显示或 Wayland 显示，则使用此后端。

以下是配置方法的详细说明

1. 在 matplotlibrc 文件中设置 rcParams["backend"]

   backend : qtagg   # use pyqt with antigrain (agg) rendering
   

   另请参阅 使用样式表和 rcParams 自定义 Matplotlib。

2. 设置 MPLBACKEND 环境变量

   您可以为当前 shell 或单个脚本设置环境变量。

   在 Unix 上

   > export MPLBACKEND=qtagg
   > python simple_plot.py
   
   > MPLBACKEND=qtagg python simple_plot.py
   

   在 Windows 上，只能使用前者

   > set MPLBACKEND=qtagg
   > python simple_plot.py
   

   设置此环境变量将覆盖任何 matplotlibrc 中的 backend 参数，即使当前工作目录中存在 matplotlibrc 也是如此。因此，不建议全局设置 MPLBACKEND（例如在 .bashrc 或 .profile 中），因为它可能导致违反直觉的行为。

3. 如果您的脚本依赖于特定的后端，可以使用 matplotlib.use() 函数

   import matplotlib
   matplotlib.use('qtagg')
   

   这应该在创建任何图形之前完成，否则 Matplotlib 可能无法切换后端并引发 ImportError。

   如果用户想要使用不同的后端，使用 use 将需要更改您的代码。因此，除非绝对必要，否则应避免显式调用 use。

内置后端

默认情况下，Matplotlib 应该自动选择一个允许交互式工作和从脚本绘图的默认后端，并将输出显示在屏幕上或写入文件中，因此至少最初您不必担心后端问题。最常见的例外情况是您的 Python 发行版没有 tkinter 且未安装其他 GUI 工具包。这在某些 Linux 发行版中会发生，您需要安装名为 python-tk（或类似名称）的 Linux 包。

但是，如果您想编写图形用户界面、Web 应用服务器（嵌入到 Web 应用服务器 (Flask)），或者需要更好地了解正在发生的事情，请继续阅读。为了使图形用户界面的定制变得更加容易，Matplotlib 将渲染器（实际执行绘图的东西）的概念与画布（绘图所在的区域）的概念分开了。用于用户界面的典型渲染器是 Agg，它使用 Anti-Grain Geometry C++ 库来制作图形的栅格（像素）图像；它被 QtAgg, GTK4Agg, GTK3Agg, wxAgg, TkAgg 和 macosx 后端使用。另一个渲染器基于 Cairo 库，由 QtCairo 等使用。

对于渲染引擎，用户还可以区分 矢量 或 栅格 渲染器。矢量图形语言发布绘图命令，如“从这一点画一条线到这一点”，因此它们是与比例无关的。栅格后端生成线的像素表示，其精度取决于 DPI 设置。

静态后端

以下是 Matplotlib 渲染器的总结（每个都有一个同名的后端；这些是非交互式后端，能够写入文件）

渲染器	文件类型	描述
AGG	png	栅格 图形 -- 使用 Anti-Grain Geometry 引擎生成的高质量图像。
PDF	pdf	矢量 图形 -- 可移植文档格式 输出。
PS	ps, eps	矢量 图形 -- PostScript 输出。
SVG	svg	矢量 图形 -- 可缩放矢量图形 输出。
PGF	pgf, pdf	矢量 图形 -- 使用 pgf 包。
Cairo	png, ps, pdf, svg	栅格 或 矢量 图形 -- 使用 Cairo 库（需要 pycairo 或 cairocffi）。

要使用非交互式后端保存绘图，请使用 matplotlib.pyplot.savefig('filename') 方法。

交互式后端

这些是支持的用户界面和渲染器组合；这些是交互式后端，能够显示在屏幕上，并使用上表中的相应渲染器写入文件

后端	描述
QtAgg	Qt 画布上的 Agg 渲染（需要 PyQt 或 Qt for Python，即 PySide）。此后端可在 IPython 中通过 %matplotlib qt 激活。Qt 绑定可以通过 QT_API 环境变量进行选择；更多详情请参见 Qt 绑定。
ipympl	嵌入到 Jupyter 小部件中的 Agg 渲染（需要 ipympl）。此后端可以在 Jupyter 笔记本中通过 %matplotlib ipympl 或 %matplotlib widget 启用。适用于 Jupyter lab 和 notebook>=7。
GTK3Agg	GTK 3.x 画布上的 Agg 渲染（需要 PyGObject 和 pycairo）。此后端可在 IPython 中通过 %matplotlib gtk3 激活。
GTK4Agg	GTK 4.x 画布上的 Agg 渲染（需要 PyGObject 和 pycairo）。此后端可在 IPython 中通过 %matplotlib gtk4 激活。
macosx	macOS Cocoa 画布上的 Agg 渲染。此后端可在 IPython 中通过 %matplotlib osx 激活。
TkAgg	Tk 画布上的 Agg 渲染（需要 TkInter）。此后端可在 IPython 中通过 %matplotlib tk 激活。
nbAgg	在 Jupyter 经典笔记本中嵌入交互式图形。此后端可以在 Jupyter 笔记本中通过 %matplotlib notebook 或 %matplotlib nbagg 启用。适用于 Jupyter notebook<7 和 nbclassic。
WebAgg	调用 show() 时将启动一个带有交互式图形的 tornado 服务器。
GTK3Cairo	GTK 3.x 画布上的 Cairo 渲染（需要 PyGObject 和 pycairo）。
GTK4Cairo	GTK 4.x 画布上的 Cairo 渲染（需要 PyGObject 和 pycairo）。
wxAgg	wxWidgets 画布上的 Agg 渲染（需要 wxPython 4）。此后端可在 IPython 中通过 %matplotlib wx 激活。

注意

内置后端的名称不区分大小写；例如，'QtAgg' 和 'qtagg' 是等效的。

ipympl

ipympl 后端位于一个单独的包中，如果您想使用它，必须显式安装，例如

pip install ipympl

或

conda install ipympl -c conda-forge

有关详细信息，请参阅 安装 ipympl。

使用非内置后端

更一般地说，可以使用上述任何方法选择任何可导入的后端。如果 name.of.the.backend 是包含后端的模块，则使用 module://name.of.the.backend 作为后端名称，例如 matplotlib.use('module://name.of.the.backend')。

后端实现者的相关信息可在 编写后端 -- pyplot 接口 中找到。

后端 API 版本

Matplotlib 致力于维护后端的向后兼容性。尽管如此，我们希望能够发展后端 API 以支持新功能。定义后端 API 版本有助于传达特定版本的 Matplotlib 支持哪些 API。

存在以下后端 API 版本

API 版本	自何时起支持	描述
1.0	Matplotlib 3.10	这是系统化定义后端版本的起点。大部分 API 在很久以前就能工作，但追溯发现所有先前的变更没有任何好处。
1.1	Matplotlib 3.11	RendererBase.draw_path_collection 增加了一个新的可选参数 hatchcolor。该参数的存在通过内省进行推断，因此 matplotlib 3.11+ 仍将与实现 API 版本 1.0 的后端一起工作。

目前没有计划取消对旧 API 版本的支持。

调试图形窗口未显示问题

有时事情并没有按预期进行，通常是在安装过程中。

如果您使用的是笔记本或集成开发环境（参见 笔记本和 IDE），请参阅其文档以调试其环境中无法工作的图形。

如果您使用的是 Matplotlib 的图形后端之一（参见 独立脚本和交互式使用），请确保您知道正在使用哪一个

import matplotlib

print(matplotlib.get_backend())

尝试简单的绘图以查看 GUI 是否打开

import matplotlib
import matplotlib.pyplot as plt

print(matplotlib.get_backend())
plt.plot((1, 4, 6))
plt.show()

如果它没有打开，您可能遇到了安装问题。此时一个很好的步骤是确保正确安装了 GUI 工具包，将 Matplotlib 从测试中排除。几乎所有的 GUI 工具包都有一个小型的测试程序，可以运行来测试基本功能。如果此测试失败，请尝试重新安装。

QtAgg, QtCairo, Qt5Agg 和 Qt5Cairo

测试 PyQt6（如果您安装的是 PyQt5, PySide2 或 PySide6 而不是 PyQt6，只需相应地更改导入）

python3 -c "from PyQt6.QtWidgets import *; app = QApplication([]); win = QMainWindow(); win.show(); app.exec()"

TkAgg 和 TkCairo

测试 tkinter

python3 -c "from tkinter import Tk; Tk().mainloop()"

GTK3Agg, GTK4Agg, GTK3Cairo, GTK4Cairo

测试 Gtk

python3 -c "from gi.repository import Gtk; win = Gtk.Window(); win.connect('destroy', Gtk.main_quit); win.show(); Gtk.main()"

wxAgg 和 wxCairo

测试 wx

python3 -c "import wx; app = wx.App(); frame = wx.Frame(None); frame.Show(); app.MainLoop()"

如果测试对您所需的后端有效，但您仍然无法让 Matplotlib 显示图形，请联系我们（参见 获取帮助）。