How to setup and configure Jupyter Notebook on a GPU instance

Jupyter Notebook Overview

Jupyter Notebook is a client-server application that allows to edit and run Notebook documents in a web browser.

The application allows to combine code, comments, multimedia contents, and visualizations in a single interactive document — called a notebook, which runs in a web browser.

The name Jupyter is an acronym which stands for the three languages it was initially designed for: JUlia, PYThon, and R, as the application was developed originally for data science needs. Nowadays Jupyter is the environment of choice for several use cases. Apart from research projects that involve visualizations of data or formulas it is used for documentation of processes with code, sharing of code or interactive visualizations.

Having evolved from its origins, today the application supports over 40 programming languages and is an open source project, based on the IPython Notebook project.


Setting up a remote Jupyter Notebook on a GPU instance

1 . Deploy a new GPU Instance with the Ubuntu ML image from the management console.

2 . Log yourself into the instance using SSH.

3 . Update the apt repositories list and upgrade the packages already installed on the instance:

apt update && apt upgrade -y

4 . Reboot the instance once the software has been upgraded:


5 . Wait a few minutes and reconnect to the instance:

ssh root@gpu-instance-ip

6 . Start the Jupyter Notebook application by running the following command:

jupyter notebook --no-browser --port=8888 --allow-root

The flag --no-browser prevents opening the notebook in a browser after startup. The flag port=8888 specifies the port on which the notebook listens. It is possible to change this value to another port number if required.

Connecting to the Remote Jupyter Notebook from a Linux/MacOS client

To connect to the Jupyter Notebook from a remote client an SSH tunnel is required. SSH is available natively on Linux or MacOS computers.

1 . On a client running on Linux or MacOS open a local terminal and run the following command:

ssh -N -L localhost:7777:localhost:8888 root@gpu-instance-ip

The command above configures the port forwarding of the local port 7777 to the port 8888 on the GPU instance. This allows access to the Jupyter Notebook with a web browser from the local computer.

Optional: Use the option -f in the command above to move SSH into the background, so the local terminal remains usable.

2 . Open a web browser and go to http://localhost:7777. The Jupyter web interface should display:

Login Mac

Connecting to the Remote Jupyter Notebook from a Windows client

To establish an SSH tunnel on a Windows computer, you need to have PuttY installed on the machine.

1 . Open the PuttY application.

2 . In the menu bar on the left, click on Connection > SSH > Tunnels. Then add a new forwarded port:

  • Fill in the Source port: 7777
  • Fill in the Destination: localhost:8888
  • Click on Add to add the configuration. Once done the forwarded port appears in the Forwarded ports list.


3 . Go back to the main window of PuttY and enter the connection details of the instance, then click on Open to log into it.

4 . Keep the PuttY window open in the background and launch a web browser. Go to http://localhost:7777 to connect to the Jupyter Notebook:

Login Windows

Setting a Password for Jupyter Notebook

1 . To access the Jupyter Notebook, an access token is required. It is displayed in the startup messages of the application:


2 . Copy the access token and open the URL http://localhost:7777 in a web browser:

Login Mac

3 . Scroll down to the password section of the page and paste the token into the corresponding form. Then enter a safe password and click on Log in and set new password to take the changes into effect:

Setup Password

Important: In case an error 500 is displayed after setting the password, manually create a directory for Jupyter to store its configuration files: mkdir /root/.jupyter

4 . You are now logged into Jupyter Notebook. The Dashboard :

Jupyter Dashboard

Using Jupyter Notebook

1 . You can now create a new or import an existing Jupyter Notebook by clicking on Upload or New:

Jupyter Create Notebook

2 . Create a new Python 3 notebook by clicking on the corresponding line in the menu:

Jupyter new Notebook

3 . The Jupyter Editor displays. The first cell is already in place and uses the kernel (Python3) that was choosen when starting the notebook. Write your Python 3 code in the cell. To run the content of a cell click on Play:

Jupyter Editor

4 . It is also possible to edit Markdown content in a Cell. To do so, change the status of a cell to Markdown by choosing it from the drop-down menu:

Jupyter Editor

5 . A running notebook is marked with a green icon. To suspend its execution, tick the corresponding box and click on Shutdown:

Jupyter Running Notebook

For more information and advanced configuration of Jupyter Notebook, refer to the official documentation.

Discover the Cloud That Makes Sense