Introduction to iPython Notebook

“ At first sight I was awed and amazed that something like it existed. It was like the perfect interpreter. Markdown documentation, code blocks, autocomplete, what else can a developer ever need? ”

Introduction to iPython Notebook


When I first started interning at Sotera I was introduced to the iPython Notebook. At first sight I was awed and amazed that something like it existed. It was like the perfect interpreter. Markdown documentation, code blocks, autocomplete, what else can a developer ever need? (maybe git integration) but I’m sure there’s an plugin for that too.

How to install…

The same person also told me that it’s a pain in the a$$ to install and the best way to get it working was using Contiuum’s Anaconda package. It’ll probably ask for your email address, but I haven’t really received much spam from them, I don’t think it even needs to be correct. The packages come in 2 different flavors, Python 2.4 and Python 3.4 so choose accordingly. If you have both, you’ll just have to install them into seperate directories.

Anaconda Installation Succesful

Once you download the PKG file, just open and install it. Then open up the terminal.

$ python --version
Python 3.4.3 :: Anaconda 2.2.0 (x86_64)
$ ipython --version

Ready to Rock!

To startup the iPython Notebook execute , there are optional parameters like –notebook-dir=~\notebooks where you can specify the Notebooks folder. By default the first page that opens will be the terminal’s current working directory.

$ ipython notebook

In a brand new folder the page will look lonely, so let’s try to create a new one.

There are two ways to execute the script control+Enter or pressing the Play arrow up top.

Exceptions Finished

Okay to take advantage of the notebook let’s divide the script into multiple code blocks. Scroll to the bottom, click on the last line, and hit Option+Enter to create a new code block. Notice the In [ ]: indicates code blocks and the number within the number of times it has been executed. Let’s copy and paste the print message and execute it. It prints!

Also notice the top blocks haven’t changed and we can still see the Done. right above. That indicated the blocks do not evaluate on their own… Let’s try to re-evaluate the top block again with control+Enter. Boom, no more Done.

Previous Done

The cool parts

Let’s divide the document into multiple code blocks. I pretty much ended up seperating the initialization code, exception 1, exception 2, and asserts. Now we can move one by one and execute the blocks.

Beginning with block one, we were told it won’t raise an exception and it didn’t. Let’s try changing the False to True, just to experience the result.

ExceptionStack trace.

So now it failed, with a pretty heavy stack trace. Good thing we chunked our code and we actually have a pretty good understanding where it failed. Change it back to False and control+Enter. The stack trace disappears.

Same story happens with block number 2. Try running the block with control+Enter the code block is executed without any problems. Change up True to False, and we get a pretty nice AssertionError once again.

If you by accident press option+Enter and create a new cell, you can delete it by clicking on the scissors up on the main toolbar.

Another wonderful feature of iPython Notebooks is the documentation, create a new cell at the very beginning and convert it to Markdown. The In[]: will dissapear and type in:


Exceptions rendered

Just like regular cells execute the markdown cell with control+Enter. It will render the Markdown. To change it again just double click the cell.

Saving your Notebook

On the top bar click on untitled and name the notebook Exceptions. By default the notebook will be saved in the working directory where python notebook was executed. To return click on the jupyter logo.title

For sharing the Notebooks we have two options.

  • Gist – just dump the Python Notebooks for the fun of it.
  • Github Repository – you actually want to use git version control.
    • The Github Repositories will actually render the ipynb files.Screen Shot 2015-06-18 at 9.57.26 PM

Open the Notebook file with a text editor.
Choose your favorite editor

If you don’t know where it was saved, just go to the terminal.

$ open .
  • Open up the browser and head to Github’s Gist.
  • Click on the + on the top bar to open a new Gist.
  • Add a description “Sharing the amazing Exceptions file!”
  • Name this file…. call it Exceptions.
  • Paste the contents of the Notebook file.
  • Click Create public Gist.
  • Now the part you need from this page will be in the URL The last identifier is called the Gist id and that’s what needs to be copied.
  • On the right side of the page we can also copy the URL by clicking the clipboard.title

Viewing Notebooks using nbViewer

Now go to nbViewer page and either

  • Paste in the Gist id.
  • Or the Github username if the Notebookis located in a publicGithub repository.
    • Try marek5050/Notebooks and selecting one, maybe Factorials.ipynb.

The notebook will render within the browser and in the top right corner we have a couple of options. To Download the Notebook and to visit the Github/Gist page.

  • There’s a way to make the public Notebooks renderable without downloading, just haven’t tried it yet, that would probably be the third button.

Loading Python Notebooks from the Web

Up top I linked a couple of awesome resources and collections of notebooks. I’ll just walk you through loading one.

  • Download the Notebooks using the terminal in one of the following ways.
    • $ wget –no-check-certificate
      $ ipython notebook
    • $ git clone
      $ cd Notebooks
      $ ipython notebook
  • This will spin up the iPython Notebook server and you should be able to see the files.
  • Open up timeseries.ipynb.
  • Now execute the first cell.BokehJS Loaded
  • Execute the next cell..
    TimeSeries Second Cell
  • and the next.TimeSeries Last Cell
  • Remember that cells might depend on the preceding cells.
  • So it might not be possible to just jump to the last one and execute it.

Problem #1:

If you already have Python feel free to download it anyways, this package will probably be more use in the future.

Problem #2:

I already installed Anaconda with Python 2.4 and want to update to 3.4.
So Anaconda will try and install into the ~/anaconda directory, just change it to ~/anaconda2 and it’ll install fine.

Installation error previous version of Anaconda.
Changing the installation directory

Then you can just ln -s ~/anaconda2/bin/python /etc/bin/python3
to create a symbolic link to the updated python.


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