@header@ 
<h2>Installing matplotlib</h2>

matplotlib requires at a minimum python 2.2+, Numeric or numarray and
freetype.  To get the most out of matplotlib, you will want to build
some of the optional GUI and image extensions, discussed below.
Matplotlib is known to work on linux, unix, win32 and OS X platforms.<p>

There are two kinds of matplotlib backends: vector based and raster
based.  The vector based backends, SVG and PS, produce ASCII text
output files *.svg and *.ps.  The core raster based renderer is the <a
href=http://antigrain.com>antigrain</a> (agg) backend.  This is a high
quality 2D library that supports fast antialiasing, alpha blending and
much more.  If you want to produce PNGs or GUI images that support all
of matplotlib's features, you should compile matplotlib with agg
support and use one of the GUI agg backends as described below:
GTKAgg, WXAgg, TkAgg or FLTKAgg.  All of these features are included
in the windows installer<p>

<h2><a name=compiling>Compiling</a></h2>

You will need to have recent versions of freetype (>= 2.1.7), libpng
and zlib installed on your system.  If you are using a package
manager, also make sure the devel versions of these packages are also
installed (eg freetype-devel).<p>

The top of setup.py contains some flags controlling which backends
will be built.  If you want to use a GUI backend, you will need either
Tkinter, pygtk or wxpython installed on your system, from src or from
a package manager including the devel packages.  You can choose which
backends to enable by setting the flags in setup.py, but the 'auto'
flags will work in most cases, as matplotlib tries to find a GUI and
build the backend acccordingly.  If you know you don't want a
particular backend or extension, you can set that flag to False.<p>

As discussed above, most users will want to set <tt>BUILD_AGG = 1</tt>
and one or more of the GUI backends to True.  Exceptions to this are
if you know you don't need a GUI (eg a web server) or you only want to
produce vector graphics.<p>

If you have installed prerequisites to nonstandard places and need to
inform matplotlib where they are, edit <tt>setupext.py</tt> an add the
base dirs to the <tt>basedir</tt> dictionary entry for your
<tt>sys.platform</tt>.  Eg, if the header to some required library is
in <tt>/some/path/include/somheader.h</tt>, put <tt>/some/path</tt> in
the basedir list for your platform.<p>

Note, matplotlib works with with Numeric or numarray, but it is
important that you set <tt>NUMERIX</tt> in <tt>setup.py</tt> to the
array package you typically use, for efficiency reasons.  For
performace, it is critical that the numerix settings in setup.py and
in your .matplotlibrc file are the same, and are the same as the array
package you typicaly use.<p>

Note that if you install matplotlib anywhere other than the default
location, you will need to set the <tt>MATPLOTLIBDATA</tt> environment
variable to point to the install base dir.
 
    
<h2><a name=windows>Windows</a></h2>

If you don't already have python installed, you may want to consider
using the enthought edition of python, which has scipy, Numeric, and
wxpython, plus a lot of other goodies, preinstalled - <a
href=http://www.enthought.com/python> enthought python</a> .  With the
enthought edition of python + matplotlib installer, the following
backends should work out of the box: agg, wx, wxagg, tkagg, ps and
svg.<p>

For standard python installations, you will also need to install
either Numeric or numarray in addition to the matplotlib installer.
matplotlib provides installers for Numeric and numarray users.  It is
important that you pick the matplotlib installer that corresponds to
your array package.  Ie, if you mostly work with numarray arrays, use
the matplotlib numarray installer.  matplotlib has a <tt>numerix</tt>
setting in the matplotlib rc file (which by default resides in
<tt>c:\python23\share\matplotlitb\.matplotlibrc</tt>) and you should
make sure this setting corresponds to your preferred array package.<p>

With a standard python + Numeric/numarray + matplotlib, the following
backends should work on windows: agg, tkagg, ps, svg.  If you want
others, eg a wx, wxagg, gtk or gtkagg, you'll need to install the
requisite GUI toolkits, as described on <a
href=backends.html>backends</a>.  This is fairly easy, as both
wxpython and pygtk come with windows friendly installers.  The latter
includes an additional requirement of the GTK runtime.<p>

All of the GUI backends run on windows, but TkAgg is probably the best
for interactive use from the standard python shell or ipython.  The
windows installer (*.exe) on the download page contains all the code
you need to get up and running.  However, there are many examples that
are not included in the windows installer.  If you want to try the
many demos that come in the matplotlib src distribution, download the
zip file and look in the examples subdir.<p>

<i>Important: There are known conflicts with some of the backends with
some python IDEs such as pycrust, idle.  If you want to use matplotlib
from an IDE, please consult <a
href=backends.html>backends</a> for
compatibility information.  You will have the greatest likelihood of
success if you run the examples from the command shell or by double
clicking on them, rather than from an IDE.  If you are interactively
generating plots, your best bet is TkAgg from the standard python
shell or ipython.</i>

<h3><a name=osx>OS X</a></h3>

All of the backends run on OS X.  fink users consult the fink section
below.  Another option is <a
href=http://www.stecf.org/macosxscisoft>scisoft</a> which packages
many scientific packages for python on OS X, including matplotlib,
although it is designed for astronomical analysis.</p>

If you want to compile yourself on OS X, make sure you read the
compiling instructions above.  You will need to install freetype2,
libpng and zlib via fink or from src.  You will also need the base
libraries for a given backend.  Eg, if you want to run TkAgg, you will
need a python with Tkinter; if you want to use WxAgg, install
wxpython.  See <a href=backends.html>backends</a> for a more
comprehensive discussion of the various backend requirements.  Edit
setup.py to configure the backends you want to build as described
above.

<h2>Package Managers: (rpms, apt, fink)</h2>

<h3><a name=rpms>RPMS</a></h3>

To build all the backends on a binary linux distro such as redhat, you
need to install a number of the devel libs (and whatever dependencies
they require), I suggest
<ul> 
	
  <li>matplotlib core: zlib, zlib-devel, libpng, libpng-devel,
      freetype, freetype-devel, freetype-utils</li>

  <li>gtk/gtkagg backend: gtk2-devel, gtk+-devel, pygtk2, glib-devel,
      pygtk2-devel, gnome-libs-devel, pygtk2-libglade</li>

  <li>tk backend: tcl, tk, tkinter</li>

  <li>wx/wxagg backends - the wxpython rpms from <a
  href=http://wxpython.org</a>wxpython</a></li>

</ul>

<h3><a name=debian>Debian</a></h3>

Vittorio Palmisano <redclay@email.it> maintails the debian
packages at http://mentors.debian.net

<ul>
    <li> add these lines to your /etc/apt/sources.list: 
<pre>
      deb http://mentors.debian.net/debian unstable main contrib non-free
      deb-src http://mentors.debian.net/debian unstable main contrib non-free
</pre> 
    </li>
   
      <li> then run:
<pre>   
        > apt-get update
        > apt-get install python-matplotlib python-matplotlib-doc
</pre>         
  </li>
</ul>


<h3><a name=fink>Fink</a></h3>

fink users should use Jeffrey Whitaker's fink distribution, which
supports the GTK, TkAgg, GTKAgg, PS, WX, WXAgg and Agg backends. See
<a
href=http://fink.sourceforge.net/pdb/package.php/matplotlib-py23>matplotlib
fink</a>
@footer@