Installing Python – iPython, Numpy, Scipy and Matplotlib on OS X (The old version)

Important Note

As of the 29th of July 2008 I’ve stopped maintaining this page. This is because Entought have produced a binary python distribution for OS X, which has every scientific package you could want installed. So I’m planning to run with that for a while to see how things go there. Should I start reinstalling from base components I’ll start updating this page again. Alternatively feel free to update it yourself. The Enthought distribution is available here.

Aim of this Guide

The aim of this guide is to inform you of all the options for installing python on Mac OS X and it’s scientific tools such as numpy, scipy, matplotlib and ipython. There are step by step instructions for installing MacPython with Numpy, SciPy, Matplotlib and iPython on Mac OS X.

Overview – The state of Python on Apple’s Mac OS X

Different Distributions

Okay so you want to get ipython with pylab running so that you can do some modelling or other scientific work on OS X. Unfortunately python on OS X is a bit of a mess, mainly because it’s available from so many sources and all are slightly different.

  • Firstly there’s Apple’s version shipped with the OS. Yes python is already installed, just launch the Terminal (Applications->Utilities) and type python at the command prompt. The problem with this is that unless you are using a version of the OS which has just been released the chances are that it is a rather out of date version of python and for various reasons (mostly involving possibly breaking OS behaviour) it’s not recommended that you update this version. Even if you are using a brand new version of OS X (currently 10.5) which has the latest version of python (10.5 come with python 2.5) it’s still not generally recommended that you use the system install of python. Interestingly 10.5 also has numpy installed by default as well.
  • That leaves us with the four (yes four) other versions available to us.
    • First there’s the offical MacPython distro which can be found on the official python website.
    • There’s ActivePython which is essential another distribution of MacPython but actually puts the help files in the OS X help browser. Go to the ActivePython homepage to download it.
    • Then there is the Fink version which can be obtained through Fink.
    • Finally there is the MacPorts (formally DarwinPorts) version which can be obtained through MacPorts.

Install locations

The unfortunate thing about all these various distros is that the support for various packages is different for each of them and mixing and matching is not a sensible option as they all install to different locations. So for instance

  • Apple’s install is here – /System/Library/Frameworks/Python.framework
  • MacPython’s install goes here – /Library/Frameworks/Python.framework (note this is based in /Library not /System and is thus a different location)
  • ActivePython is the same location as MacPython (if I remember correctly)
  • Fink installs to here – /sw/lib /sw/bin etc (/sw is created by fink to install all fink packages into)
  • MacPorts installs to here – /opt/local/lib /opt/local/bin etc (/opt/local is created by MacPorts to install all MacPorts packages into)

So as you can see, if you install MacPython and then install ipython from Fink it’s not going to be installed in the correct place, infact fink will realise that ipython needs python and hence also install it’s version of python into /sw with ipython and any other dependancies. This means that you can rapidly end up with more versions of python than you want or need installed on your OS X box along with potentially the required packages scattered all over the place and hence in nonworking order.

Choosing a Distribution

So the question is what version should I install? If you are only looking to play around with python and learn the ropes you can probably get by quite happily with the version already installed in OS X. If you want to do more like setup a Matlab type scientific environment with python using numpy, scipy, matplotlib and ipython then you’ll need to install from one of the other four options.

MacPython benifits from tieing into the API set of OS X and is Framework based. This means that a lot of tools for integrating with OS X are available to you in the MacPython version and if you are thinking of tying into OS X then this is the way to go and the instructions for that are below. ActivePython is basically the same as MacPython as far as we are concerned here the notable difference being that the Help files are linked into OS Xs help browser. If you want to use ActivePython try following the instructions below which should hopefully work for you. Fink and MacPorts are similar in concept. I think that generally speaking I find Fink to be a friendlier package manager with much broader package support than MacPorts though you need to remember to enable unstable packages (which are quite often stable, they simply haven’t had enough testing) to install scipy and matplotlib. MacPorts does the same thing and both are package managers so you can use them to check for updates and have them update python and the various modules as and when. The downside is that the packages are straight unix ports, so there is no tie in with Mac OS X in python. This may be a sensible route to go if you want to ensure your code works as well on linux as it does on OS X. It can also be a very simple way to install as the package manager realises when you are missing some required packages and installs them as well. For instructions on how to install using Fink of MacPorts see [[#Other OS X install guides|other os x install guides]].

Installing MacPython with Numpy, Scipy, Matplotlib and iPython

Prerequisites

  1. First thing you need to do is install the developer tools either of your Mac OS X install DVD or by downloading Xcode from the Apple Developer Connection website (free registration required). This will take a while to install so while that is going on you can download all the other bits you need.
  2. Next up is X Windows, you need to install this to support various things. Again it can be installed of your Mac OS X install DVD and then you’ll need to run Software Update to bring it upto date. See this page for more information.
  3. Next is Fortran. You can download GNU F95 as a universal binary (linked to .dmg) from this site and just install it using the graphical installer. If you really want to build and install your own version then look at this site. No matter which you do, you need to make sure that gfortran (in /usr/local/bin) is on your PATH after you have installed it. If you are using the bash shell this can be done by typing in the Terminal (Applications->Utilities):

export PATH=$PATH:/usr/local/bin

You can check what is on your PATH and what shell you are using by typing:

env

  1. FFTW is a C routine for Fast Fourier Transforms. Version 3.1 is already installed in OS X 10.5 so you shouldn’t need to worry about it but if you are installing onto 10.4 then you’ll want to grab the source here and then install it. To install it you need open the Terminal in Applications->Utilities and type the following hitting enter after every line (comments are in brackets and should not be typed):

cd ~/Downloads (or cd ~/Desktop if you've downloaded the file to you desktop ~ is a unix shortcut for your home folder)
tar -xvzf fftw-3.1.2.tar.gz (or tar -xvf if it has already been unzipped which OS X tends to do automatically)
cd fftw-3.1.2
./configure
make
sudo make install (You will be asked to enter your password)

Python

  1. With that stuff out of the way now we can get down to installing Python and the modules mentioned above. From the MacPython pages you can choose the most recent version of Python and download it (currently 2.5). So these are all binary installers with the familiar installer interface to anyone who has used OS X. (Alternatively you can download and install ActivePython). Just double click on the file to mount it and then double click on the installer and follow the instructions. You will need admin privileges.
  2. So now you should have the MacPython IDE (Integrated Development Environment) called IDLE in your Applications folder under MacPython 2.5. You can launch this and if you type help() and then modules you will get a full list of all the modules installed which will currently not include Matplotlib, Numpy and Scipy. Quit IDLE.
  3. Next you should download and install wxPython from MacPython. Again this is a .dmg installer and does everything in a standard mac installer way. wxPython is needed to allow matplotlib to plot using X windows.
  4. So now it’d be nice to install Numpy, Scipy and Matplotlib in one go. Well you could try downloading the Scipy Superpack for Intel OS X which aims to do just that. It seems to work for a lot of people, clearly if you have a PPC based Mac you need to follow the instructions below. I would give this a try and then test it [[#Testing out your install|following the testing out your install instructions]]. See what bits are working and if some bits aren’t working try reinstalling the broken bits using the instructions below. Alternatively ignore Scipy Superpack and follow the instructions below.

Numpy

  1. Numpy can be downloaded as a binary installer from MacPython or the latest version can now be downloaded as a binary from numpy. Again this is a straight forward .dmg file. Alternatively you can download the source and build your own version. You’ll need to open the Terminal in Applications->Utilities and type the following hitting enter after every line (comments are in brackets and should not be typed):

cd ~/Downloads (or cd ~/Desktop if you've downloaded the file to you desktop)
tar -xvfz numpy-1.1.0.tar.gz (or tar -xvf if it has already been unzipped which OS X tends to do automatically)
(note sometimes the file seems to end up called numpy-1.1.0.tar.gz.tar in which case just use -xvf)
cd numpy-1.1.0
python setup.py build
sudo python setup.py install</pre></code>

Scipy

  1. Scipy needs to be built against the installed version of Numpy so you can’t generally get away with installing Scipy from a separate binary to the Numpy one. So you can  download Scipy here. The install procedure is essentially the same as above.

cd ~/Downloads (or cd ~/Desktop if you've downloaded the file to you desktop)
tar -xvfz scipy-0.6.0.tar.gz (or tar -xvf if it has already been unzipped which OS X tends to do automatically)
(note sometimes the file seems to end up called scipy-0.6.0.tar.gz.tar in which case just use -xvf)
cd scipy-0.6.0
python setup.py build
sudo python setup.py install</pre></code>

  1. So Numpy and Scipy should now both be installed and next on our list is Matplotlib. You may want to [[#Testing out your install|test out your Numpy and Scipy install]] in IDLE before carrying on.

Matplotlib

  1. You can try the binary install of Matplotlib available on the MacPython page. Again this is a .dmg file and is easy to install. Hopefully that will work fine and you can skip to installing [[#iPython|iPython]].
  2. If you need to build from source (which is what I ended up having to do) then you can download the source here. Installing follows a similar procedure to that for Numpy and Scipy.

cd ~/Downloads (or cd ~/Desktop if you've downloaded the file to you desktop)
tar -xvfz matplotlib-0.91.2.tar.gz (or tar -xvf if it has already been unzipped which OS X tends to do automatically)
(note sometimes the file seems to end up called matplotlib-0.91.2.tar.gz.tar in which case just use -xvf)
cd matplotlib-0.91.2
python setup.py build
sudo python setup.py install

You should get a message telling you what Matplotlib has found to build with. It needs to find: python, numpy, freetype2, libpng, Tkinter and wxPython. If it’s missing any of these you need to install them. Hopefully it will install fine and you can skip down to installing [[#iPython|iPython]].

==================================================================
BUILDING MATPLOTLIB
matplotlib: 0.91.2
python: 2.5.1 (r251:54869, Apr 18 2007, 22:08:04) [GCC
4.0.1 (Apple Computer, Inc. build 5367)]
platform: darwin
REQUIRED DEPENDENCIES
numpy: 1.0.4
freetype2: 9.12.3
OPTIONAL BACKEND DEPENDENCIES
libpng: found, but unknown version (no pkg-config)
Tkinter: Tkinter: 50704, Tk: 8.4, Tcl: 8.4
wxPython: 2.8.3.0
* WxAgg extension not required for wxPython >= 2.8
Gtk+: no
* Building for Gtk+ requires pygtk; you must be able
* to "import gtk" in your build/install environment
Qt: no
Qt4: no
Cairo: no
OPTIONAL DATE/TIMEZONE DEPENDENCIES
datetime: present, version unknown
dateutil: matplotlib will provide
pytz: matplotlib will provide
OPTIONAL USETEX DEPENDENCIES
dvipng: 1.9
ghostscript: 8.57
latex: 3.141592
EXPERIMENTAL CONFIG PACKAGE DEPENDENCIES
configobj: matplotlib will provide
enthought.traits: matplotlib will provide
[Edit setup.cfg to suppress the above messages]
==================================================================

freetype2 and libpng are both included in X11 in /usr/X11R6 so you can just point Matplotlib at them. To do this edit setupext.py (in the matplotlib folder using a text editor) and add /usr/X11R6 to the basedir dictionary for the darwin key. You may well find this is already the case in which case you don’t need to change it. It should look the same as below.

 basedir = {
 'win32' : ['win32_static',],
 'linux2' : ['/usr/local', '/usr'],
 'linux' : ['/usr/local', '/usr',],
 'cygwin' : ['/usr/local', '/usr',],
 'darwin' : ['/sw/lib/freetype2', '/sw/lib/freetype219', '/usr/local',
 '/usr', '/sw', '/usr/X11R6'],
 'freebsd4' : ['/usr/local', '/usr'],
 'freebsd5' : ['/usr/local', '/usr'],
 'freebsd6' : ['/usr/local', '/usr'],
 'sunos5' : [os.getenv('MPLIB_BASE') or '/usr/local',],
 'gnukfreebsd5' : ['/usr/local', '/usr'],
 'gnukfreebsd6' : ['/usr/local', '/usr'],
 'aix5' : ['/usr/local'],
 }

You need to install pkgcong-0.23 so that matplotlib can use it to find and properly configure libpng and freetype.

 cd ~/Downloads (or cd ~/Desktop if you've downloaded the file to you desktop ~ is a unix shortcut for your home folder)
 tar -xvzf pkgcong-0.23.tar.gz (or tar -xvf if it has already been unzipped which OS X tends to do automatically)
 cd pkgcong-0.23
 ./configure
 make
 sudo make install (You will be asked to enter your password)

You will need to set the pkgcong path

export PKG_CONFIG_PATH=/usr/X11/lib/pkgconfig

Then try the same install again and see if it works

cd matplotlib-0.91.2
 python setup.py build
 sudo python setup.py install

So you may find that you also need to install pytz if you get errors related to pytz when launching ipython -pylab. If you do, install pytz and then re-run the above matplotlib install again.

iPython

  1. Finally we need to install ipython which is an interactive python shell suited to scientific devleopment amongst other things. Unfortunately there is no convient binary install for OS X so you need to download the source and build it. Don’t worry though this isn’t hard. First go to the ipython downloads page and download the latest stable released source. Currently it’s a file called ipython-0.8.2.tar.gz at any rate it’ll be the .tar.gz file that you are after.
  2. Again the install procedure is similar to ones outlined above open the Terminal in Applications->Utilities and type the following hitting enter after every line:
 cd ~/Downloads (or cd ~/Desktop if you've downloaded the file to you desktop)
 tar -xvfz ipython-0.8.2.tar.gz (or tar -xvf if it has already been unzipped which OS X tends to do automatically)
 (note sometimes the file seems to end up called ipython-0.8.2.tar.gz.tar in which case just use -xvf)
 cd ipython-0.8.2
 python -c "import sys;print sys.prefix

The second command will return a path and that path should be /Library/Frameworks/Python.framework/Versions/2.5 which means that ipython will install into the our newly installed version of MacPython (which may be 2.4, 2.5 or later). Now all that is left to do is build and install ipython with the following two commands.

 python setup.py build
 sudo python setup.py install

So that’s it we’re done.

Testing out your install

So it’s probably worth while just stepping through a couple of things to test your install. We’ll start by using IDLE to test numpy, scipy and matplotlib before finally checking they all work in ipython.

  • Go to Aplications->MacPython and launch IDLE. A window will open with the current version of python and the cursor will be displayed after >>>. Type help() and hit return then type modules for a list of the installed modules. You should see Numpy, Scipy and Matplotlib listed if you have installed them.
 Python 2.5.1 (r251:54869, Apr 18 2007, 22:08:04)
 [GCC 4.0.1 (Apple Computer, Inc. build 5367)] on darwin
 Type "copyright", "credits" or "license()" for more information.
****************************************************************
 Personal firewall software may warn about the connection IDLE
 makes to its subprocess using this computer's internal loopback
 interface. This connection is not visible on any external
 interface and no data is sent to or received from the Internet.
 ****************************************************************
IDLE 1.2.1
 >>> help()
Welcome to Python 2.5! This is the online help utility.
If this is your first time using Python, you should definitely check out
 the tutorial on the Internet at http://www.python.org/doc/tut/.
Enter the name of any module, keyword, or topic to get help on writing
 Python programs and using Python modules. To quit this help utility and
 return to the interpreter, just type "quit".
To get a list of available modules, keywords, or topics, type "modules",
 "keywords", or "topics". Each module also comes with a one-line summary
 of what it does; to list the modules whose summaries contain a given word
 such as "spam", type "modules spam".
help> modules
Please wait a moment while I gather a list of all available modules...
  • After confirming that the required modules show up in the modules listings it’s time to run numpy and scipy’s built in tests. Type the following for numpy
 >>> import numpy
 >>> numpy.test(1,10)

This should run a series of tests and tell you how many passed and how long they took. Generally I find one or two tend to fail on me but mostly everything works. If your install really isn’t working it’ll probably not complete any tests.

  • The same thing can be done for scipy
 >>> import scipy
 >>> scipy.test(1,10)

Again a series of tests will be run and python will tell you how long they took and what the outcome was.

  • To test out your plotting download the examples folder from matplotlib. Assuming it is on your Desktop and has been decompressed then type the following in ipython.
 >>>cd ~/Desktop/examples
 >>>run bar_stacked.py

You should now have a nice bar graph displayed in front of you. You can get a full list of examples by typing ls and then run any of them by typing run name_of_example_file.

  • If you’ve closed the Terminal open it up again and type ipython -pylab (or just ipython if you don’t want matplotlib functionality) at the command prompt. This will launch the ipython environment within the terminal. You should see something similar to that below.
 Python 2.5.1 (r251:54869, Apr 18 2007, 22:08:04)
 Type "copyright", "credits" or "license" for more information.
IPython 0.8.2 -- An enhanced Interactive Python.
 ? -> Introduction and overview of IPython's features.
 %quickref -> Quick reference.
 help -> Python's own help system.
 object? -> Details about 'object'. ?object also works, ?? prints more.
Welcome to pylab, a matplotlib-based Python environment.
 For more information, type 'help(pylab)'.
In [1]:

So now you can try some simple things out like 2+2 followed by enter will return 4 on the next line. It’s worth checking that your readline support is working by hitting the up arrow on your keyboard. This should cause 2+2 to reappear at your command prompt. To test Numpy and Scipy and Matplotlib enter the following in iPython.

 In [1]: import numpy
In [2]: import scipy
In [3]: numpy.test(1,10)
In [4]: scipy.test(1,10)
In [5]: cd ~/Desktop/examples
In [6]: run bar_stacked.py

That’s it. You now have a fully working MacPython install with iPython, matplotlib, Numpy and Scipy.

Some Notes

It’s worth pointing out that you try to run python commands from the terminal you need to cd out of the directory you’ve just installed from. For example if I build numpy from source and then install it, then run python and try to test numpy from the command line it will almost certainly fail. This is because the terminal will try and run the unbuilt copy in the directory that you are currently in over the system installed one. Essentially the terminal assumes you want to run the locally available files over the system wide ones. This makes sense but can be confusing if you’re not expecting it. A simple cd ~ will almost certainly sort the problem out.

Tutorials and Links

Offical Guides

MacPython and a link to the docs Installing MacPython

Installing Numpy and SciPy and the Numpy docs page

Installing matplotlib and notes on how to build it

Download and install instructions and the Installing ipython docs page

Other OS X install guides

Superpack for Intel OS X. Not really an install guide but a handy link because it removes a lot if install hassle.

Fink based instructions for Python and the Scientific tools from Davis University in California

MacPython and ActivePython instructions from Cornell

A very comprehensive set of instructions at NIST based around getting FiPy running but also includes NumPy, SciPy, matplotlib and ipyhton.

Basic instructions from Cornell

Some instructions from Berkeley