What is a backend?#

Backends are used for displaying Matplotlib figures (seeIntroduction to Figures),on the screen, or for writing to files. A lot of documentation on the websiteand in the mailing lists refers to the "backend" and many new users areconfused by this term. Matplotlib targets many different use cases and outputformats. Some people use Matplotlib interactively from the Python shell andhave plotting windows pop up when they type commands. Some people runJupyter notebooks and draw inline plots for quick dataanalysis. Others embed Matplotlib into graphical user interfaces like PyQt orPyGObject to build rich applications. Some people use Matplotlib in batchscripts to generate postscript images from numerical simulations, and stillothers run web application servers to dynamically serve up graphs.

To support all of these use cases, Matplotlib can target differentoutputs, and each of these capabilities is called a backend; the"frontend" is the user facing code, i.e., the plotting code, whereas the"backend" does all the hard work behind-the-scenes to make the figure.There are two types of backends: user interface backends (for use inPyQt/PySide, PyGObject, Tkinter, wxPython, or macOS/Cocoa); also referred toas "interactive backends") and hardcopy backends to make image files(PNG, SVG, PDF, PS; also referred to as "non-interactive backends").

Selecting a backend#

There are three ways to configure your backend:

• ThercParams["backend"] parameter in yourmatplotlibrc file

• TheMPLBACKEND environment variable

• The functionmatplotlib.use()

Below is a more detailed description.

If there is more than one configuration present, the last one from thelist takes precedence; e.g. callingmatplotlib.use() will overridethe setting in yourmatplotlibrc.

Without a backend explicitly set, Matplotlib automatically detects a usablebackend based on what is available on your system and on whether a GUI eventloop is already running. The first usable backend in the following list isselected: MacOSX, QtAgg, GTK4Agg, Gtk3Agg, TkAgg, WxAgg, Agg. The last, Agg,is a non-interactive backend that can only write to files. It is used onLinux, if Matplotlib cannot connect to either an X display or a Waylanddisplay.

Here is a detailed description of the configuration methods:

1. SettingrcParams["backend"] in yourmatplotlibrc file:

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

   See alsoCustomizing Matplotlib with style sheets and rcParams.

2. Setting theMPLBACKEND environment variable:

   You can set the environment variable either for your current shell or fora single script.

   On Unix:

   >exportMPLBACKEND=qtagg>pythonsimple_plot.py>MPLBACKEND=qtaggpythonsimple_plot.py

   On Windows, only the former is possible:

   >setMPLBACKEND=qtagg>pythonsimple_plot.py

   Setting this environment variable will override thebackend parameterinanymatplotlibrc, even if there is amatplotlibrc inyour current working directory. Therefore, settingMPLBACKENDglobally, e.g. in your.bashrc or.profile, is discouragedas it might lead to counter-intuitive behavior.

3. If your script depends on a specific backend you can use the functionmatplotlib.use():

   importmatplotlibmatplotlib.use('qtagg')

   This should be done before any figure is created, otherwise Matplotlib mayfail to switch the backend and raise an ImportError.

   Usinguse will require changes in your code if users want touse a different backend. Therefore, you should avoid explicitly callinguse unless absolutely necessary.

The builtin backends#

By default, Matplotlib should automatically select a default backend whichallows both interactive work and plotting from scripts, with output to thescreen and/or to a file, so at least initially, you will not need to worryabout the backend. The most common exception is if your Python distributioncomes withouttkinter and you have no other GUI toolkit installed.This happens with certain Linux distributions, where you need to install aLinux package namedpython-tk (or similar).

If, however, you want to write graphical user interfaces, or a webapplication server(Embed in a web application server (Flask)), or need abetter understanding of what is going on, read on. To make things easilymore customizable for graphical user interfaces, Matplotlib separatesthe concept of the renderer (the thing that actually does the drawing)from the canvas (the place where the drawing goes). The canonicalrenderer for user interfaces isAgg which uses theAnti-GrainGeometry C++ library to make a raster (pixel) image of the figure; itis used by theQtAgg,GTK4Agg,GTK3Agg,wxAgg,TkAgg, andmacosx backends. An alternative renderer is based on the Cairo library,used byQtCairo, etc.

For the rendering engines, users can also distinguish betweenvector orraster renderers. Vectorgraphics languages issue drawing commands like "draw a line from thispoint to this point" and hence are scale free. Raster backendsgenerate a pixel representation of the line whose accuracy depends on aDPI setting.

pipinstallipympl

condainstallipympl-cconda-forge

Using non-builtin backends#

More generally, any importable backend can be selected by using any of themethods above. Ifname.of.the.backend is the module containing thebackend, usemodule://name.of.the.backend as the backend name, e.g.matplotlib.use('module://name.of.the.backend').

Information for backend implementers is available atWriting a backend -- the pyplot interface.

Debugging the figure windows not showing#

Sometimes things do not work as expected, usually during an install.

If you are using a Notebook or integrated development environment (seeNotebooks and IDEs),please consult their documentation for debugging figures not working in theirenvironments.

If you are using one of Matplotlib's graphics backends (seeStandalone scripts and interactive use), make sure you know whichone is being used:

importmatplotlibprint(matplotlib.get_backend())

Try a simple plot to see if the GUI opens:

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

If it does not, you perhaps have an installation problem. A good step at thispoint is to ensure that your GUI toolkit is installed properly, takingMatplotlib out of the testing. Almost all GUI toolkits have a small testprogram that can be run to test basic functionality. If this test fails, try re-installing.

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

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

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

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