Installing scientific Python on Mac OS X

Getting scientific Python running on a Mac is one of the biggest hurdles for data scientists who are just getting started (and, trust us, professionals too!). We'd usually steer readers toward one of the more popular articles on the subject, but it's gotten a bit stale. Therefore, here are updated step-by-step instructions for getting a basic environment set up.

In this guide we'll install the following packages:

  1. Quickstart
  2. Homebrew
  3. Python
  4. virtualenv and virtualenvwrapper
  5. NumPy
  6. SciPy
  7. matplotlib
  8. IPython and the Qt console



For the impatient, the following code will get you up and running without delay. Otherwise, please continue reading the rest of this post for step-by-step instructions and explanations.

NB: This code assumes Homebrew is installed; if it isn't, follow the instructions below! Also, be sure to follow any instructions Homebrew gives after each installation, such as modifying your path variables.



Homebrew's homepage puts it well: "Homebrew installs the stuff you need that Apple didn’t." (It used to say, "Homebrew is the easiest and most flexible way to install the UNIX tools Apple didn't include with OS X," which may not be as catchy as the new wording, but does a better job explaining.) You will need to have XCode and its Command Line Tools installed first (get them in the App Store). Then, install Homebrew on your machine by pasting this into Terminal:

That's it. Try running brew update and brew doctor at the command line to make sure it's working properly.

You'll need to add the Homebrew directory to the front of your system path, in order to ensure that Homebrew-installed software is given priority over any other versions. To do so, open the .bash_profile in your user directory (that's the ~ directory or, more verbosely, /Users/[your_user_name]) and add the following line (if you don't have a .bash_profile, just create one with any text editor):

Restart Terminal so it picks up the new path. Homebrew is generally very good about alerting you to any action you need to take after it runs, including path modifications. Make sure to pay attention to its output.



Now to the main event: Python. These instructions are for version 2.7.3. If you want to install something else, like Python3, just adjust the commands as required. With Homebrew, getting Python is quite easy:

This will also install package management tools like pip, which we'll need later. To get them to work seamlessly, add this to your .bash_profile:

To verify the installation, type which python into Terminal. You should see /usr/local/bin/python in response.



virtualenv is a tool that allows you to create isolated Python environments, each with its own set of packages and dependencies. This is useful for testing or managing package requirements (for example, if you build an application that is dependent on a certain version of a third-party package but another application requires a more recent version, you might break the first application by upgrading). This is not required, and all the commands below should work whether or not you are using virtualenv, so consider this step for convenience only. The only difference will be that directories (such as that returned by which pip) will point to the virtualenv rather than /usr/local.

First, install virtualenv and virtualenvwrapper, a tool that makes working with virtualenv somewhat easier:

Next, source the virtualenvwrapper script:

This will create a (hidden) virtualenv directory at ~/.virtualenv. Now you can create your first virtual environment:

Your new virtualenv test1 comes with a complete install of Python 2.7.3 and its own version of pip. It is activated by default, so running any pip command will only impact this environment. Note that if you deactivate the virtualenv, you will lose access to any packages installed in it. You can switch between virtualenvs with the workon command. To delete your test virtualenv, run rmvirtualenv test1.



NumPy, of course, forms the basis of most scientific work in Python. NumPy can be installed with pip, but that method failed on Macs until quite recently (see pip issue #707). If you'd like to try it, simply execute the following in Terminal:



SciPy requires a Fortran compiler. To acquire one, use Homebrew:

Once that installs, you may choose to install SciPy with pip:



Installing matplotlib, a versatile plotting library, follows the same pattern. However, you may have to install freetype first:

Either use pip:



If you're not using IPython as your interactive console, you should be. It improves on the stock Python console in every way. Installing IPython itself is a fairly straightforward pip command:

Getting the Qt Console to run is more difficult, but well worth it. First, you'll need to download the Qt library from this site. Once you have that set up, begin installing the prerequisites:

After installing pyqt, Homebrew will prompt you to add the following to your .bash_profile:

Continue installing prerequisites:

And that's all -- you should be able to launch the Qt console by executing ipython qtconsole. If you want to see the matplotlib output inline (and why wouldn't you?), then execute:


We hope these instructions remove a common stumbling block for any data scientists getting started with scientific Python... and also those professionals who need a checklist for setting up new environments! After all, at some point we all start from square one.

9 Responses to “Installing scientific Python on Mac OS X”

  1. Why does the old page that links here ( ) say that python should be built with --framework and --universal but those flags are missing here? Are they the default now?


    • That's correct: the --universal flag is no longer needed due to improvements in Homebrew and the --framework flag is now enabled by default.


  2. Hi,

    I'm following this guide, and I found something that worked for me different that what you write. Installing python, and setting the correct value in .bash_profile on mountain lion. my line looks like

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

    Thanks for the guide!


  3. Hi -
    Thanks for the great writeup -- it works really well on Mountain Lion (ver. 10.8.3). I did have to execute this after getting to the end and updating the $PYTHONPATH:
    easy_install readline
    pip install matplotlib
    I'm not sure why they weren't already installed following your steps. In any case, executing those commands got everything in order so I could:
    ipython qtconsole --pylab=inline
    without errors.


  4. I had to add:
    brew install libpng

    before I could get matplotlib to compile. If you are getting an error that png is missing, give that a try. This is on mountain lion. hope that helps someone :)


  5. There is also an active solution, hosted on github, by Fonnesbeck:


  6. [...] several Macbook systems for scientific Python and there were enough gotchas to write this up. The excellent install post at Lowin Data Company is the latest successor to ‘This is the Green Room‘ for Mac Lion. [...]


  7. If you type in: which python
    and get something other than the path you said we should
    (i.e., /Library/Frameworks/Python.framework/Versions/2.7/bin/python)

    what is wrong and how do we fix it?


    • Hi Mike, you need to check your PATH settings -- most likely it hasn't been updated to reflect the new software. The system will search the PATH in order, accessing the first Python it comes across (reported by "which python"), so you'll need to make sure the new Python appears earlier on the PATH.


Leave a Reply

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">