Writing a backend -- the pyplot interface#
This page assumes general understanding of the information in the
Backends page, and is instead intended as reference for
third-party backend implementers. It also only deals with the interaction
between backends and
pyplot, not with the rendering side, which is described
There are two APIs for defining backends: a new canvas-based API (introduced in Matplotlib 3.6), and an older function-based API. The new API is simpler to implement because many methods can be inherited from "parent backends". It is recommended if back-compatibility for Matplotlib < 3.6 is not a concern. However, the old API remains supported.
Fundamentally, a backend module needs to provide information to
pyplot.show()can show all figures and start the GUI event loop (if any).
To do so, the backend module must define a
FigureCanvasBase. In the canvas-based API, this is the only
strict requirement for backend modules. The function-based API additionally
requires many module-level functions to be defined.
Canvas-based API (Matplotlib >= 3.6)#
Creating a figure:
figure = Figure(); FigureCanvas.new_manager(figure, num)(
new_manageris a classmethod) to instantiate a canvas and a manager and set up the
figure.canvas.managerattributes. Figure unpickling uses the same approach, but replaces the newly instantiated
Figure()by the unpickled figure.
Interactive backends should customize the effect of
new_managerby setting the
FigureCanvas.manager_classattribute to the desired manager class, and additionally (if the canvas cannot be created before the manager, as in the case of the wx backends) by overriding the
FigureManager.create_with_canvasclassmethod. (Non-interactive backends can normally use a trivial
FigureManagerBaseand can therefore skip this step.)
After a new figure is registered with
pyplot.figure()or via unpickling), if in interactive mode,
pyplotwill call its canvas'
draw_idle()method, which can be overridden as desired.
FigureCanvas.manager_class.pyplot_show()(a classmethod), forwarding any arguments, to start the main event loop.
pyplot_show()checks whether there are any
pyplot(exiting early if not), calls
manager.show()on all such managers, and then, if called with
block=True(or with the default
block=Noneand out of IPython's pylab mode and not in interactive mode), calls
FigureCanvas.manager_class.start_main_loop()(a classmethod) to start the main event loop. Interactive backends should therefore override the
FigureCanvas.manager_class.start_main_loopclassmethod accordingly (or alternatively, they may also directly override
Creating a figure:
new_figure_manager(num, *args, **kwargs)(which also takes care of creating the new figure as
Figure(*args, **kwargs)); unpickling calls
Furthermore, in interactive mode, the first draw of the newly registered figure can be customized by providing a module-level
draw_if_interactive()function. (In the new canvas-based API, this function is not taken into account anymore.)
pyplot.show()calls a module-level
show()function, which is typically generated via the
ShowBaseclass and its