ContextQMD
Back to Matplotlib

``matplotlib.backends.backend_qtagg``, ``matplotlib.backends.backend_qtcairo``

doc/api/backend_qt_api.rst

3.10.93.5 KB
Original Source

matplotlib.backends.backend_qtagg, matplotlib.backends.backend_qtcairo

NOTE These :ref:backends are not (auto) documented here, to avoid adding a dependency to building the docs.

.. redirect-from:: /api/backend_qt4agg_api .. redirect-from:: /api/backend_qt4cairo_api .. redirect-from:: /api/backend_qt5agg_api .. redirect-from:: /api/backend_qt5cairo_api

.. module:: matplotlib.backends.qt_compat .. module:: matplotlib.backends.backend_qt .. module:: matplotlib.backends.backend_qtagg .. module:: matplotlib.backends.backend_qtcairo .. module:: matplotlib.backends.backend_qt5agg .. module:: matplotlib.backends.backend_qt5cairo

.. _QT_bindings:

Qt Bindings

There are currently 2 actively supported Qt versions, Qt5 and Qt6, and two supported Python bindings per version -- PyQt5 <https://www.riverbankcomputing.com/static/Docs/PyQt5/>_ and PySide2 <https://doc.qt.io/qtforpython-5/contents.html>_ for Qt5 and PyQt6 <https://www.riverbankcomputing.com/static/Docs/PyQt6/>_ and PySide6 <https://doc.qt.io/qtforpython/contents.html>_ for Qt6 [#]_. Matplotlib's qtagg and qtcairo backends (matplotlib.backends.backend_qtagg and matplotlib.backend.backend_qtcairo) support all these bindings, with common parts factored out in the matplotlib.backends.backend_qt module.

At runtime, these backends select the actual binding used as follows:

  1. If a binding's QtCore subpackage is already imported, that binding is selected (the order for the check is PyQt6, PySide6, PyQt5, PySide2).
  2. If the :envvar:QT_API environment variable is set to one of "PyQt6", "PySide6", "PyQt5", "PySide2" (case-insensitive), that binding is selected. (See also the documentation on :ref:environment-variables.)
  3. Otherwise, the first available backend in the order PyQt6, PySide6, PyQt5, PySide2 is selected.

In the past, Matplotlib used to have separate backends for each version of Qt (e.g. qt4agg/matplotlib.backends.backend_qt4agg and qt5agg/matplotlib.backends.backend_qt5agg). This scheme was dropped when support for Qt6 was added. For back-compatibility, qt5agg/backend_qt5agg and qt5cairo/backend_qt5cairo remain available; selecting one of these backends forces the use of a Qt5 binding. Their use is discouraged and backend_qtagg or backend_qtcairo should be preferred instead. However, these modules will not be deprecated until we drop support for Qt5.

While both PyQt and Qt for Python (aka PySide) closely mirror the underlying C++ API they are wrapping, they are not drop-in replacements for each other [#]. To account for this, Matplotlib has an internal API compatibility layer in matplotlib.backends.qt_compat which covers our needs. Despite being a public module, we do not consider this to be a stable user-facing API and it may change without warning [#].

.. [#] There is also PyQt4 <https://www.riverbankcomputing.com/static/Docs/PyQt4/>_ and PySide <https://srinikom.github.io/pyside-docs/>_ for Qt4 but these are no longer supported by Matplotlib and upstream support for Qt4 ended in 2015. .. [#] Despite the slight API differences, the more important distinction between the PyQt and Qt for Python series of bindings is licensing. .. [#] If you are looking for a general purpose compatibility library please see qtpy <https://github.com/spyder-ide/qtpy>_.