Installing the IPython qtconsole in Mac OS X

patricksurry edited this page May 1, 2013 · 17 revisions
Clone this wiki locally

Installing qtconsole for the new IPython 0.11 to work in Mac OS X is quite cumbersome. The following guide will help you in installing qtconsole for IPython on Mac OS X Lion. It will also work for newer versions of IPython.

  1. First, make sure that you do everything with the latest version of the system Python. This should be /Library/Frameworks/Python.framework/Versions/2.7/bin/python2.7.

    Make sure that this is 64-bit. You can check this by running

    print '32-bit' if isinstance(int(2**42), long) else '64-bit'

    in Python. You can also just run python -c "print '32-bit' if isinstance(int(2**42), long) else '64-bit'". If it isn't 64-bit, download the 10.6/10.7 installer at

  2. Now, you need to install IPython. A simple pip install ipython or easy_install ipython should do it. Alternately, you can download the source, or clone the git repo and install from that.

    Now, you have the new IPython. It will work with the terminal out of the box. You may want to play around with the new configuration (it should tell you about this the first time you start IPython).

    To get the qtconsole, you need to install some dependencies.

  3. First, you will need Xcode to compile some stuff. In Lion, just install it from the App store (note, this installs an installer, which you then need to run). I used Xcode 4, but this might also work with Xcode 3.

[patricksurry: FWIW, I used macports to install ipython in the first place (sudo port install py27-ipython), and then following your hints here I just needed to do "sudo port install py27-pyqt4" followed by "sudo port install py27-pygments" and qtconsole started working. I did have Xcode installed from the app store first.]

  1. Next, you need to install Qt. Install the Qt Library (not the SDK) for Mac OS X from If you installed the right one, there should now be a Qt folder in /Developer/Applications.

  2. Here is the hard part: pyqt. Don't even try compiling this yourself; it won't work (or at least that's what I've been told; I haven't tried it since a few months ago when I was using Mac OS X 10.6, when it didn't work). You want to rather use homebrew to compile it for you (alternately, you can try manually applying the homebrew formula for it; I haven't tried this myself).

    Install homebrew by running

    /usr/bin/ruby -e "$(curl -fsSL"

    (see This will guide you to do some stuff. If you have fink or macports installed, it will warn you. I have fink installed, and this all worked.

  3. Now, install pyqt by running brew install pyqt. Make sure you extend your PATH as it tells you, or else Python won't be able to find it. I am stuck at this stage. I did not see where brew told me how to extend the path and, indeed, it seems like python is not funding qtconsole. Can you tell me how to get the required change to the PATH now that pyqt is already installed?

Test that you have done this right so far by running

$ ipython qtconsole

If you did it right, it should tell you you need pyzmq.  If it tells you you need pyside or pyqt, you didn't install pyqt correctly.

Now, to get pyzmq.
  1. First, install zeromq. I compiled this from the master of the git repository. The tarball from should work too. I think you need version 2, not 3.

    Compile this using

    ./ # you may not need this one if you use the tarball
    make check
    sudo make install

    Note that I had some errors when I did make check, but it doesn't seem to be a problem.

    You can also use homebrew. Do brew install zeromq --universal. I didn't do this, so I can't say if it works, though it should.

    7a. Supposedly, easy_install pyzmq will install both zeromq and pyzmq, so you can do that instead of this and the next step. I didn't do this, though, so I can't personally verify this.

  2. Now, get pyzmq. Again, you can go tarball or git. pip won't work because it builds from source and you need to specify the zmq path when you build (but you can try it). easy_install might work. They didn't for me, though, which is why I installed it from git.

    8a. Note, if you use git, you will first need to install cython (you might as well use git for this too).

    To build pyzmq, do sudo python install --zmq="/usr/local".

  3. Now you need Pygments. Otherwise you will get "ImportError: No module named pygments.lexers" when invoking "ipython qtconsole". This can be done simply by pip:

    $ pip install pygments
  4. If you did this all right, you should now be able to use the qtconsole. Try

    $ ipython qtconsole

    If it works, the Python rocketship application should open, and a GUI window with a IPython shell should open up. This is the qtconsole!


  • ./ clean doesn't work very well in most repositories (such as IPython). If you are using git, you can clean everything better using git clean -Xdn first (this is a dry run), and then git clean -Xdf if you are OK with what it will delete.

  • If you use fink, or for whatever reason have some other version of Python from the system one in your PATH, make sure you always explicitly call /Library/Frameworks/Python.framework/Versions/2.7/bin/python2.7 in all the install steps. If you installed something but it still can't find it, this is likely the culprit. Do a hard clean (see above) and try again.

  • To use the qtconsole with SymPy, run ipython qtconsole --profile=sympy. This makes the qtconsole run similar to isympy. It's also supposed to use LaTeX for the math, though this hasn't been the case for me. See below for how to make LaTeX printing work.

  • This is all just how I did it. Hopefully I didn't forget anything. Your milage may vary.

Getting LaTeX printing for SymPy

To get LaTeX printing for SymPy, you need matplotlib. This in turn requires numpy. So do

  1. sudo pip install numpy

  2. sudo pip install matplotlib did not work for me. Rather, I had to clone the git repo and install from that

git clone git://
cd matplotlib
sudo python install

You can test that the latex printing works by first cd'ing out of the matplotlib directory, and doing

ipython qtconsole --profile=sympy

and then typing something like

Integral(sin(1/x), x)

If this works, you should see something like

[\int \sin\left(\frac{1}{x}\right),dx]

(only it will look bad because matplotlib LaTeX rendering isn't good).