setup jupyter notebook
Jump toUpdate content

Setting up and configuring Jupyter Notebook on a GPU Instance

Reviewed on 24 August 2023Published on 19 July 2019
  • compute
  • GPU-Instance
  • Jupyter
  • Jupyter-Notebook
  • Notebook-documents

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 you 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.

Security & Identity (IAM):

You may need certain IAM permissions to carry out some actions described on this page. This means:

  • you are the Owner of the Scaleway Organization in which the actions will be carried out, or
  • you are an IAM user of the Organization, with a policy granting you the necessary permission sets

Setting up a remote Jupyter Notebook on a GPU Instance

  1. Deploy a new GPU Instance with the Ubuntu ML image from the Scaleway console.
  2. Log in to 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. Open a local terminal and run the following command on a client running on Linux or macOS:
    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.


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

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

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 Connection > SSH > Tunnels. Then add a new forwarded port:

    • Fill in the Source port: 7777
    • Fill in the Destination: localhost:8888
    • Click 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 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:

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:
  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 Log in and set new password to take the changes into effect:

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

  1. You are now logged into Jupyter Notebook. The Dashboard displays :

Using Jupyter Notebook

  1. You can now create a new or import an existing Jupyter Notebook by clicking on Upload or New:
  2. Create a new Python 3 notebook by clicking on the corresponding line in the menu:
  3. The Jupyter Editor displays. The first cell is already in place and uses the kernel (Python3) that was chosen when starting the notebook. Write your Python 3 code in the cell. To run the content of a cell click Play:
  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:
  5. A running notebook is marked with a green icon. To suspend its execution, tick the corresponding box and click Shutdown:

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