Posted on by & filed under Content - Highlights and Reviews, Programming & Development.

code A guest post by Jonathan Frederic who is currently working as a full time IPython Developer. He works on the IPython Notebook and related tools, and enjoys spending his spare time writing a video game in Python. He can be contacted either by email at or on GitHub at

As a Physics undergraduate, I spent many weekends writing lab reports. I used a wide variety of tools including MatLab, Maple, and Excel. Although these tools were excellent for data analysis, they were either severely limited in or completely lacked the ability to create text documents. Because of this, I would spend hours moving and formatting data from these applications into my word processor. The IPython Notebook circumvents this issue by combining the word processor with the data analysis software. This tool provides users the ability to create content rich documents with embedded source code with very little effort.

In this first post of a three parter, I will show you how to download and install the IPython Notebook, how to create a notebook, and then how to share that notebook. This post requires a basic understanding of the Linux shell, and it was written and tested on Lubuntu 13.10.


The IPython Notebook is a component of IPython and is installed alongside IPython automatically. There are many different ways to install IPython. The officially supported methods can be found on IPython’s website at IPython can be installed on Linux, Macintosh, and Windows operating systems. Single click installers are available and listed in the officially supported methods.

There are, however, benefits to downloading and installing IPython from source. In my opinion, the greatest benefit is the ability to easily change the version of your installation. I will walk you through the process of downloading and installing IPython from scratch.

Step 1, Install Python

Most Linux distributions come with Python pre-installed. To check if your system has Python already installed, try reading the current Python version. This can be done using the system terminal:

IPython 1.1 supports Python 2.6,2 .7, 3.2, and 3.3. If your system doesn’t have Python installed, you can install it by running:

After Python is installed, you will need to install the Python setup tools and dev packages. This can be done by running the following commands in the system terminal:

Step 2, Installing IPython’s dependencies

IPython depends upon many open source packages. The notebook has additional dependencies. To install these, run the following in the system terminal:

Step 3, Download and install IPython

The IPython source code is available on GitHub. To download the source code, your system must have Git installed. To check if Git is already installed on your machine, run the following command in the system terminal:

If the command above returns an error, Git is not installed. You can install Git by running the following:

Now you are ready to download IPython. Navigate to the directory where you would like IPython installed. Once you are there, download IPython by running the following:

Git will create an /ipython subdirectory where all required files will reside. Once the download is complete, to begin the installation process, you must checkout the IPython version you want installed. This post targets version 1.1. You can checkout version 1.1 files by running the following:

Note: Other versions are available to checkout. To view the latest developer code, which includes the experimental features, checkout master (git checkout master).

To install IPython, run the following:

Step 4, Verify IPython installation

Depending upon the version of Python installed (see step 1), the command used to launch the software differs. If Python 3.x is installed, the command to launch any IPython application is suffixed with a 3. If you have Python 2.x installed, the commands are not suffixed.

Verify that the test suite executes without any errors. Run the test suite by using the following:


Using the Notebook

Now that IPython is installed, you will have to identify where you would like the notebooks you create to be saved. Navigate to that directory and launch the IPython Notebook. To launch the notebook, run the following:


The IPython Notebook dashboard will launch inside your default web browser. The page will resemble the screenshot below.


Create a notebook by clicking the New Notebook button. The new notebook will resemble the screenshot below. Change the title of the notebook to “Tutorial1” by left clicking on “Untitled0” at the top of the page.


The notebook is composed of cells. Every cell has a unique purpose depending upon its type. Each cell in the notebook is a Python code-cell by default. To change the type of the cell, use the first dropdown box in the toolbar (as seen below).

Highlight the first cell by clicking on it. From the dropdown select Heading 1. This will change the highlighted cell type to a level 1 header. Press Shift+Enter to execute the current cell and move to the next one. If no cell exists below the current one, a new cell will be created. To insert a cell above or below the current cell, use the Insert menu.


Change the next cell to a “Markdown” cell type. This type is used to create rich text in the notebook (as seen below). To learn more about the Markdown syntax, visit

Note: IPython supports a rich variation of Markdown. This variation allows latex equations to be entered directly into the markdown.


Pressing Shift+Enter will render the markdown (as seen below).


IPython has a set of magic commands that help the interactive programming process. Magic commands are prefixed with a single or double percent symbol. The pylab magic command automatically configures Python for plotting. Use the pylab magic command by entering the following into a code cell:

Execute the cell and the pylab magic will run. In another code cell, add and execute the following Python code to plot a segment of the sine function:

The results will resemble the screenshot below.


Sharing your Notebook

There are many methods to share your notebooks. The two most common methods are to: use IPython’s nbconvert to export the notebook as a redistributable format (one that can be rendered without IPython) or to upload and view it using IPython’s nbviewer.

Exporting a Notebook

Nbconvert can be used to export your newly created “Tutorial1” notebook to an HTML document. To do this, first open a terminal window and navigate to the directory where “Tutorial1” is saved. From this window, export the notebook by running the following command:


An HTML file will be created with the name “Tutorial1.html”. Opening the HTML file in a web browser will yield the Tutorial1 notebook as shown below.


Sharing a notebook online without exporting it

Nbviewer can be used to view notebooks stored online. To store your notebook online, you can use GitHub’s gist service by navigating to (as seen below).


Once on this page, drag and drop the notebook file onto the largest textbox. Next click on the “Create Public Gist” button (at the bottom of the page) to create the following view:


Note: Do not use the Create Private Gist function. This does not work with nbviewer.

The web page address can be rendered using nbviewer. This can be done by copying the address into the textbox on and clicking the “Go!” button. A static rendering of the notebook, as seen below, will be displayed. The address generated by nbviewer can be shared with anyone. People viewing your notebook do not need a GitHub account.



Now that you have downloaded and installed the IPython Notebook and explored it a bit, be sure to look for the second post where I will show how you can customize the notebook and nbconvert by writing a custom plugin. Then, in the final post of this series, I will illustrate how to apply custom formatting to notebooks.

See below for IPython resources from Safari Books Online.

Not a subscriber? Sign up for a free trial.

Safari Books Online has the content you need

Mining the Social Web, 2nd Edition combines popular and useful social web data with analysis techniques and visualization to help you find the needles in the social haystack that you’ve been looking for—as well as many you probably didn’t even know existed. You’ll also find an appendix that covers IPython Notebook tips and tricks.
Learning IPython for Interactive Computing and Data Visualization covers all aspects of IPython, from the highly powerful interactive Python console to the numerical and visualization features that are commonly associated with IPython.
Practical Data Analysis is a hands-on guide to understanding the nature of your data and turn it into insight. It will introduce you to the use of machine learning techniques, social networks analytics, and econometrics to help your clients get insights about the pool of data they have at hand. Performing data preparation and processing over several kinds of data such as text, images, graphs, documents, and time series will also be covered, and covers the IPython Notebook.

Tags: gist, git, Github, IPython, IPython Notebook, linux, Lubuntu, Nbconvert,

Comments are closed.