Jupyter/IPython Notebook Quick Start
Guide Documentation
Release 0.1

Antonino Ingargiola and other contributors

Feb 13, 2018

Contents1

Contents

3i

ii

Jupyter/IPython Notebook Quick Start Guide Documentation, Release 0.1

This document is a brief step-by-step tutorial on installing and running Jupyter (IPython) notebooks on local computerfor new users who have no familiarity with python.
Briefly, if someone gave you a notebook to run and you don’t know what a notebook is, this document is for you.
Jupyter Notebook App (formerly IPython Notebook) is an application running inside the browser. This guidedescribes how to install and use Jupyter Notebook App as normal desktop application, without using any remoteserver.
For other use-cases, please refer to the Official Jupyter Documentation.

Contents1

Jupyter/IPython Notebook Quick Start Guide Documentation, Release 0.1

2

Contents

CHAPTER

1Contents

1.1 What is the Jupyter Notebook?
In this page briefly introduce the main components of the Jupyter Notebook environment. For a more completeoverview see References.
Contents• What is the Jupyter Notebook?
– Notebook document– Jupyter Notebook App– kernel– Notebook Dashboard– References

1.1.1 Notebook document
Notebook documents (or “notebooks”, all lower case) are documents produced by the Jupyter Notebook App, whichcontain both computer code (e.g. python) and rich text elements (paragraph, equations, figures, links, etc. . . ). Notebook documents are both human-readable documents containing the analysis description and the results (figures,tables, etc..) as well as executable documents which can be run to perform data analysis.
References: Notebook documents in the project homepage and in the official docs.

3

Jupyter/IPython Notebook Quick Start Guide Documentation, Release 0.1

1.1.2 Jupyter Notebook App
The Jupyter Notebook App is a server-client application that allows editing and running notebook documents via a webbrowser. The Jupyter Notebook App can be executed on a local desktop requiring no internet access (as described inthis document) or can be installed on a remote server and accessed through the internet.
In addition to displaying/editing/running notebook documents, the Jupyter Notebook App has a “Dashboard” (Notebook Dashboard), a “control panel” showing local files and allowing to open notebook documents or shutting down
their kernels.
References: Jupyter Notebook App in the project homepage and in the official docs.

1.1.3 kernel
A notebook kernel is a “computational engine” that executes the code contained in a Notebook document. The ipython
kernel, referenced in this guide, executes python code. Kernels for many other languages exist (official kernels).
When you open a Notebook document, the associated kernel is automatically launched. When the notebook is executed(either cell-by-cell or with menu Cell -> Run All), the kernel performs the computation and produces the results.
Depending on the type of computations, the kernel may consume significant CPU and RAM. Note that the RAM is
not released until the kernel is shut-down.
See also Close a notebook: kernel shut down.
References: from the official docs Opening Notebooks and Decoupled two-process model.

1.1.4 Notebook Dashboard
The Notebook Dashboard is the component which is shown first when you launch Jupyter Notebook App. The Notebook Dashboard is mainly used to open notebook documents, and to manage the running kernels (visualize and shutdown).
The Notebook Dashboard has other features similar to a file manager, namely navigating folders and renaming/deleting
files.
References: from the official docs Opening Notebooks.

1.1.5 References
Official Jupyter Project Pages:• Project Jupyter Homepage• Old IPython Notebook Homepage
Official Documentation:• Jupyter Notebook Documentation• Jupyter Project Documentation
See also:• What is the IPython Notebook?
• Notebook Basics, an example notebook• Introducing IPython Notebook• Jupyter Notebook: The Definitive Guide, an introductory tutorial to Jupyter
4Chapter 1. ContentsJupyter/IPython Notebook Quick Start Guide Documentation, Release 0.1

The Next button will bring you to the next section (Installation).

1.2 Installation
1.2.1 Step 0: The browser
Step “zero” consists in installing a modern standard-compliant browser. Either Mozilla Firefox or Google Chrome
will work well. Try to avoid MS Explorer.

1.2.2 Step 1: Installation
The easiest way to install the Jupyter Notebook App is installing a scientific python distribution which also includes
scientific python packages. The most common distribution is called Anaconda:• Download Anaconda Distribution (a few 100MB), Python 3, 64 bits.
• Install it using the default settings for a single user.
Official docs: Installation: If you are new to Python and Jupyter.

The Next button will bring you to the next section (Running Jupyter Notebook).

1.3 Running the Jupyter Notebook
1.3.1 Launching Jupyter Notebook App
The Jupyter Notebook App can be launched by clicking on the Jupyter Notebook icon installed by Anaconda in thestart menu (Windows) or by typing in a terminal (cmd on Windows):
jupyter notebookThis will launch a new browser window (or a new tab) showing the Notebook Dashboard, a sort of control panel thatallows (among other things) to select which notebook to open.
When started, the Jupyter Notebook App can access only files within its start-up folder (including any sub-folder). No
configuration is necessary if you place your notebooks in your home folder or subfolders. Otherwise, you need tochoose a Jupyter Notebook App start-up folder which will contain all the notebooks.
See below for platform-specific instructions on how to start Jupyter Notebook App in a specific folder.
Change Jupyter Notebook startup folder (Windows)• Copy the Jupyter Notebook launcher from the menu to the desktop.
• Right click on the new launcher and change the Target field, change %USERPROFILE% to the full path of thefolder which will contain all the notebooks.
• Double-click on the Jupyter Notebook desktop launcher (icon shows [IPy]) to start the Jupyter Notebook App.
The notebook interface will appear in a new browser window or tab. A secondary terminal window (used onlyfor error logging and for shut down) will be also opened.
1.2. Installation5

Jupyter/IPython Notebook Quick Start Guide Documentation, Release 0.1

Change Jupyter Notebook startup folder (Mac OS)
To launch Jupyter Notebook App:• Click on spotlight, type terminal to open a terminal window.
• Enter the startup folder by typing cd /some_folder_name.
• Type jupyter notebook to launch the Jupyter Notebook App The notebook interface will appear in a newbrowser window or tab.

1.3.2 Shut down the Jupyter Notebook App
Closing the browser (or the tab) will not close the Jupyter Notebook App. To completely shut it down you need toclose the associated terminal.
In more detail, the Jupyter Notebook App is a server that appears in your browser at a default address(http://localhost:8888). Closing the browser will not shut down the server. You can reopen the previous address
and the Jupyter Notebook App will be redisplayed.
You can run many copies of the Jupyter Notebook App and they will show up at a similar address (only the number
after “:”, which is the port, will increment for each new copy). Since with a single Jupyter Notebook App you canalready open many notebooks, we do not recommend running multiple copies of Jupyter Notebook App.

1.3.3 Close a notebook: kernel shut down
When a notebook is opened, its “computational engine” (called the kernel) is automatically started. Closing thenotebook browser tab, will not shut down the kernel, instead the kernel will keep running until is explicitly shut down.
To shut down a kernel, go to the associated notebook and click on menu File -> Close and Halt. Alternatively, theNotebook Dashboard has a tab named Running that shows all the running notebooks (i.e. kernels) and allows shutting
them down (by clicking on a Shutdown button).

1.3.4 Executing a notebook
Download the notebook you want to execute and put it in your notebook folder (or a sub-folder of it).
Then follow these steps:• Launch the Jupyter Notebook App (see previous section).
• In the Notebook Dashboard navigate to find the notebook: clicking on its name will open it in a new browser
tab.
• Click on the menu Help -> User Interface Tour for an overview of the Jupyter Notebook App user interface.
• You can run the notebook document step-by-step (one cell a time) by pressing shift + enter.
• You can run the whole notebook in a single step by clicking on the menu Cell -> Run All.
• To restart the kernel (i.e. the computational engine), click on the menu Kernel -> Restart. This can be useful tostart over a computation from scratch (e.g. variables are deleted, open files are closed, etc. . . ).
More information on editing a notebook:• Notebook Basics (or alternate link)

6Chapter 1. ContentsJupyter/IPython Notebook Quick Start Guide Documentation, Release 0.1

Note: Save notebooks: modifications to the notebooks are automatically saved every few minutes. To avoid modifying the original notebook, make a copy of the notebook document (menu File -> Make a copy . . . ) and save themodifications on the copy.

Warning: Pay attention to not open the same notebook document on many tabs: edits on different tabs canoverwrite each other! To be safe, make sure you open each notebook document in only one tab. If you accidentally
open a notebook twice in two different tabs, just close one of the tabs.
More info on the Jupyter Notebook App environment see References.
The Next button will bring you to the first item in the tables of content (What is Jupyter Notebook).

1.3. Running the Jupyter Notebook

7