An introduction to the Jupyther Notebook (formerly known as IPython notebook)

In [1]:
import addutils.toc ; addutils.toc.js(ipy_notebook=True)
In [2]:
from addutils import css_notebook

1 Before starting...

The Jupyter Notebook is an interactive computing environment that enables users to author notebook documents that include:

  • Live code
  • Interactive widgets
  • Plots
  • Narrative text
  • Equations
  • Images
  • Video

These documents provide a complete and self-contained record of a computation that can be converted to various formats and shared with others using email, Dropbox, version control systems (like git/GitHub) or

To find more documentation and examples check the follwing links:

The document you are reading now is precisely an example of one such notebook, and we will show you here how to best use this new interface. The first thing to understand is that a notebook consists of a sequence of 'cells' that can contain either text or code meant for execution:

  • Text cells can be written using Markdown syntax (in a future release there will be support for reStructuredText and Sphinx integration).
  • Code cells take IPython input (i.e. Python code, %magics, !system calls, etc). When you type Shift-Enter, the cell content is executed, output displayed and a new cell is created below. Try it now by putting your cursor on the next cell and typing Shift-Enter:
In [3]:
print ('This is the new IPython notebook')
This is the new IPython notebook

You can re-execute the same cell over and over as many times as you want. Simply put your cursor in the cell again, edit at will, and type Shift-Enter to execute.

Tip: A cell can also be executed in-place, where IPython executes its content but leaves the cursor in the same cell. This is done by typing Ctrl-Enter instead, and is useful if you want to quickly run a command to check something before typing the real content you want to leave in the cell. For example, in the next cell, try issuing several system commands in-place with Ctrl-Enter, such as pwd and then ls:

In [4]:

In a cell, you can type anything from a single python expression to an arbitrarily long amount of code (although for reasons of readability, you should probably limit this to a few dozen lines):

In [5]:
def f(x):
    '''My function description'''
    return x+6

value = 3
print ('f({0:.2f})= {0:.2f}'.format(value, f(value)))
f(3.00)= 3.00

1.1 Kernels

The Notebook allows code to be run in a range of different programming languages. For each notebook document that a user opens, the web application starts a kernel that runs the code for that notebook. Each kernel is capable of running code in a single programming language and there are kernels available in the following languages:

The default kernel runs Python code. The notebook provides a simple way for users to pick which of these kernels is used for a given notebook.

Each of these kernels communicate with the notebook web application and web browser using a JSON over ZeroMQ/WebSockets message protocol.

2 User interface

When you start a new notebook server with ipython notebook, your browser should open into the Dashboard, a page listing all notebooks available in the current directory, which allow to create new notebooks. In this page, you can also drag and drop existing .py files over the file list to import them as notebooks (see the manual for further details on how these files are interpreted).

Once you open an existing notebook (like this one) or create a new one, you are in the main notebook interface, which consists of a main editing area (where these cells are contained) as well as a menu and permanent header area at the top, and a pager that rises from the bottom when needed and can be collapsed again.

2.1 Main editing area

Here, you can move with the arrow keys or use the scroll bars. The cursor enters code cells immediately, but only selects text (markdown) cells without entering them; to enter a text cell, use Enter (or double-click), and Shift-Enter to exit it again (just like executing a code cell).

2.2 Menu

The menu bar contains all the commands you can use to manipulate the notebook.

  • The File menu has the usual open/save file operations, as well as Export, for downloading the notebook to your computer.
  • Edit has controls for cut/copy/paste.
  • View lets you toggle visibility of the header elements.
  • The Cell menu lets you manipulate individual cells.
  • The Kernel menu lets you signal the kernel executing your code. Interrupt stops the running computation while Restart fully kills the kernel and starts a fresh one. Obviously this means that all your previous variables are destroyed, but it also makes it easy to get a fresh kernel in which to re-execute a notebook, perhaps after changing an extension module for which Python's reload mechanism does not work.
  • The Help menu contains links to the documentation of some projects closely related to IPython as well as the minimal keybindings you need to know. You should use Ctrl-m h (or click the QuickHelp button at the top) to show keybindings.
  • You will also see a few buttons there for common actions, and hovering over each button will tell you which command they correspond to, if the icons are not clear enough.

2.3 Help and Keyboard Shortcuts

Go to Help -> Keyboard Shortcuts to see the complete shortcuts list

To access the help system symply type help() in a code cell. Use quit to finish:

In [6]:
Welcome to Python 3.6's help utility!

If this is your first time using Python, you should definitely check out
the tutorial on the Internet at

Enter the name of any module, keyword, or topic to get help on writing
Python programs and using Python modules.  To quit this help utility and
return to the interpreter, just type "quit".

To get a list of available modules, keywords, symbols, or topics, type
"modules", "keywords", "symbols", or "topics".  Each module also comes
with a one-line summary of what it does; to list the modules whose name
or summary contain a given string such as "spam", type "modules spam".


You are now leaving help and returning to the Python interpreter.
If you want to ask for help on a particular object directly from the
interpreter, you can type "help(object)".  Executing "help('string')"
has the same effect as typing a particular string at the help> prompt.

2.4 Header bar

The header area at the top allows you to rename an existing notebook. This area also indicates whenever the kernel is busy executing code.

2.5 The pager at the bottom

Whenever IPython needs to display additional information, such as when you type somefunction? in a cell, the notebook opens a pane at the bottom. You can keep this pager pane open for reference (it doesn't block input in the main area) or dismiss it by clicking on its divider bar. Try this:

In [7]:

3 Tab completion and tooltips

Whey you complete with the Tab key, IPython shows a drop list with all available completions. If you type more characters while this list is open, IPython automatically refines the search; once there is only one option left you can hit Tab once more (or Enter) to complete. You can also select the completion you want with the arrow keys or the mouse, and then hit Enter.

In addition, if you hit Tab inside of open parentheses, IPython will search for the docstring of the last object left of the parens and will display it on a tooltip. For example, type list(<TAB> and you will see the docstring for the builtin list constructor. Moreover, pressing tab several time in a row allows you change the behaviour of the tooltip:

In [8]:
# Remove comment, then position your cursor after the ( and hit the Tab key:

4 Plotting support

You can enable inline plotting with %pylab inline:

In [9]:
import numpy as np
import bokeh.plotting as bk
Loading BokehJS ...
In [10]:
# NOTICE: In Jupyter and Python3 you can use UNICODE identifiers as variable names.
#         Example: just type \alpha and press <TAB>
β = np.linspace(0, 3*np.pi, 700)
fig = bk.figure(title="A simple Chirp",
                plot_width = 700, plot_height = 300)
fig.line(β, np.sin(β**2), line_width=2, line_color='magenta')

5 Interactive Widgets

IPython comes with basic widgets that represent common interactive controls.

5.1 Plot controlled by Widgets

In [11]:
import ipywidgets
from ipywidgets import interact

# Here "interact" is used as a decorator:
@interact(n=(2.0,30.0), lw=(0.5, 10.0, 0.5), c=(['blue', 'green', 'red']))
def edit_myplot(n=2.0, lw=1.0, c='blue'):
    fig = bk.figure(title="An interactive Chirp",
                    plot_width = 700, plot_height = 300)
    fig.line(β, np.sin(β**n), line_width=lw, line_color=c)

5.2 Factorization Example using Interactive Widgets and SimPy

In [12]:
from IPython.display import display
from sympy import Symbol, Eq, factor, init_printing
In [13]:
def factorit(n):
    x = Symbol('x')
    display(Eq(x**n-1, factor(x**n-1)))
In [14]:
interact(factorit, n=(2,60));

6 Markdown cells can contain formatted text and code

You can italicize, boldface or typewrite text

  • build
  • lists

and embed code meant for illustration instead of execution in Python:

def f(x):
    """a docstring"""
    return x**2

or other languages:

if (i=0; i<n; i++) {
  printf("hello %d\n", i);
  x += 4;

Courtesy of MathJax, you can include mathematical expressions both inline: $e^{i\pi} + 1 = 0$ and displayed:

$$ {\partial{\bf u}\over{\partial t}} + ({\bf u} \cdot \nabla) {\bf u} = - {1\over\rho} \nabla p + \gamma\nabla^2{\bf u} + {1\over\rho}{\bf F} $$

7 Rich display: include anything a browser can show

Note that we have an actual protocol for this, see the display_protocol notebook for further details.

7.1 Videos

In [15]:
# Video credit: Fernando Pérez, Brian E. Granger, Min Ragan-Kelley
from IPython.display import YouTubeVideo
YouTubeVideo('Rc4JQWowG5I', width=800, height=420)

7.2 External Websites

You can even embed an entire page from another site in an iframe; for example this is today's Wikipedia page for mobile users:

In [16]:
from IPython.display import HTML
HTML('<iframe src="" width=800 height=350>')