Complaints about Installing IPython Notebok

For the Mac user, installing ipynb is nontrivial. The software depends on a series of packages which must be installed in the correct order. I have heard that the installation process for PC and Linux users is relatively easy (one click, or guided by an install wizard). But I am a Mac user, and I have spent an extensive amount of time trying to get ipynb installed. After fighting with the install for days, I finally found a method that uses MacPorts and works well (reliably). I documented my process here for future users.

I want to state that I am a second-year PhD-track graduate student at Michigan State University with a Bachelor’s in Computer Science, and I still found this process very tedious, and at times baffling. It wasn’t until my adviser and I sat down for an hour and worked on the install together that I was finally able to get ipynb working.

Now, to talk about why the install was difficult. Please note that this post is a series of complaints, and should not at all be followed as an installation tutorial.



(1) Getting a C Compiler

There is no default C compiler installed on new Macs. Instead, you have to get a copy of X-Code and install a C compiler through the preferences (which requires an Apple developer user ID), or find a package that specifically installs a C compiler on a Mac.

(2) Python Versions

Next, I encountered a serious problem with using different versions of Python and being unclear about which ipynb I am installing. The existing tutorial for installing ipynb simply states that a user should run this line at the terminal:

$ easy_install ipython[zmq,qtconsole,notebook,test]

But, there are actually different easy_install commands for each version of Python you have installed on your computer. If you want to install a specific version of ipynb, you must use the correct easy_install command. In my case, I want easy_install-2.7 to get IPython Notebook for Python 2.7.

(3) Quickstart? The IPy Tutorial

Once you figure out which easy_install you need to use, the tutorial states that the install will be quick:

But…my experience was not quick at all:

So, I googled the error I got, and found this fix, which did install ipynb:

$ sudo easy_install-2.7 -U ipython

Or so I thought. When I try running ipynb, I got this problem:

ImportError: IPython.zmq requires pyzmq >= 2.1.4

(4) Finding the Packages

So, I think that means that I don’t have the packages that ipynb is built upon. The tutorial online doesn’t show how to install the dependencies, so I was winging it for the majority of that – including figuring out why I didn’t have a default C compiler installed on my Mac.

$ sudo easy_install-2.7 pyzmq

Oddly, after that install happened, the error message about not having pyzmq did not go away. I also tried installing tornado:

$ sudo easy_install-2.7 tornado

And, it appears that I need pygments:

$ sudo easy_install-2.7 pygments

And, PyQt, which is not easy_install-able and must be downloaded here – maybe? But first, PyQt needs the SIP package, available for download from the same site. There is a nice, detailed description of the install process here, but it is for Windows users. After a lot of searching, I finally realized that this download is what Mac OS X users need. Thank goodness someone made that available! Unfortunately, the links pointing to it are not clear at all. I really had high hopes for this install wizard, but…

Well, now I’m really just hitting a wall. This was about the point that I turned to my adviser for assistance.

(5) Screw it. Use MacPorts.

Bill then suggested that I get MacPorts. MacPorts is a package manager for installing open source software on a Mac. Had I known this existed, I would have started here in the first place. It makes the install really easy and quick in comparison – only about an hour’s process. First, it requires that you download and install MacPorts. But, MacPorts maintains its own directories of open source software – separate from the typical places software installs itself. That means that I needed an altogether new version of Python 2.7 on my computer installed via MacPorts in the correct directory, as well as the package dependencies which IPython requires…before I go anywhere near installing ipynb.

(6) Changing the .bash_profile file

Finally, though, Bill and I executed the steps in my tutorial here and were able to get ipynb running successfully on my machine. With one exception, of course. We had to modify the path file (called .bash_profile for OS X), so that it would look in the MacPorts directory properly for the ipynb files.



When all is said and done, I have spent countless hours on this install project. If I were an undergrad who just wanted ipynb installed for using in a class, I would have probably given up ages ago. I also would have developed a deep hatred for the software because of all the problems it caused me. Since I am a fan of Python and excited for new ways to integrate ipynb in my teaching, however, I can’t really the software itself. But, we cannot expect the average user to have that sort of perseverance and commitment to ipynb.

What do we need, then? An easy (actually easy, not just easy_install) way to distribute ipynb and *all* of its dependencies for Mac users. A package, perhaps?


One thought on “Complaints about Installing IPython Notebok

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s