@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 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 SVG, 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

# 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
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, PS TkAgg WX 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 module. 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 Users

Windows users should consult Cedric's pygtk for win32 site for information about pygtk for win32. Basically, you need to install the GTK 2.2.4 Runtime and pygtk-2.0.0 both of which have friendly windows installers. After you install the runtime, you need to add the bin and lib subdirs of your install dir to your PATH. Cedric's website also provides pygtk-1.99.16 for python2.2 users which also works fine with matplotlib.

See the fonts for more information about getting the GTK backend setup for proper font rendering. If you are experiencing warnings about Times font not being found, see this FAQ entry

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.

Agg output

The antigrain geometry library is a platform independent library that provides efficient antialiased rendering with a vector model. This is a sophisticated libary that we hope will provide the basis for more sophisticated drawing and image handling in future versions of matplotlib. Because is 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. To compile Agg from src, set the BUILD_AGG flag in setup.py. Like the other freetype image modules GD and Paint, Agg uses TTFQuery and fonttools for cross-platform font finding. These modules, too, are included in the windows installer, and will be build automatically by setting BUILD_AGG. See ttf fonts for information about setting your paths to find your *.ttf font files.

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. 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.

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.

GD output

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, gdmodule, gd, TTFQuery and fonttools. To ease installation, the latter two packages now ship with matplotlib. Set the flag BUILD_FONTTOOLS in setup.py to build both TTFQuery and fonttools with matplotlib. Below are instructions for building gdmoule.

Quick install guide for GD module: linux and friends

The latest snapshot of matplotlib requires a patch to gdmodule-0.52. 
    cd /var/tmp
    tar xvfz ~/src/gd-2.0.22.tar.gz
    cd gd-2.0.22/
    ./configure --prefix=/usr
    sudo make install

    cd /var/tmp
    tar xvfz ~/python/src/gdmodule-0.52.tar.gz
    cd gdmodule-0.52
    sudo python2.3 Setup.py install

Quick install guide for GD output: Windows

The windows installer for matplotlib comes with fonttools and TTFQuery built in. In addition to that package and Numeric, you'll need See the fonts for more information about getting the GD backend setup for proper font rendering. Note the formerly named GDFONTPATH is now called TTFPATH.

Postscript

The only requirement is Numeric

See the fonts page for more information about getting the postscript backend setup for proper font rendering; notably, you must make sure there are some '*.afm' files in your AFMPATH if you want to use fonts other than the ones that ship with matplotlib.

Paint

David Moore has written a paint backend for matplotlib. paint is a libart wrapper. In a nutshell, libart is a svg oriented, high performance, 2D graphics engine that supports lots of nifty features. The paint backend exposes some of them, and David has been extending it to expose more.

The paint backend requires Numeric, pypaint version 0.3. If you want cross-platform freetype font selection support, you'll also need TTFQuery and fonttools - these now ship with matplotlib in both the src and windows binary distributions. See freetype fonts for more information.

libart is highly portable, and the paint backend has been confirmed to work on win32 and linux. The pypaint web site has a src distribution and a windows installer.

@footer@