Installation

How do I report a compilation problem?

See How do I report a problem?.

matplotlib compiled fine, but I can’t get anything to plot

The first thing to try is a clean install and see if that helps. If not, the best way to test your install is by running a script, rather than working interactively from a python shell or an integrated development environment such as IDLE which add additional complexities. Open up a UNIX shell or a DOS command prompt and cd into a directory containing a minimal example in a file. Something like simple_plot.py, or for example:

from pylab import *
plot([1,2,3])
show()

and run it with:

python simple_plot.py --verbose-helpful

This will give you additional information about which backends matplotlib is loading, version information, and more. At this point you might want to make sure you understand matplotlib’s configuration process, governed by the matplotlibrc configuration file which contains instructions within and the concept of the matplotlib backend.

If you are still having trouble, see How do I report a problem?.

How do I cleanly rebuild and reinstall everything?

The steps depend on your platform and installation method.

Easy Install

  1. Delete the caches from your .matplotlib configuration directory.

  2. Run:

    easy_install -m PackageName
  3. Delete any .egg files or directories from your installation directory.

Windows installer

  1. Delete the caches from your .matplotlib configuration directory.
  2. Use Start ‣ Control Panel to start the Add and Remove Software utility.

Source install

Unfortunately:

python setup.py clean

does not properly clean the build directory, and does nothing to the install directory. To cleanly rebuild:

  1. Delete the caches from your .matplotlib configuration directory.
  2. Delete the build directory in the source tree
  3. Delete any matplotlib directories or eggs from your installation directory <locating-matplotlib-install>

Backends

What is a backend?

A lot of documentation on the website and in the mailing lists refers to the “backend” and many new users are confused by this term. matplotlib targets many different use cases and output formats. Some people use matplotlib interactively from the python shell and have plotting windows pop up when they type commands. Some people embed matplotlib into graphical user interfaces like wxpython or pygtk to build rich applications. Others use matplotlib in batch scripts to generate postscript images from some numerical simulations, and still others in web application servers to dynamically serve up graphs.

To support all of these use cases, matplotlib can target different outputs, and each of these capabililities is called a backend (the “frontend” is the user facing code, ie the plotting code, whereas the “backend” does all the dirty work behind the scenes to make the figure. There are two types of backends: user interface backends (for use in pygtk, wxpython, tkinter, qt or fltk) and hardcopy backends to make image files (PNG, SVG, PDF, PS).

There are a two primary ways to configure your backend. One is to set the backend parameter in you matplotlibrc file (see Customizing matplotlib):

backend : WXAgg   # use wxpython with antigrain (agg) rendering

The other is to use the matplotlib use() directive:

import matplotlib
matplotlib.use('PS')   # generate postscript output by default

If you use the use directive, this must be done before importing matplotlib.pyplot or matplotlib.pylab.

If you are unsure what to do, and just want to get cranking, just set your backend to TkAgg. This will do the right thing for 95% of the users. It gives you the option of running your scripts in batch or working interactively from the python shell, with the least amount of hassles, and is smart enough to do the right thing when you ask for postscript, or pdf, or other image formats.

If however, you want to write graphical user interfaces, or a web application server (How do I use matplotlib in a web application server?), or need a better understanding of what is going on, read on. To make things a little more customizable for graphical user interfaces, matplotlib separates the concept of the renderer (the thing that actually does the drawing) from the canvas (the place where the drawing goes). The canonical renderer for user interfaces is Agg which uses the antigrain C++ library to make a raster (pixel) image of the figure. All of the user interfaces can be used with agg rendering, eg WXAgg, GTKAgg, QTAgg, TkAgg. In addition, some of the user interfaces support other rendering engines. For example, with GTK, you can also select GDK rendering (backend GTK) or Cairo rendering (backend GTKCairo).

For the rendering engines, one can also distinguish between vector or raster renderers. Vector graphics languages issue drawing commands like “draw a line from this point to this point” and hence are scale free, and raster backends generate a pixel represenation of the line whose accuracy depends on a DPI setting.

Here is a summary of the matplotlib renderers (there is an eponymous backed for each):

Renderer Filetypes Description
AGG png raster graphics – high quality images using the Anti-Grain Geometry engine
PS ps eps vector graphicsPostscript output
PDF pdf vector graphicsPortable Document Format
SVG svg vector graphicsScalable Vector Graphics
Cairo png ps pdf svg ... vector graphicsCairo graphics
GDK png jpg tiff ... raster graphics – the Gimp Drawing Kit

And here are the user interfaces and renderer combinations supported:

Backend Description
GTKAgg Agg rendering to a GTK canvas (requires PyGTK)
GTK GDK rendering to a GTK canvas (not recommended) (requires PyGTK)
GTKCairo Cairo rendering to a GTK Canvas (requires PyGTK)
WXAgg Agg rendering to to a wxWidgets canvas (requires wxPython)
WX Native wxWidgets drawing to a wxWidgets Canvas (not recommended) (requires wxPython)
TkAgg Agg rendering to a Tk canvas (requires TkInter)
QtAgg Agg rendering to a Qt canvas (requires PyQt)
Qt4Agg Agg rendering to a Qt4 canvas (requires PyQt4)
FLTKAgg Agg rendering to a FLTK canvas (requires pyFLTK)

How do I compile matplotlib with PyGTK-2.4?

There is a bug in PyGTK-2.4. You need to edit pygobject.h to add the G_BEGIN_DECLS and G_END_DECLS macros, and rename typename parameter to typename_:

-                       const char *typename,
+                       const char *typename_,

OS-X questions

How can I easy_install my egg?

I downloaded the egg for 0.98 from the matplotlib webpages, and I am trying to easy_install it, but I am getting an error:

> easy_install ./matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg
Processing matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg
removing '/Library/Python/2.5/site-packages/matplotlib-0.98.0-py2.5-
...snip...
Reading http://matplotlib.sourceforge.net
Reading http://cheeseshop.python.org/pypi/matplotlib/0.91.3
No local packages or download links found for matplotlib==0.98.0
error: Could not find suitable distribution for
Requirement.parse('matplotlib==0.98.0')

If you rename matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg to matplotlib-0.98.0-py2.5.egg, easy_install will install it from the disk. Many Mac OS X eggs with cruft at the end of the filename, which prevents their installation through easy_install. Renaming is all it takes to install them; still, it’s annoying.

Windows questions

Where can I get binary installers for windows?

If you have already installed python, you can use one of the matplotlib binary installers for windows – you can get these from the sourceforge download site. Choose the files that match your version of python (eg py2.5 if you installed Python 2.5) which have the exe extension. If you haven’t already installed python, you can get the official version from the python web site. There are also two packaged distributions of python that come preloaded with matplotlib and many other tools like ipython, numpy, scipy, vtk and user interface toolkits. These packages are quite large because they come with so much, but you get everything with a single click installer.