Easy Install

1. Delete the caches from your :ref:`.matplotlib configuration directory <locating-matplotlib-config-dir>`.

2. Run:

   easy_install -m PackageName
   

3. Delete any .egg files or directories from your :ref:`installation directory <locating-matplotlib-install>`.

Windows installer

1. Delete the caches from your :ref:`.matplotlib configuration directory <locating-matplotlib-config-dir>`.
2. Use :menuselection:`Start --> Control Panel` to start the :program:`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 :ref:`.matplotlib configuration directory <locating-matplotlib-config-dir>`.
2. Delete the build directory in the source tree
3. Delete any matplotlib directories or eggs from your installation directory <locating-matplotlib-install>

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 :ref:`customizing-matplotlib`):

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

The other is to use the matplotlib :func:`~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 :mod:`matplotlib.pyplot` or :mod:`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 (:ref:`howto-webapp`), 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):

And here are the user interfaces and renderer combinations supported:

Compile matplotlib with PyGTK-2.4

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

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

Which python for OS X?

Apple ships with its own python, many users have had trouble with it so there are alternatives. If it is feasible for you, we recommend the enthought python distribution EPD for OS X (which comes with matplotlib and much more) or the MacPython or the official OS X version from python.org.

Installing OSX binaries

If you want to install matplotlib from one of the binary installers we build, you have two choices: a dmg installer, which is a typical Installer.app, or an binary OSX egg, which you can install via setuptools easy_install.

The mkpg installer will have a "dmg" extension, and will have a name like :file:`matplotlib-0.99.0-py2.5-macosx10.5.dmg` depending on the python, matplotlib, and OSX versions. Save this file and double click it, which will open up a folder with a file in it that has the mpkg extension. Double click this to run the Installer.app, which will prompt you for a password if you need system wide installation privileges, and install to a directory like :file:`/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages`, again depedending on your python version. This directory should be in your python path, so you can test your installation with:

> python -c 'import matplotlib; print matplotlib.__version__, matplotlib.__file__'

If you get an error like:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
ImportError: No module named matplotlib

then you will need to set your PYTHONPATH, eg:

export PYTHONPATH=/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages:$PYTHONPATH

See also :ref:`environment-variables`.

If you are upgrading your matplotlib using the dmg installer over an Enthought Python Distribution, you may get an error like "You must use a framework install of python". EPD puts their python in a directory like :file://Library/Frameworks/Python.framework/Versions/4.3.0 where 4.3.0 is an EPD version number. The mpl installer needs the python version number, so you need to create a symlink pointing your python version to the EPS version before installing matplotlib. For example, for python veersion 2.5 and EPD version 4.3.0:

> cd /Library/Frameworks/Python.framework/Versions
> ln -s 4.3.0 2.5

easy_install from egg

You can also us the eggs we build for OSX (see the installation instructions for easy_install if you do not have it on your system already). You can try:

> easy_install matplotlib

which should grab the latest egg from the sourceforge site, but the naming conventions for OSX eggs appear to be broken (see below) so there is no guarantee the right egg will be found. We recommend you download the latest egg from our download site directly to your harddrive, and manually install it with

> easy_install --install-dir=~/dev/lib/python2.5/site-packages/ matplotlib-0.99.0.rc1-py2.5-macosx-10.5-i386.egg

Some users have reported problems with the egg for 0.98 from the matplotlib download site, with easy_install, 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.

Building and installing from source on OSX with EPD

If you have the EPD installed (:ref:`which-python-for-osx`), it might turn out to be rather tricky to install a new version of matplotlib from source on the Mac OS 10.5 . Here's a procedure that seems to work, at least sometimes:

0. Remove the ~/.matplotlib folder ("rm -rf ~/.matplotlib").

1. Edit the file (make a backup before you start, just in case): /Library/Frameworks/Python.framework/Versions/Current/lib/python2.5/config/Makefile, removing all occurrences of the string -arch ppc, changing the line MACOSX_DEPLOYMENT_TARGET=10.3 to MACOSX_DEPLOYMENT_TARGET=10.5 and changing the occurrences of MacOSX10.4u.sdk into MacOSX10.5.sdk

2. In /Library/Frameworks/Python.framework/Versions/Current/lib/pythonX.Y/site-packages/easy-install.pth, (where X.Y is the version of Python you are building against) Comment out the line containing the name of the directory in which the previous version of MPL was installed (Looks something like ./matplotlib-0.98.5.2n2-py2.5-macosx-10.3-fat.egg).

3. Save the following as a shell script , for example ./install-matplotlib-epd-osx.sh

   NAME=matplotlib
   VERSION=0_99
   PREFIX=$HOME
   #branch="release"
   branch="trunk"
   if [  $branch = "trunk" ]
      then
      echo getting the trunk
      svn co https://matplotlib.svn.sourceforge.net/svnroot/$NAME/trunk/$NAME $NAME
      cd $NAME
   
    fi
    if [ $branch = "release" ]
       then
       echo getting the maintenance branch
       svn co https://matplotlib.svn.sf.net/svnroot/matplotlib/branches/v${VERSION}_maint $NAME$VERSION
       cd $NAME$VERSION
    fi
    export CFLAGS="-Os -arch i386"
    export LDFLAGS="-Os -arch i386"
    export PKG_CONFIG_PATH="/usr/x11/lib/pkgconfig"
    export ARCHFLAGS="-arch i386"
    python setup.py build
    python setup.py install #--prefix=$PREFIX #Use this if you don't want it installed into your default location
    cd ..
   

Run this script (for example sh ./install-matplotlib-epd-osx.sh) in the directory in which you want the source code to be placed, or simply type the commands in the terminal command line. This script sets some local variable (CFLAGS, LDFLAGS, PKG_CONFIG_PATH, ARCHFLAGS), removes previous installations, checks out the source from svn, builds and installs it. The backend seems to be set to MacOSX.

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.

• the enthought python distribution EPD
• python (x, y)