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.


There is also PyQt4 and PySide 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.