Note: You need to know the adminstrator/root password to install what you need. This is the same password OS X asks you for whenever you install or update a significant system component. The "sudo" command, invoked many times below, will produce a prompt asking you for it. This guide also presumes you are comfortable with use of the OS X Terminal application; these commands should be entered at a shell prompt in a Terminal window.
See the Python Statistical Computing Essentials page if you'd like to learn more about this software before or after installation.
OS X comes with a version of Python already installed. However, it is a rather minimalist installation, and it typically lags the current version by one minor version number (e.g, 2.3 vs. 2.4). You should install a separate version that is more recent and more feature-filled. It will not overwrite Apple's version, but it will be installed as the first "python" on your command path, so you will never encounter Apple's Python unless you go out of your way to use it.
I recommend two options; I have installed the software mentioned below with both of them:
/Library/Frameworks/Python.framework/Versions/2.4/lib/python2.4/lib-dynload/I can't guarantee this will work, but several users have reported success with this procedure. You will know it's working if, after starting the interactive Python interpreter with "python", you can use your arrow keys to edit an expression typed at the ">>>" Python prompt.
A quirk of OS X is that its window manager works quite differently than that of other platforms. As a result, if you run a Python program that requires GUI interaction (e.g., anything that plots with matplotlib), you should run it with the GUI-enabled "pythonw" command rather than "python". (ipython, installed below, always uses pythonw on the Mac.) The pythonw command is one of the "extras" you get with the Python distributions above (vs. Apple's Python, which has no cross-platform GUI support).
"python" and "pythonw" get installed in /usr/local/bin; make sure this is earlier than /usr/bin (the location of Apple's Python) in your shell's PATH variable. There are a few other Python-based applications that get installed that you will want to access from the command line (e.g., idle, Python's IDE, and f2py, a Fortran-Python interface tool). To get easy access to these, you need to add the location of your new Python's binary directory to PATH. For example, the beginning of my PATH (from "echo $PATH" at the shell) is:
That second, long path is where MacPython and ActivePython install their binaries. Edit your .cshrc file (for tcsh shell) or .bashrc (for bash shell) to adjust your PATH accordingly.
You will need to be able to install Python packages from source; that is, you will run (simple!) commands that compile C, C++, and Fortran source code. You will also need some libraries the code must link against. You need to have Apple's Developer Tools installed to get gcc. A DVD with the Tools comes with OS X releases; the tools are also available as a free (but large!) download from Apple Developer Connection (you'll need to create a free account, then go to the download area and find the tools for your OS version). You also need Apple's X11 (Tiger users may have it already installed) and Tcl/TK Aqua (BI version). Finally, you need an OS X version of the g77 Fortran compiler. Optionally, consider installing the FFTW2 Fourier transform library to accelerate FFTs. Chris Fonnesbeck's SciPy/Mac OS X Installation page explains where to get g77 and FFTW2.
The gcc compiler used by Apple's Developer Tools recently underwent a major version change, from 3.x to 4.x. For OS 10.4, the default gcc is a 4.x version. Users of a wide variety of software have reported problems due to bugs in early 4.x releases. The safest course is to change the default gcc to 3.x. Use "gcc_select -l" to list available compiler versions. Then use "gcc_select #.#" to set the active gcc compiler to version #.# (you may need administrator privileges to perform this operation; i.e., prefix it with "sudo"). Version 3.3 should be available and should work fine. Reportedly, very recent gcc-4.x versions are relatively bug-free, and you may have success with them (check Apple Developer Connection for the latest version). Further tips on this are at Chris's web page. You have been forewarned.
The matplotlib plotting package requires the FreeType (v. 2.1.7 or later), libpng, and zlib libraries. Panther users in particular will not have all of these unless they have been installed separately; I'm not sure of the situation for Tiger. Perhaps the most-used way to get them is as pre-built binaries via a package manager like Fink or DarwinPorts. (Here are some instructions using DarwinPorts specifically to get these libraries.) If you are using the popular gwTeX distribution of TeX for OS X, then you can use the i-Installer application you used to install TeX to install Freetype and perhaps the other libraries (use the i-Installer to see what's currently available). The libraries also build fine from source, using the standard "./configure --prefix=/usr/local ; make ; make install" installation sequence with minor variations. The Building R page gives instructions for libpng; this Pythonmac-SIG post describes the procedure for FreeType and libpng. Also, recently libpng was made available as an OS X binary from the libpng page linked above. I personally have used FreeType via i-Installer and the other libraries built from source.
You will soon be editing files containing Python source code. It will be handy to use an editor with a Python mode. There are many choices; some that I use on the Mac are xemacs (in an X11 xterm), jEdit, Eclipse with its pydev plugin (huge but feature-filled; good for organizing multi-file projects), and BBEdit (a very popular commercial text editor). If you are an emacs/xemacs fan, there is a useful Python mode for emacs. The IPython page hosts a widely-used, self-contained version: python-mode.el. You may also consider a newer, multi-file version that offers more functionality, just released by the python-mode project.
For several packages, you should be using a recent developer snapshot from the developer SVN or CVS archive, rather than the last official release, due to many recent innovations and bugfixes. At this point, OS 10.4 (Tiger) users are in luck. Chris hosts binary installers for the largest and most important packages we need. Install the numpy, scipy, numarray, and matplotlib packages from OSX at tichech.us (simple instructions are there). Then pick up the installation process below at "ipython-0.7.0". But read the comments at the end of the "scipy" entry, about suppressing import overwrite warning messages, and a recent FFT bug.
For OS 10.3 (Panther) users like myself, binaries may be available within a few days. But in light of the uncertainty, I've packaged all the releases in a single gzipped tarball so you can build the packages from source (time-consuming, but simple; and it's the computer that will take all the time). Download it and unpack it ("tar zxf samsi-dist.tar.gz") somewhere on your hard drive where you have substantial free space (300 MB or so). This will create a directory "samsi-dist" containing all the software. Then, in the following order, in a Terminal window, "cd" into the following directories and run the following install commands. The numbers in brackets indicate the [minutes:seconds] the command took on my old and slow 333 MHz PowerBook G3, to give you some idea of what to expect. Commands with no brackets run very quickly. You may delete each directory after the installation if you'd like to free the space (if you keep them, you can update the contents later via SVN or CVS and rebuild). You can safely ignore the many innocuous compiler warnings that will appear during some install procedures (they're warnings, not errors; real errors will abort the install process). The installations end with little fanfare; if there are no failure messages, the install went just fine.
If you have trouble with the installation, you can ask for help on one of the following email support lists. Please contact me for help only as a last resort, or if you think there is a mistake in these instructions; I will be in very limited email contact until the CASt/SAMSI School is over.
Some packages come with test suites that you can run to verify the installation. I describe some below. I recommend you keep a separate shell open in which to run the tests. This will ensure that Python is finding the package installed in its global site-packages directory, and not in the distribution directory.
Now to the package installations, by directory name under the unpacked distribution:
sudo python setup.py install [5:28]
If you'd like to verify the installation, try this in your home directory (">>>" is the Python prompt; hit Ctl-D to quit Python at the end):
python >>> import numpy >>> numpy.__version__ '0.9.3.1882' >>> numpy.test(1,1)
It will print out a lot of information, including several lines of periods. Each "." indicates a passed test; failures will produce obvious and verbose messages. There may be a few warnings, errors or failures among the ~200 tests (they are being sorted out and won't affect our basic use). On my Mac all tests pass with this numpy release.
sudo python setup.py install [43:51]
python >>> import scipy >>> scipy.__version__ '0.4.4.1544' >>> scipy.test()
For a lengthier suite of tests, you may also try "scipy.test(10)". Around 1000 tests will be run; as above you can ignore the small number of possible failures for now (I get about 10).
A few users have encountered a linking error when the installer attempts to build fftpack. If this happens, consult Chris Fonnesbeck's SciPy install page for a workaround.
When you import scipy, it imports numpy. Both packages have FFT functions, so you will see a warning that SciPy is "overwriting" NumPy's fft and ifft functions. You can disregard this. If you'd like to suppress this import warning, set the SCIPY_IMPORT_VERBOSE environment variable to "-1" in your shell. For tcsh, use "setenv SCIPY_IMPORT_VERBOSE -1" and for bash, use "export SCIPY_IMPORT_VERBOSE=-1". You can use these at the command line, or stick them in your .cshrc or .bashrc file to make them "permanent."
One last quirk. Recent revisions introduced a bug with SciPy's FFTs in at least some OS X installations; NumPy's FFTs remains solid. This will get sorted out soon; in the meantime, use numpy.fft and numpy.ifft in place of scipy.fft and scipy.ifft.
sudo python setup.py install --gencode [10:16]
python >>> import numarray.testall as testall >>> testall.test()
sudo python setup.py build [33:18] sudo python setup.py install [0:55]
Test it by going into the "examples" directory and trying to plot one of the examples. Since matplotlib displays plots in a GUI window, you need to use "pythonw" to run the examples in OS X. Try:
cd examples pythonw fill_demo.py
In the course of making your first plot, matplotlib will create a ".matplotlib" directory in your home directory where it can access a startup profile and cache various information. You will likely see a bunch of warnings referring to obscure fonts it cannot find as it tries to build a font cache; you can safely ignore these! You should soon see a plot; when you close it, the Python command will terminate.
At this point, return to the install directory, where you'll find a default startup profile, "matplotlibrc". Copy this to your .matplotlib directory:
cd .. cp matplotlibrc ~/.matplotlib
Use your favorite text editor to edit the copy in your .matplotlib directory (not the original!). About 30 lines down from the top you should find two lines that look like this:
backend : TkAgg numerix : numpy # numpy, Numeric or numarray
Make sure they say ": TkAgg" and ": numpy" as shown above. These tell matplotlib to use an anti-aliasing Tcl/Tk backend for plotting, and to use numpy arrays.
Since we'll be using ipython to draw plots with matplotlib, we need to build it with "pythonw" rather than "python"; this signals the installer to build a GUI-capable version. The ipython program is a Python script; tell the installer to put the script in /usr/local/bin so your shell will know where to find it.
The first time you run IPython (just type "ipython" at the shell), it will create a ".ipython" directory in your home directory (and warn you about it). It installs a set of default startup profiles there that you may edit to customize how IPython behaves.
sudo python setup.py install
One of IPython's profiles is intended for use with SciPy and is invoked with "ipython -p scipy". However, it tries do some "magic" tailored to the last official release and won't work with the latest version. So just use plain "ipython" for now, or write your own profile that automatically imports scipy.
sudo python setup.py install
If you'd like to work through the STScI Data Analysis With Python Tutorial, you should also install the DS9 image viewer (binaries for all major platforms are at the DS9 web site) and the following Python package from STScI, included in the tarball:
sudo python setup.py install
Finally, copy the "samsi-for-home.tar.gz" file to your home directory and unpack it there. It will create a "samsi" directory that includes a copy of the matplotlib examples directory (a good source of plotting recipes), and copies of some basic documentation: the official Python Tutorial and Standard Library docs, the IPython manual, the matplotlib tutorial, and the STScI Python Data Analysis Tutorial.
The numpy, scipy, and numarray installations are from current SVN or CVS developer archive revisions. There will be solid official releases of all of these packages quite soon, including binary installers for several platforms; check the web sites (linked on the Essentials page) for news about official releases. If you are ambitious (courageous?) and wish to stay on the "bleeding edge," do not delete the unpacked directories after installing the software. As you wish, update them via SVN or CVS as follows (execute these in your shell in the directory right above the package directory), and re-install the packages.
NOTE: Before you reinstall a developer snapshot, which may have significant internal reorganization, you should manually remove all results of an earlier installation. To do this, delete the "build" folder within the package's source directory (the installer creates this to store files during the installation process). Also, delete the installed Python package in your Python's "site-packages" directory. This is a directory with the same name as the package, located here:
numpy from SVN (monitor at numpy SVN timeline):
svn co http://svn.scipy.org/svn/numpy/trunk numpy
scipy from SVN (monitor at scipy SVN timeline):
svn co http://svn.scipy.org/svn/scipy/trunk scipy
numarray from CVS:
cvs -d:pserver:firstname.lastname@example.org:/cvsroot/numpy login cvs -z3 -d:pserver:email@example.com:/cvsroot/numpy co -P numarray
matplotlib from CVS:
cvs -d:pserver:firstname.lastname@example.org:/cvsroot/matplotlib login cvs -z3 -d:pserver:email@example.com:/cvsroot/matplotlib co -P matplotlib
10 January 2006 Tom Loredo