---
title: Setting up and configuring Jupyter Notebook on a Scaleway GPU Instance
description: Jupyter Notebook is a client-server application that allows to edit and run Notebook-documents in a web browser.
tags: GPU-Instance Jupyter Jupyter-Notebook
products:
  - gpu-instances
  - instances
hero: assets/scaleway_jupyter.webp
dates:
  validation: 2025-03-27
  posted: 2019-07-19
  validation_frequency: 12
difficulty: beginner
usecase:
  - build-and-run-ai
ecosystem:
  - third-party
---
import image from './assets/scaleway-login_mac.webp'
import image2 from './assets/scaleway-putty.webp'
import image3 from './assets/scaleway-login_win.webp'
import image4 from './assets/scaleway-token.webp'
import image5 from './assets/scaleway-login_mac.webp'
import image6 from './assets/scaleway-setup_password.webp'
import image7 from './assets/scaleway-jupyter_dashboard.webp'
import image8 from './assets/scaleway-upload_create_notebook.webp'
import image9 from './assets/scaleway-new_notebook.webp'
import image10 from './assets/scaleway-jupyter_editor.webp'
import image11 from './assets/scaleway-jupyter_markdown.webp'
import image12 from './assets/scaleway-running_notebook.webp'

import Requirements from '@macros/iam/requirements.mdx'


Jupyter Notebook is a dynamic client-server application tailored for editing and executing notebook documents right from your web browser.

This versatile platform empowers you to seamlessly blend code, annotations, multimedia elements, and visualizations into a cohesive interactive document — aptly named a **notebook** — all within the confines of your web browser.

Originally designed to cater to the needs of data science, the name **Jupyter** is a clever amalgamation of the initial languages it supported: **JUlia**, **PYThon**, and **R**. However, its utility has transcended those origins. Today, Jupyter serves as the go-to environment for an array of applications. It's not only indispensable for research endeavors involving data visualization or complex formulas but also finds extensive use in documenting processes with code and facilitating code sharing or interactive visualization experiences.

This evolutionary journey has seen Jupyter expand its horizons to provide support for over 40 programming languages. As an open-source project, it builds upon the foundation laid by the *IPython Notebook* project, fostering a vibrant ecosystem of innovation and collaboration.

<Requirements />

- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
- An [SSH key](/organizations-and-projects/how-to/create-ssh-key/)
- `sudo` privileges or access to the root user

## Setting up a remote Jupyter Notebook on a GPU Instance

1. Deploy a new [GPU Instance](/instances/how-to/create-an-instance/) with the [Ubuntu ML](https://www.scaleway.com/en/imagehub/) image from the [Scaleway console](https://console.scaleway.com).
2. [Log in to](/instances/how-to/connect-to-instance/) 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:
    ```
    reboot
    ```
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.

  <Message type="tip">
    Use the option `-f` in the command above to move SSH into the background, so the local terminal remains usable.
  </Message>
2. Open a web browser and go to `http://localhost:7777`. The Jupyter web interface should display:
    <Lightbox image={image} alt="" />

### From a Windows client

To establish an SSH tunnel on a Windows computer, you need to have [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) 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.

    <Lightbox image={image2} alt="" />
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:
    <Lightbox image={image3} alt="" />

## 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:
    <Lightbox image={image4} alt="" />
2. Copy the access token and open the URL `http://localhost:7777` in a web browser:
    <Lightbox image={image5} alt="" />
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:
    <Lightbox image={image6} alt="" />

  <Message type="tip">
    If an error 500 is displayed after setting the password, manually create a directory for Jupyter to store its configuration files: `mkdir /root/.jupyter`
  </Message>
4. You are now logged into Jupyter Notebook. The Dashboard displays:
    <Lightbox image={image7} alt="" />

## Using Jupyter Notebook

1. You can now create a new or import an existing Jupyter Notebook by clicking on **Upload** or **New**:
    <Lightbox image={image8} alt="" />
2. Create a new **Python 3** notebook by clicking on the corresponding line in the menu:
    <Lightbox image={image9} alt="" />
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**:
    <Lightbox image={image10} alt="" />
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:
    <Lightbox image={image11} alt="" />
5. A running notebook is marked with a green icon. To suspend its execution, tick the corresponding box and click **Shutdown**:
    <Lightbox image={image12} alt="" />

For more information and advanced configuration of Jupyter Notebook, refer to the [official documentation](https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/examples_index.html).