后端

什么是后端？

后端用于显示 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，是一个非交互式后端，只能写入文件。如果 Matplotlib 无法连接到 X 显示或 Wayland 显示，则在 Linux 上使用它。

以下是配置方法的详细描述：

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

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

   另请参阅 自定义。

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	raster_graphics -- 使用 Anti-Grain Geometry 引擎的高质量图像。
PDF	pdf	矢量图形 -- 便携文档格式 输出。
PS	ps, eps	vector 图形 -- PostScript 输出。
SVG	svg	vector 图形 -- 可缩放矢量图形 输出。
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_API 环境变量选择 Qt 绑定；更多详情请参阅 Qt 绑定。
ipympl	在 Jupyter 小部件中嵌入 Agg 渲染（需要 ipympl）。此后端可以在 Jupyter 笔记本中通过 %matplotlib ipympl 或 %matplotlib widget 启用。适用于 Jupyter lab 和 notebook>=7。
GTK3Agg	Agg 渲染到 GTK 3.x 画布（需要 PyGObject 和 pycairo）。此后端可以在 IPython 中使用 %matplotlib gtk3 激活。
GTK4Agg	Agg 渲染到 GTK 4.x 画布（需要 PyGObject 和 pycairo）。此后端可以在 IPython 中使用 %matplotlib gtk4 激活。
macosx	在 macOS 中将 Agg 渲染到 Cocoa 画布。这个后端可以在 IPython 中通过 %matplotlib osx 激活。
TkAgg	将Agg渲染到Tk_画布（需要TkInter）。此后端可以在IPython中通过``%matplotlib tk``激活。
nbAgg	在 Jupyter 经典笔记本中嵌入一个交互式图形。可以通过 %matplotlib notebook 或 %matplotlib nbagg 在 Jupyter 笔记本中启用此后端。适用于 Jupyter notebook<7 和 nbclassic。
WebAgg	在 show() 上将启动一个带有交互式图形的 tornado 服务器。
GTK3Cairo	Cairo 渲染到 GTK 3.x 画布（需要 PyGObject 和 pycairo）。
GTK4Cairo	Cairo 渲染到 GTK 4.x 画布（需要 PyGObject 和 pycairo）
wxAgg	将Agg渲染到wxWidgets_画布（需要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 接口 找到。

调试图形窗口不显示的问题

有时事情并不如预期那样工作，通常是在安装过程中。

如果你在使用笔记本或集成开发环境（参见 笔记本和集成开发环境），请查阅它们的文档以解决在它们的环境中调试图形不工作的问题。

如果你使用的是 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

测试 PyQt5。

如果你安装的是 PySide 或 PyQt6 而不是 PyQt5，只需相应地更改导入：

python -c "from PyQt5.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：

import wx

app = wx.App(False)  # Create a new app, don't redirect stdout/stderr to a window.
frame = wx.Frame(None, wx.ID_ANY, "Hello World") # A Frame is a top-level window.
frame.Show(True)     # Show the frame.
app.MainLoop()

如果你的测试适用于你期望的后端，但你仍然无法让 Matplotlib 显示图形，那么请联系我们（参见 获取帮助）。