The author selected the Apache Software Foundation to receive a $100 donation as part of the Write for DOnations program.

Introduction

Jupyter Notebook is an open-source, interactive web application that allows you to write and run computer code in more than 40 programming languages, including Python, R, Julia, and Scala. A product from Project Jupyter, Jupyter Notebook is useful for iterative coding as it allows you to write a small snippet of code, run it, and return the result.

Jupyter Notebook provides the ability to create notebook documents, referred to simply as "notebooks". Notebooks created from the Jupyter Notebook are shareable, reproducible research documents which include rich text elements, equations, code and their outputs (figures, tables, interactive plots). Notebooks can also be exported into raw code files, HTML or PDF documents, or used to create interactive slideshows or web pages.

This article will walk you through how to install and configure the Jupyter Notebook application on an Ubuntu 18.04 web server and how to connect to it from your local computer. Additionally, we will also go over how to use Jupyter Notebook to run some example Python code.

Prerequisites

To complete this tutorial, you will need:

• One Ubuntu 18.04 server instance. This server must have a non-root user with sudo privileges and a firewall configured. Set this up by following our initial server setup guide.
• Python 3, pip, and the Python venv module installed on the server. Do this by following Steps 1 and 2 of our tutorial on How To Install Python 3 and Set Up a Local Programming Environment on Ubuntu 18.04.
• A modern web browser running on your local computer which you will use to access Jupyter Notebook.

Additionally, if your local computer is running Windows, you will need to install PuTTY on it in order to establish an SSH tunnel to your server. Follow our guide on How to Create SSH Keys with PuTTY on Windows to download and install PuTTY.

Step 1 — Installing Jupyter Notebook

Since notebooks are used to write, run and see the result of small snippets of code, you will first need to set up the programming language support. Jupyter Notebook uses a language-specific kernel, a computer program that runs and introspects code. Jupyter Notebook has many kernels in different languages, the default being IPython. In this tutorial, you will set up Jupyter Notebook to run Python code through the IPython kernel.

Assuming that you followed the tutorials linked in the Prerequisites section, you should have Python 3, pip and a virtual environment installed. The examples in this guide follow the convention used in the prerequisite tutorial on installing Python 3, which names the virtual environment "my_env", but you should feel free to rename it.

Begin by activating the virtual environment:

source my_env/bin/activate

Following this, your prompt will be prefixed with the name of your environment.

Now that you're in your virtual environment, go ahead and install Jupyter Notebook:

python3 -m pip install jupyter

If the installation was successful, you will see an output similar to the following:

Output
. . .
Successfully installed MarkupSafe-1.0 Send2Trash-1.5.0 backcall-0.1.0 bleach-2.1.3 decorator-4.3.0 entrypoints-0.2.3 html5lib-1.0.1 ipykernel-4.8.2 ipython-6.4.0 ipython-genutils-0.2.0 ipywidgets-7.2.1 jedi-0.12.0 jinja2-2.10 jsonschema-2.6.0 jupyter-1.0.0 jupyter-client-5.2.3 jupyter-console-5.2.0 jupyter-core-4.4.0 mistune-0.8.3 nbconvert-5.3.1 nbformat-4.4.0 notebook-5.5.0 pandocfilters-1.4.2 parso-0.2.0 pexpect-4.5.0 pickleshare-0.7.4 prompt-toolkit-1.0.15 ptyprocess-0.5.2 pygments-2.2.0 python-dateutil-2.7.3 pyzmq-17.0.0 qtconsole-4.3.1 simplegeneric-0.8.1 six-1.11.0 terminado-0.8.1 testpath-0.3.1 tornado-5.0.2

With that, Jupyter Notebook has been installed onto your server. Next, we will go over how to run the application.

Step 2 — Running the Jupyter Notebook

Jupyter Notebook must be run from your VPS so that you can connect to it from your local machine using an SSH Tunnel and your favorite web browser.

To run the Jupyter Notebook server, enter the following command:

jupyter notebook

After running this command, you will see output similar to the following:

Output
[I 19:46:22.031 NotebookApp] Writing notebook server cookie secret to /home/sammy/.local/share/jupyter/runtime/notebook_cookie_secret
[I 19:46:22.365 NotebookApp] Serving notebooks from local directory: /home/sammy/environments
[I 19:46:22.365 NotebookApp] 0 active kernels
[I 19:46:22.366 NotebookApp] The Jupyter Notebook is running at:
[I 19:46:22.366 NotebookApp] http://localhost:8888/?token=Example_Jupyter_Token_3cadb8b8b7005d9a46ca4d6675
[I 19:46:22.366 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[W 19:46:22.366 NotebookApp] No web browser found: could not locate runnable browser.
[C 19:46:22.367 NotebookApp]

    Copy/paste this URL into your browser when you connect for the first time,
    to login with a token:
        http://localhost:8888/?token=Example_Jupyter_Token_3cadb8b8b7005d9a46ca4d6675&tokenExample_Jupyter_Token_3cadb8b8b7005d9a46ca4d6675

You might notice in the output that there is a No web browser found warning. This is to be expected, since the application is running on a server and you likely haven't installed a web browser onto it. This guide will go over how to connect to the Notebook on the server using SSH tunneling in the next section.

For now, exit the Jupyter Notebook by pressing CTRL+C followed by y, and then pressing ENTER to confirm:

Output
Shutdown this notebook server (y/[n])? y
[C 20:05:47.654 NotebookApp] Shutdown confirmed
[I 20:05:47.654 NotebookApp] Shutting down 0 kernels

Then log out of the server by using the exit command:

exit

You've just run Jupyter Notebook on your server. However, in order to access the application and start working with notebooks, you'll need to connect to the application using SSH tunneling and a web browser on your local computer.

Step 3 — Connecting to the Jupyter Notebook Application with SSH Tunneling

SSH tunneling is a simple and fast way to connect to the Jupyter Notebook application running on your server. Secure shell (more commonly known as SSH) is a network protocol which enables you to connect to a remote server securely over an unsecured network.

The SSH protocol includes a port forwarding mechanism that allows you to tunnel certain applications running on a specific port number on a server to a specific port number on your local computer. We will learn how to securely "forward" the Jupyter Notebook application running on your server (on port 8888, by default) to a port on your local computer.

The method you use for establishing an SSH tunnel will depend on your local computer's operating system. Jump to the subsection below that is most relevant for your machine.

Note: It's possible to set up and install the Jupyter Notebook using the DigitalOcean Web Console, but connecting to the application via an SSH tunnel must be done through the terminal or with PuTTY.

SSH Tunneling using macOS or Linux

If your local computer is running Linux or macOS, it's possible to establish an SSH tunnel just by running a single command.

ssh is the standard command to open an SSH connection, but when used with the -L directive, you can specify that a given port on the local host (that is, your local machine) will be forwarded to a given host and port on the remote host (in this case, your server). This means that whatever is running on the specified port on the remote server (8888, Jupyter Notebook's default port) will appear on the specified port on your local computer (8000 in the example command).

To establish your own SSH tunnel, run the following command. Feel free to change port 8000 to one of your choosing if, for example, 8000 is in use by another process. It is recommended that you use a port greater than or equal to 8000, as those port numbers are unlikely to be used by another process. Be sure to include your own server's IP address and the name of your server's non-root user:

ssh -L 8000:localhost:8888 sammy@your_server_ip

If there are no errors from this command, it will log you into your remote server. From there, activate the virtual environment:

source ~/environments/my_env/bin/activate

Then run the Jupyter Notebook application:

jupyter notebook

To connect to Jupyter Notebook, use your favorite web browser to navigate to the local port on the local host: http://localhost:8000. Now that you're connected to Jupyter Notebook, continue on to Step 4 to learn how to use it.

SSH Tunneling using Windows and PuTTY

PuTTY is an open-source SSH client for Windows which can be used to connect to your server. After downloading and installing PuTTY on your Windows machine (as described in the prerequisite tutorial), open the program and enter your server URL or IP address, as shown here:

Next, click + SSH at the bottom of the left pane, and then click Tunnels. In this window, enter the port that you want to use to access Jupyter on your local machine (8000 ). It is recommended to use a port greater or equal to 8000 as those port numbers are unlikely to be used by another process. If 8000 is used by another process, though, select a different, unused port number. Next, set the destination as localhost:8888, since port 8888 is the one that Jupyter Notebook is running on. Then click the Add button and the ports should appear in the Forwarded ports field:

Finally, click the Open button. This will both connect your machine to the server via SSH and tunnel the desired ports. If no errors show up, go ahead and activate your virtual environment:

source ~/environments/my_env/bin/activate

Then run Jupyter Notebook:

jupyter notebook

Next, navigate to the local port in your favorite web browser, for example http://localhost:8000 (or whatever port number you chose), to connect to the Jupyter Notebook instance running on the server. Now that you're connected to Jupyter Notebook, continue on to Step 4 to learn how to use it.

Step 4 — Using Jupyter Notebook

When accessed through a web browser, Jupyter Notebook provides a Notebook Dashboard which acts as a file browser and gives you an interface for creating, editing and exploring notebooks. Think of these notebooks as documents (saved with a .ipynb file extension) which you populate with any number of individual cells. Each cell holds an interactive text editor which can be used to run code or write rendered text. Additionally, notebooks allow you to write and run equations, include other rich media, such as images or interactive plots, and they can be exported and shared in various formats (.ipyb, .pdf, .py). To illustrate some of these functions, we'll create a notebook file from the Notebook Dashboard, write a simple text board with an equation, and run some basic Python 3 code.

By this point you should have connected to the server using an SSH tunnel and started the Jupyter Notebook application from your server. After navigating to http://localhost:8000, you will be presented with a login page:

In the Password or token field at the top, enter the token shown in the output after you ran jupyter notebook from your server:

Output
[I 20:35:17.004 NotebookApp] Writing notebook server cookie secret to /run/user/1000/jupyter/notebook_cookie_secret
[I 20:35:17.314 NotebookApp] Serving notebooks from local directory: /home/sammy
[I 20:35:17.314 NotebookApp] 0 active kernels
[I 20:35:17.315 NotebookApp] The Jupyter Notebook is running at:
[I 20:35:17.315 NotebookApp] http://localhost:8888/?token=Example_Jupyter_Token_3cadb8b8b7005d9a46ca4d6675
[I 20:35:17.315 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[W 20:35:17.315 NotebookApp] No web browser found: could not locate runnable browser.
[C 20:35:17.316 NotebookApp]
. . .

Alternatively, you can copy that URL from your terminal output and paste it into your browser's address bar.

Automatically, Jupyter notebook will show all of the files and folders stored in the directory from which it's run. Create a new notebook file by clicking New then Python 3 at the top-right of the Notebook Dashboard:

Within this new notebook, change the first cell to accept markdown syntax by clicking Cell > Cell Type > Markdown on the navigation bar at the top. In addition to markdown, this Cell Type also allows you to write equations in LaTeX. For example, type the following into the cell after changing it to markdown:

# Simple Equation

Let us now implement the following equation in Python:
$$ y = x^2$$

where $x = 2$

To turn the markdown into rich text, press CTRL + ENTER and the following should be the result:

You can use the markdown cells to make notes and document your code.

Now, let's implement a simple equation and print the result. Click Insert > Insert Cell Below to insert a cell. In this new cell, enter the following code:

x = 2
y = x*x
print(y)

To run the code, press CTRL + ENTER, and the following will be the result:

These are some relatively simple examples of what you can do with Jupyter Notebook. However, it is a very powerful application with many potential use cases. From here, you can add some Python libraries and use the notebook as you would with any other Python development environment.

Conclusion

You should be now able to write reproducible Python code and text using the Jupyter Notebook running on a remote server. To get a quick tour of Jupyter Notebook, click Help in the top navigation bar and select User Interface Tour as shown here:

If you're interested, we encourage you to learn more about Jupyter Notebook by going through the Project Jupyter documentation. Additionally, you can build on what you learned in this tutorial by learning how to code in Python 3.