Building Matplotlib for MacOS X 10.6 and later

To build a binary installer for matplotlib that others can use on other versions of MacOS X, use Matthew Brett's build scripts, which as of matplotlib 1.3.1 are the official way to build the binary installer. The following information may possibly also be of some use.

Note: every line that begins with $ is intended to be typed into Terminal (without the leading $; it simply represents the Terminal's prompt).

Install python

Install Python from Using this python will make your matplotlib installer maximally compatible with various versions of Mac OS X.

Install XCode (Apple's Developer Tools) command-line tools

Install Xcode. You must be a registered developer to download XCode, but registration is free.

Then install the command-line tools using xcode-select --install (or for older versions of XCode, look in XCode Preferences>Downloads).

Configure Your Environment

Install Unix Libraries (or XQuartz/X11)

MacOS X with optional XQuartz (X11 on MacOS X 10.7 and earlier) includes all the libraries matplotlib needs. If you are building matplotlib for your own use then simply install XQuartz (or X11). However, if you want to build a binary installer for others to use (and don't want those others to have to install XQuartz or X11) then you must build your own libfreetype and libpng libraries and link those statically. See Matthew Brent's build scripts for details.

Install Python Packages

Install numpy

Matplotlib requires numpy, preferably using the official binary installer (which, for awhile, were surprisingly hard to find).

Install other required packages using pip

maplotlib requires following packages. They can be installed using pip or easy_install or manually from source:

Note: if pip won't install pytz then download the source and install using "python install". (At the time of this writing there is a known bug that pip can't understand pytz's version numbers).

Install wxPython

If you want WXAgg support you must install wxPython. I recommend the most recent stable release (2.8.x at this writing; the 2.9 series is a development branch and is best avoided unless you want to be a beta tester).

Install setuptools

Install setuptools. Download it, unpack it and type:

$ python build
$ python install

Install bdist_mpkg

Install bdist_mpkg, preferably using pip or easy_install, since those will install the prerequisite packages.

Build Matplotlib

Download and Unpack Matplotlib

Configure matplotlib

Build the Matplotlib Installer

To create a double-clickable installer package that you and others can use to install matplotlib:

Run Terminal and cd to the top level of the matplotlib source directory:

$ bdist_mpkg

or you want to run a bdist_mpkg for a particular version of python you can be explicit, for example:

$ /Library/Frameworks/Python.Framework/Versions/2.6/bin/bdist_mpkg

The binary installer will be inside subdirectory dist.

Build An Egg

If you wish to have an egg distribution, you can build it as follows:

First edit and comment out the lines for pytz, dateutil and six (if present) so that they are not built. They should be a dependency of the egg rather than included in the egg.

Then build the egg as follows:

$ python bdist_egg

The egg file will be inside subdirectory dist.

Test the Result

Install matplotlib using your new installer. cd out of the matplotlib source directory and run the tests:

$ python -c "import matplotlib as m ; m.test(verbosity=1)"


Final Cleanup

Save your /usr/local in case you wish to do future builds, and move your normal /usr/local back into place (if you had one):

$ sudo mv /usr/local /usr/local-static
$ sudo mv /usr/local-disabled /usr/local

Before distributing the binary installer I recommend a few cleanup steps:


Many thanks to Charlie Moad and mpsuzuki for help with installation instructions and to Sandro Tosi and Derek Homeier for testing instructions.


Russell Owen
University of Washington
PO Box 351580
Seattle, WA 98195-1580
rowen uw edu
     @  .