@header@

matplotlib backends

The matplotlib core graphics routines interact with an abstract renderer and graphics context to allow device independent ouput. Currently, output to pygtk, wxPython, Tkinter, postscript, gdmodule, libart/paint, svg and agg (antigrain geometry) are supported. With not too much effort, you can port matplotlib to your favorite display; high on my list of priorities are PDF and PIL. If you are interested in porting to one of these platforms, please contact me!

For a summary of the comparative strengths and features of the various backends, see which backend should I use?. This page describes how to install and use each backend.

You can choose your default backend in the matplotlibrc file. The default can be overridden from the command line prompt. This allows most if not all matplotlib scripts can generate output to any of the backends without any alterations. Following the lead of the matlab print command, the backend can be chosen from the command line with the -d flag, as in 

# the GUI backends
> python subplot_demo.py -dGTK     # GTK GUI with gdk drawing
> python subplot_demo.py -dGTKAgg  # GTK GUI with antigrain rendering
> python subplot_demo.py -dTkAgg   # Tkinter GUI with antigrain rendering
> python subplot_demo.py -dWX      # WX backend
> python subplot_demo.py -dWXAgg   # WX GUI with antigrain rendering

# The image backends, no window pops up; you must call savefig
> python subplot_demo.py -dAgg     # antigrain geometry backend image
> python subplot_demo.py -dGD      # GD backend
> python subplot_demo.py -dPaint   # Paint backend
> python subplot_demo.py -dPS      # postscript backend
> python subplot_demo.py -dSVG      # SVG backend
For backends that do not have a GUI, no output will be produced unless a call to savefig is made. The recommended way to use the savefig function is to not give an extension. The backends will choose the proper extension. This allows you to write a single script and select the output format from the command line. So a script containing savefig('somefile') will create somefile.ps if called with -dPS and somefile.png if called with -dGD, and so on.

Alternatively, you can select the backend renderer in your script by calling the matplotlib use function. At the top of your script (before you import matplotlib.matlab, just do, for example 

import matplotlib
matplotlib.use('PS')
The current backend strings that are supported are GD, Agg, GTK, GTKAgg, PS TkAgg WX WXAgg Paint and Template. The default is GTK. Template is a do nothing backend that serves as a template for backend writers (volunteers welcome!).

To get the most of your backend of choice, you may need to set an environment variable controlling the fonts; see fonts for more information.

Backend requirements

Each of the backends have a different set of requirements, listed below. All require the Numeric or numarray modules. Note, matplotlib can also be made to work with numarray with minor changes; see the FAQ.

Specific information for installing the other backends can be found on this page below or by clicking

GTK

 This is the default backend and the first one supported by matplotlib; it requires

Redhat Users

GTK2 became the default with the Redhat Linux 8 series. If your distro is older than that, you'll need to upgrade your desktop, upgrade your gtk libs, or upgrade your distro.

I am not sure what the status of GTK2 versus version number is with the other distros, but I would be happy for answers, so if you know, please email me @myemail@. If you put matplotlib in the subject, the email will be sure to get past my spam filters.

Windows GTK Quickstart

These install instructions will provide the GTK and GTKGTKAgg backends on windows. If you encounter troubles, please see the FAQ

WX

 Requires wxpython. Windows users may want to consider the enthought edition of python, which comes with wxpython and Numeric built in, so matplotlib will work right out of the box. matplotlib under WX has been tested on linux, win32 and OSX.

WXAgg

Requires wxpython. Windows users may want to consider the enthought edition of python, which comes with wxpython and Numeric built in, so matplotlib will work right out of the box. matplotlib under WXAgg has been tested on linux, win32 and OSX.

Agg output

The antigrain geometry library is a platform independent library that provides efficient antialiased rendering with a vector model. Because it doesn't depend on a GUI framework, it is suitable for use in web application servers generating images for html inclusion or for generating images in batch scripts. Agg can also be embedded in GUI applications, as in the GTKAgg and TkAgg backends -- see setup.py

The windows installer comes with Agg prebuilt. For other platforms, to compile Agg from src, set the BUILD_AGG flag in setup.py.

GTKAgg: GTK GUI with antigrain rendering

GTK has a very nice and portable widget set. The gdk drawing commands, while fast, are somewhat limited. To overcome this limitation, GTKAgg marries the widgets of GTK with the rendering of antigrain. You need the agg and gtk prerequisites. On windows, GTKAgg is builtin, so you only need to install pygtk and the GTK runtime, as described in gtk.

Tkinter GUI backend

 Todd Miller has written a backend for Tkinter that uses the agg backend for rendering. To use Tkagg, you need to set the BUILD_TKAGG flag in setup.py. The windows installer comes with TkAgg prebuilt. See agg backend for more information on agg rendering and fonts. NOTE: on at least some versions of redhat linux, you must install a separate tkinter package, apparently tkinter-2.2.2-26.i386.rpm on Red Hat 9 linux. Alternately, Python built from source code (Python.org tarball, not the redhat SRPM) includes Tkinter support by default on Red Hat Linux. In general, TkAgg is known to work with TkAgg is known not work with: Both of the latter shells fail with a RuntimeError "abnormal program termination". I checked on www.python.org about Tkinter and Pythonwin and they're known not to work together so that explains TkAgg on Pythonwin. tkinter trouble.

I also looked into SciTE a little and discovered that it is related to Scintilla which in turn was derived from Pythonwin. scintilla This indicates to me that the same problem with Tkinter may be affecting both (SciTE and Pythonwin)... but I am out on a limb.

GD output

The recommended image backend is Agg. If you are sure you want to use GD, read on.

The GD module can be used to create images with no X11 server, and is particularly useful for web application developers who want dynamic graphing capabilities. There are a number of prerequisites but they are easy to install (Windows users should skip ahead to the win32 section).

The GD backend depends on Numeric/numarray, gdmodule, and gd. To ease installation, the latter two packages now ship with matplotlib. Below are instructions for building gdmodule.