后端#

什么是后端？#

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

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

选择后端#

有三种方法可以配置您的后端

以下是更详细的描述。

如果存在多个配置，则列表中最后一个配置优先；例如，调用 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

    另请参阅 使用样式表和 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_API 环境变量选择 Qt 绑定；有关更多详细信息，请参阅 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 接口。

调试图形窗口不显示#

有时，事情不像预期的那样工作，通常在安装期间发生。

如果您正在使用笔记本或集成开发环境 (请参阅 笔记本和 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#

测试 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 显示图形，请联系我们（请参阅 获取帮助）。

在此页面