matplotlib · timhoffm · Oct 14, 2021 · Oct 11, 2021 · Oct 12, 2021 · Oct 14, 2021
diff --git a/doc/users/backends.rst b/doc/users/backends.rst
@@ -0,0 +1,250 @@
+.. _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::
+
+       backend : qtagg   # use pyqt with antigrain (agg) rendering
+
+   See also :doc:`/tutorials/introductory/customizing`.
+
+#. Setting the :envvar:`MPLBACKEND` environment variable:
+
+   You can set the environment variable either for your current shell or for
+   a single script.
+
+   On Unix::
+
+        > export MPLBACKEND=qtagg
+        > python simple_plot.py
+
+        > MPLBACKEND=qtagg python simple_plot.py
+
+   On Windows, only the former is possible::
+
+        > set MPLBACKEND=qtagg
+        > python simple_plot.py
+
+   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`::
+
+      import matplotlib
+      matplotlib.use('qtagg')
+
+   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
+
+   pip install ipympl
+   jupyter nbextension enable --py --sys-prefix ipympl
+
+or
+
+.. code-block:: bash
+
+   conda install ipympl -c conda-forge
+
+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')``.
diff --git a/doc/users/getting_started.rst b/doc/users/getting_started.rst
@@ -24,6 +24,12 @@ Installation
 
 Further details are available in the :doc:`Installation Guide </users/installing>`.
 
+Choosing a backend
+------------------
+
+Matplotlib needs a "backend" to render your figure, either in its own GUI window,
+as part of a notebook, or saved as an image to disk.  If you need more information on 
+choosing a backend, see :ref:`backends`.
 
 Draw a first plot
 -----------------

diff --git a/doc/users/index.rst b/doc/users/index.rst
@@ -11,7 +11,11 @@ Usage guide
    ../tutorials/index.rst
    ../gallery/index.rst
    getting_started.rst
+   backends.rst
+   performance.rst
+   ../gallery/usage.rst
    explain.rst
    ../faq/index.rst
    ../api/index.rst
    ../resources/index.rst
+