How to run IPython on MacOSX

IPython is a very powerful and convenient Python console (alternative to standard Python interpreter) that makes every day tasks much easier. It also plays well with scientific libraries such as numpy and matplotlib making it the console of choice for almost every scientist.

The current version of IPython frontend (version 0.12) comes in three flavours:

  • standard text-based interpreter with line editing capabilities (including tab completion) that works in every terminal (for example in MacOSX),
  • Qt console for more advanced editing (for example, multiline editing and embedding of graphical output) and multiple tabs,
  • web-based notebook — this is a very recent frontend which allows one to run Mathematica-like notebook in a browser — great for demos and scripting.

I like having a copy of IPython Qt console running all the time for simple calculations or checking the docstrings when I program (normally I code in Vim and I do not use call tips). In order to make IPython quickly accessible it is convenient to put an IPython luncher in MacOSX Dock. A nice feature of Dock is that when you want to find a running instance of any application, you may simple click on its icon and if the window already exist it will be brought to the foreground.

Unfortunately, creating a Dock luncher for IPython is not easy. Basically, you have to create a new bundle (file-like directory) that contains all the application data. Here is the entire process step-by-step:

  1. First, you need to install IPython. I will use as an example Macport’s ipython, but after adapting some paths the procedure should work with any installation.
  2. In Finder create a directory named This will create a new bundle which is a special directory that contains application and all the related files. In order to open the directory, right-click the directory and select “Show package contents” (alternatively you may “cd” to the directory in your terminal). Create the following tree inside the directory:
  3. Using any text editor (such as Vim) create a new file with the same name as the package (without .app suffix, in our case IPythonQt) and the following contents:
    import os
    executable = '/opt/local/Library/Frameworks/Python.framework/Versions/2.6/bin/ipython'
    arguments = [executable, 'qtconsole', '--pylab']
    os.environ["PYTHONPATH"]=os.getenv("PYTHONPATH", "")
    os.execve(executable, arguments, os.environ)

    Change the paths at the top of the file and in executable variable to the paths of your python and ipython interpreter, respectively (you may check them in the terminal using which python and which ipython commands).

    Add the “executable” bit to the file and copy it to MacOS subdirectory of IPythonQt package created in the previous step:

    chmod +x IPythonQt
    cp IPythonQt
  4. If you also want to add an icon, you have to copy the icon .icns file (to be downloaded here, right click – Save As…) to the Resources subdirectory and add the following Info.plist file to the Contentssubdirectory:
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
    <plist version="1.0">

    At the end your package should look like this:

  5. If you double click on the directory in Finder an IPython Qt console should be opened. You can also copy the package to the Applications directory and drag it to your Dock so that it is always at hand. When you activate the luncher, a small dot will appear under the icon, which means that IPython is already open. Double-clicking the icon will bring the open window to the foreground.I hope that was helpful! If you have any questions please leave a comment below.

10 thoughts on “How to run IPython on MacOSX

  1. Felix says

    Hi, this is awesome. However, when using the edit magic command doesn’t work anymore. IPython acts as if it starts the editor, but my editor (TextWrangler) will neither start nor open a document if it’s already running. When I start ipython qtconsole via the terminal, everything is fine. I’m using ipython py27-ipython @0.12 from macports.

  2. Felix says

    Hi again, problem fixed. I just needed to set c.IPythonWidget.editor = ‘/usr/local/bin/edit’ in my instead of just setting it to ‘edit’. Could have thought of that before posting…

  3. Felix says

    Another tip: I added os.chdir(os.getenv(“HOME”)) to the file IPythonQt to start ipython in my home directory rather than /.

  4. Felix says

    Hi again,
    I just wanted to add, that missing some paths from os.environ[‘PATH’] caused some troubles. E.g. matplotlib did not work when using TeX. Therefore, I ended up putting the following code in my IPythonQt file. This also removes the necessity to specify absolute paths in the ipython config file (my earlier problem). I got the list of paths simply by typing echo $PATH into the terminal.

    # add possibly missing paths
    pathlist = [‘/usr/bin’, ‘/bin’, ‘/usr/sbin’, ‘/sbin’, ‘/usr/local/bin’, ‘/usr/X11/bin’, ‘/usr/texbin’]
    envpaths = os.environ[‘PATH’].split(os.pathsep)
    for p in pathlist:
    if not p in envpaths:
    os.environ[“PATH”] += os.pathsep + p

    I think that missing environment variables that are present when running the qtconsole from the terminal may be a common source of problems. Therefore it might be useful for others if you added a corresponding remark to your instructions above.

  5. mbs says

    Just wanted to thank you for a great tutorial. Now I know how to package other executables as well. Splendid

  6. Alex says

    I added os.chdir(os.getenv(“HOME”)) to the bottom of my IPythonQt file, and it wouldn’t start. Am I missing something? I want to make the start dir my Desktop.

Leave a Reply

Your email address will not be published. Required fields are marked *