matplotlib.backends.backend_qtagg,matplotlib.backends.backend_qtcairo#

NOTE TheseBackends are not (auto) documented here, to avoid addinga dependency to building the docs.

Qt Bindings#

There are currently 2 actively supported Qt versions, Qt5 and Qt6, and twosupported Python bindings per version --PyQt5 andPySide2 for Qt5 andPyQt6 andPySide6 for Qt6[1]. Matplotlib'sqtagg and qtcairo backends (matplotlib.backends.backend_qtagg andmatplotlib.backend.backend_qtcairo) support all these bindings, with commonparts factored out in thematplotlib.backends.backend_qt module.

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

  1. If a binding'sQtCore subpackage is already imported, that binding isselected (the order for the check isPyQt6,PySide6,PyQt5,PySide2).

  2. If theQT_API environment variable is set to one of "PyQt6","PySide6", "PyQt5", "PySide2" (case-insensitive), that binding is selected.(See also the documentation onEnvironment variables.)

  3. Otherwise, the first available backend in the orderPyQt6,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 andqt5agg/matplotlib.backends.backend_qt5agg). This scheme was dropped whensupport for Qt6 was added. For back-compatibility, qt5agg/backend_qt5aggand qt5cairo/backend_qt5cairo remain available; selecting one of thesebackends forces the use of a Qt5 binding. Their use is discouraged andbackend_qtagg orbackend_qtcairo should be preferred instead. However,these modules will not be deprecated until we drop support for Qt5.

While both PyQtand Qt for Python (aka PySide) closely mirror the underlying C++ API they arewrapping, they are not drop-in replacements for each other[2]. To accountfor this, Matplotlib has an internal API compatibility layer inmatplotlib.backends.qt_compat which covers our needs. Despite being a publicmodule, we do not consider this to be a stable user-facing API and it maychange without warning[3].

[1]

There is alsoPyQt4 andPySide for Qt4 but these are nolonger supported by Matplotlib and upstream support for Qt4 endedin 2015.

[2]

Despite the slight API differences, the more important distinctionbetween the PyQt and Qt for Python series of bindings is licensing.

[3]

If you are looking for a general purpose compatibility library pleaseseeqtpy.

On this page