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.