.. _backends:

Backends

.. _what-is-a-backend:

What is a backend?

A lot of documentation on the website and in the mailing lists refers

to the "backend" and many new users are confused by this term.

Matplotlib targets many different use cases and output formats. Some

people use Matplotlib interactively from the Python shell and have

plotting windows pop up when they type commands. Some people run

`Jupyter <https://jupyter.org>`_ notebooks and draw inline plots for

quick data analysis. Others embed Matplotlib into graphical user

interfaces like PyQt or PyGObject to build rich applications. Some

people use Matplotlib in batch scripts to generate postscript images

from numerical simulations, and still others run web application

servers to dynamically serve up graphs.

To support all of these use cases, Matplotlib can target different

outputs, 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 in

PyQt/PySide, PyGObject, Tkinter, wxPython, or macOS/Cocoa); also referred to

as "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:

- The :rc:`backend` parameter in your :file:`matplotlibrc` file

- The :envvar:`MPLBACKEND` environment variable

- The function :func:`matplotlib.use`

Below is a more detailed description.

If there is more than one configuration present, the last one from the

list takes precedence; e.g. calling :func:`matplotlib.use()` will override

the setting in your :file:`matplotlibrc`.

Without a backend explicitly set, Matplotlib automatically detects a usable

backend based on what is available on your system and on whether a GUI event

loop is already running. The first usable backend in the following list is

selected: MacOSX, QtAgg, GTK4Agg, Gtk3Agg, TkAgg, WxAgg, Agg. The last, Agg,

is a non-interactive backend that can only write to files. It is used on

Linux, if Matplotlib cannot connect to either an X display or a Wayland

display.

Here is a detailed description of the configuration methods:

#. Setting :rc:`backend` in your :file:`matplotlibrc` file::

#. Setting the :envvar:`MPLBACKEND` environment variable:

You can set the environment variable either for your current shell or for

a single script.

On Unix::

On Windows, only the former is possible::

Setting this environment variable will override the ``backend`` parameter

in *any* :file:`matplotlibrc`, even if there is a :file:`matplotlibrc` in

your current working directory. Therefore, setting :envvar:`MPLBACKEND`

globally, e.g. in your :file:`.bashrc` or :file:`.profile`, is discouraged

as it might lead to counter-intuitive behavior.

#. If your script depends on a specific backend you can use the function

:func:`matplotlib.use`::

This should be done before any figure is created, otherwise Matplotlib may

fail to switch the backend and raise an ImportError.

Using `~matplotlib.use` will require changes in your code if users want to

use a different backend. Therefore, you should avoid explicitly calling

`~matplotlib.use` unless absolutely necessary.

.. _the-builtin-backends:

The builtin backends

By default, Matplotlib should automatically select a default backend which

allows both interactive work and plotting from scripts, with output to the

screen and/or to a file, so at least initially, you will not need to worry

about the backend. The most common exception is if your Python distribution

comes without :mod:`tkinter` and you have no other GUI toolkit installed.

This happens on certain Linux distributions, where you need to install a

Linux package named ``python-tk`` (or similar).

If, however, you want to write graphical user interfaces, or a web

application server

(:doc:`/gallery/user_interfaces/web_application_server_sgskip`), or need a

better understanding of what is going on, read on. To make things easily

more customizable for graphical user interfaces, Matplotlib separates

the concept of the renderer (the thing that actually does the drawing)

from the canvas (the place where the drawing goes). The canonical

renderer for user interfaces is ``Agg`` which uses the `Anti-Grain

Geometry`_ C++ library to make a raster (pixel) image of the figure; it

is used by the ``QtAgg``, ``GTK4Agg``, ``GTK3Agg``, ``wxAgg``, ``TkAgg``, and

``macosx`` backends. An alternative renderer is based on the Cairo library,

used by ``QtCairo``, etc.

For the rendering engines, users can also distinguish between `vector

<https://en.wikipedia.org/wiki/Vector_graphics>`_ or `raster

<https://en.wikipedia.org/wiki/Raster_graphics>`_ renderers. Vector

graphics languages issue drawing commands like "draw a line from this

point to this point" and hence are scale free. Raster backends

generate a pixel representation of the line whose accuracy depends on a

DPI setting.

Here is a summary of the Matplotlib renderers (there is an eponymous

backend for each; these are *non-interactive backends*, capable of

writing to a file):

Renderer Filetypes Description

AGG png raster_ graphics -- high quality images using the

`Anti-Grain Geometry`_ engine

PDF pdf vector_ graphics -- `Portable Document Format`_

PS ps, eps vector_ graphics -- Postscript_ output

SVG svg vector_ graphics -- `Scalable Vector Graphics`_

PGF pgf, pdf vector_ graphics -- using the pgf_ package

Cairo png, ps, raster_ or vector_ graphics -- using the Cairo_ library

pdf, svg

To save plots using the non-interactive backends, use the

``matplotlib.pyplot.savefig('filename')`` method.

These are the user interfaces and renderer combinations supported;

these are *interactive backends*, capable of displaying to the screen

and using appropriate renderers from the table above to write to

a file:

Backend Description

QtAgg Agg rendering in a Qt_ canvas (requires PyQt_ or `Qt for Python`_,

a.k.a. PySide). This backend can be activated in IPython with

``%matplotlib qt``.

ipympl Agg rendering embedded in a Jupyter widget. (requires ipympl).

This backend can be enabled in a Jupyter notebook with

``%matplotlib ipympl``.

GTK3Agg Agg rendering to a GTK_ 3.x canvas (requires PyGObject_,

and pycairo_ or cairocffi_). This backend can be activated in

IPython with ``%matplotlib gtk3``.

GTK4Agg Agg rendering to a GTK_ 4.x canvas (requires PyGObject_,

and pycairo_ or cairocffi_). This backend can be activated in

IPython with ``%matplotlib gtk4``.

macosx Agg rendering into a Cocoa canvas in OSX. This backend can be

activated in IPython with ``%matplotlib osx``.

TkAgg Agg rendering to a Tk_ canvas (requires TkInter_). This

backend can be activated in IPython with ``%matplotlib tk``.

nbAgg Embed an interactive figure in a Jupyter classic notebook. This

backend can be enabled in Jupyter notebooks via

``%matplotlib notebook``.

WebAgg On ``show()`` will start a tornado server with an interactive

figure.

GTK3Cairo Cairo rendering to a GTK_ 3.x canvas (requires PyGObject_,

and pycairo_ or cairocffi_).

GTK4Cairo Cairo rendering to a GTK_ 4.x canvas (requires PyGObject_,

and pycairo_ or cairocffi_).

wxAgg Agg rendering to a wxWidgets_ canvas (requires wxPython_ 4).

This backend can be activated in IPython with ``%matplotlib wx``.

.. note::

The names of builtin backends case-insensitive; e.g., 'QtAgg' and

'qtagg' are equivalent.

.. _`Anti-Grain Geometry`: http://agg.sourceforge.net/antigrain.com/

.. _`Portable Document Format`: https://en.wikipedia.org/wiki/Portable_Document_Format

.. _Postscript: https://en.wikipedia.org/wiki/PostScript

.. _`Scalable Vector Graphics`: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics

.. _pgf: https://ctan.org/pkg/pgf

.. _Cairo: https://www.cairographics.org

.. _PyGObject: https://wiki.gnome.org/action/show/Projects/PyGObject

.. _pycairo: https://www.cairographics.org/pycairo/

.. _cairocffi: https://pythonhosted.org/cairocffi/

.. _wxPython: https://www.wxpython.org/

.. _TkInter: https://docs.python.org/3/library/tk.html

.. _PyQt: https://riverbankcomputing.com/software/pyqt/intro

.. _`Qt for Python`: https://doc.qt.io/qtforpython/

.. _Qt: https://qt.io/

.. _GTK: https://www.gtk.org/

.. _Tk: https://www.tcl.tk/

.. _wxWidgets: https://www.wxwidgets.org/

ipympl

The Jupyter widget ecosystem is moving too fast to support directly in

Matplotlib. To install ipympl:

.. code-block:: bash

or

.. code-block:: bash

See `jupyter-matplotlib <https://github.com/matplotlib/jupyter-matplotlib>`__

for more details.

.. _QT_API-usage:

How do I select PyQt5 or PySide2?

The :envvar:`QT_API` environment variable can be set to either ``pyqt5`` or

``pyside2`` to use ``PyQt5`` or ``PySide2``, respectively.

Since the default value for the bindings to be used is ``PyQt5``, Matplotlib

first tries to import it. If the import fails, it tries to import

``PySide2``.

Using non-builtin backends

More generally, any importable backend can be selected by using any of the

methods above. If ``name.of.the.backend`` is the module containing the

backend, use ``module://name.of.the.backend`` as the backend name, e.g.

``matplotlib.use('module://name.of.the.backend')``.

Further details are available in the :doc:`Installation Guide </users/installing>`.

If a plot does not show up please check :ref:`troubleshooting-faq`.

backends.rst

performance.rst