Skip to content

Jupyter Notebook

What is Jupyter Notebook?

Jupyter Notebook is an open-source web application that allows you to create and share documents containing live code, equations, visualizations, and narrative text. It's widely used for data science, scientific computing, and machine learning workflows.

Important - Do NOT Run on Login Node

Computations must NOT be executed on the login node.

Solution: Run Jupyter Notebook server on a compute node via SLURM job and connect to it via SSH tunnel.

Prerequisites

This guide assumes you have Conda installed in your PERUN environment. If you don't have Conda yet, follow the Conda installation guide.

Setup Overview

The basic setup involves five main steps:

  1. Install Jupyter Notebook via Conda
  2. Submit a SLURM job to start Jupyter server on compute node
  3. Get server URL from job output
  4. Create SSH tunnel from local machine to compute node
  5. Access Jupyter in your web browser

Step 1: Install Jupyter via Conda

Install JupyterLab

conda install -c conda-forge jupyterlab -y

Verify Installation

Check that Jupyter was installed successfully: 

jupyter --version

Step 2: Create SLURM Job Script

Create a job script to start Jupyter Notebook server on a compute node.

jupyter_job.sh

SLURM Job Script for Jupyter

#!/bin/bash
#SBATCH --job-name=jupyter
#SBATCH --partition=CPU
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --mem=8G
#SBATCH --time=02:00:00

# Activate your conda environment
source ~/miniconda3/bin/activate
conda activate myenv

# Start Jupyter Lab server
python -m jupyterlab --no-browser --ip=0.0.0.0 --port=8888

Submit the job

sbatch jupyter_job.sh

Job Parameters Explained

  • --partition=CPU: Use CPU or GPU partition depending on your workload
  • --time=02:00:00: Server runs for 2 hours (adjust as needed)
  • --port=8888: Port for Jupyter server (example - see note below)
  • --ip=0.0.0.0: Allow connections from any IP
  • --no-browser: Don't try to open browser on compute node

Port Selection

The port 8888 is just an example. If multiple users use the same port, you'll get conflicts. It's recommended to choose a different port (e.g., 8889, 8890, 9000, etc.) to avoid blocking other users. If you get an "Address already in use" error, change the port number in your script.

Step 3: Get Server URL from Job Output

Once your job is running, check the output file to find the compute node and access token.

Check job output

cat slurm-JOBID.out

Look for two important pieces of information:

  1. Compute node and port: Look for a line like: 

    http://cn01:8888/lab?token=...
    Here, cn01 is the compute node and 8888 is the port.

  2. Full localhost URL with token: Look for a line like: 

    http://127.0.0.1:8888/lab?token=<token>
    This is the URL you'll use in your browser (Step 5).

Note the Compute Node

The compute node name (e.g., cn01, cn02, cn03) will vary depending on which node your job was assigned to. Make sure to use the correct one in the next step.

Step 4: Create SSH Tunnel

Create an SSH tunnel from your local machine to the compute node.

SSH Tunnel (run on your local machine)

ssh -L 8888:cn01:8888 username@login01.perun.tuke.sk

Replace cn01 with your actual compute node from Step 3.

Format explanation: 

ssh -L [local_port]:[compute_node]:[remote_port] username@login_node

Keep this terminal open

The SSH tunnel must remain active while you use Jupyter Notebook. Keep this terminal window open.

Step 5: Access Jupyter in Your Browser

Open Jupyter in Browser

Copy the localhost URL with token from the .out file (from Step 3) and paste it into your web browser: 

http://127.0.0.1:8888/lab?token=<token>

Alternative: Manual Token Entry

You can also:

  1. Open http://127.0.0.1:8888 in your browser
  2. Enter the token manually when prompted (copy it from the .out file)

Ready to Use

You can now use Jupyter Notebook. If you need help with how to use Jupyter Notebook, see the documentation links in the More Information section at the bottom of this guide.

Alternative: Using VS Code

VS Code can be used as an alternative interface for working with Jupyter notebooks.

Install VS Code Extensions

Install the following extensions in VS Code:

  • Python (by Microsoft)
  • Jupyter (by Microsoft)

To install: Open VS Code → Extensions (Ctrl+Shift+X) → Search for each extension → Install

Connect VS Code to Jupyter Server

You have two options to connect VS Code to the Jupyter server:

Option 1: Using SSH Tunnel

Important

You still need to follow Steps 1-4 (install Jupyter, submit job, get server URL, create SSH tunnel) from the main guide above.

Once your Jupyter server is running and SSH tunnel is active:

Connect via SSH Tunnel

  1. Open or create a .ipynb file in VS Code
  2. Click on Select Kernel in the top right
  3. Click Select Another Kernel...
  4. Choose Existing Jupyter Server...
  5. Paste the localhost URL from the job output: 
    http://127.0.0.1:8888/lab?token=<token>
  6. Enter a display name (e.g., cn01)
  7. Select the Python kernel from your environment

Option 2: Using Remote SSH Extension

If you're using VS Code's Remote SSH extension and are already connected to PERUN, you can skip Step 4 (SSH tunnel).

Connect via Remote SSH

  1. Connect to PERUN via Remote SSH extension in VS Code
  2. Open or create a .ipynb file in VS Code
  3. Click on Select Kernel in the top right
  4. Click Select Another Kernel...
  5. Choose Existing Jupyter Server...
  6. Paste the compute node URL from the job output: 
    http://cn01:8888/lab?token=<token>
  7. Enter a display name (e.g., cn01)
  8. Select the Python kernel from your environment

Connected

Notebook cells will now execute on the compute node through the remote Jupyter server.

More Information

Documentation