backend_qtagg, backend_qtcairo#
NOTE These backends are not (auto) documented here, to avoid adding a dependency to building the docs.
Qt Bindings#
There are currently 2 actively supported Qt versions, Qt5 and Qt6, and two
supported Python bindings per version -- PyQt5 and PySide2 for Qt5 and PyQt6 and PySide6 for Qt6 [1]. 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 [2]. 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 [3].
Previously Matplotlib's Qt backends had the Qt version number in the name, both
in the module and the rcParams["backend"] value
(e.g. matplotlib.backends.backend_qt4agg and
matplotlib.backends.backend_qt5agg). However as part of adding support for
Qt6 we were able to support both Qt5 and Qt6 with a single implementation with
all of the Qt version and binding support handled in
qt_compat. A majority of the renderer agnostic Qt code
is now in matplotlib.backends.backend_qt with specialization for AGG in
backend_qtagg and cairo in backend_qtcairo.
The binding is selected at run time based on what bindings are already imported
(by checking for the QtCore sub-package), then by the QT_API
environment variable, and finally by the rcParams["backend"]. In all cases when we
need to search, the order is PyQt6, PySide6, PyQt5, PySide2.
See How do I select the Qt implementation? for usage instructions.
The backend_qt5, backend_qt5agg, and backend_qt5cairo are provided
and force the use of a Qt5 binding for backwards compatibility. Their use is
discouraged (but not deprecated) and backend_qt, backend_qtagg, or
backend_qtcairo should be preferred instead. However, these modules will
not be deprecated until we drop support for Qt5.