Jupyter Notebook¶

Jupyter notebooks let you mix code, visualizations, and notes in a single document. On the DIPC clusters, you run the Jupyter server on a compute node and connect to it from your local browser through an SSH tunnel.

There are two ways to launch the server:

Both methods give you the same result: a Jupyter server on a compute node that you access through your local browser.

module load Miniforge3

In the examples below, replace <login_node> with the login address of your cluster:

See the Connect page for more details.

Interactive mode¶

Step 1: Request a compute node¶

srun --nodes=1 --ntasks=1 --cpus-per-task=4 --mem=20G --qos=regular --time=4:00:00 --pty bash

If you are not familiar with these flags, the SLURM reference explains each directive in detail.

Once SLURM allocates the resources, your prompt will change to show the compute node hostname (e.g., hyperion-039). Take note of it.

Step 2: Start the notebook server¶

module load Miniforge3
jupyter notebook --no-browser --ip 0.0.0.0

The output will show the connection URLs:

[C 2026-03-09 11:53:36.918 ServerApp]

    To access the server, open this file in a browser:
        file:///home/<username>/.local/share/jupyter/runtime/jpserver-1528950-open.html
    Or copy and paste one of these URLs:
        http://hyperion-039:8888/tree?token=58ba7c2deaca627fc8af44854714327ff2a2ec610884c85c
        http://127.0.0.1:8888/tree?token=58ba7c2deaca627fc8af44854714327ff2a2ec610884c85c

Take note of the compute node hostname (hyperion-039 in this example) and the port (8888).

env PYTHONNOUSERSITE=1 jupyter notebook --no-browser --ip 0.0.0.0

Step 3: Create an SSH tunnel¶

On your local machine, open a new terminal and create a tunnel that maps local port 8888 to port 8888 on the compute node:

ssh -L 8888:<compute_node>:8888 <username>@<login_node> -N

For example, if Jupyter is running on hyperion-039:

ssh -L 8888:hyperion-039:8888 <username>@hyperion.sw.ehu.es -N

By using the same port on both sides, you can directly use the 127.0.0.1 link that Jupyter prints in the output.

Step 4: Open the notebook in your browser¶

Copy the http://127.0.0.1:8888/... URL from step 2 and paste it in your browser:

http://127.0.0.1:8888/tree?token=58ba7c2deaca627fc8af44854714327ff2a2ec610884c85c

The token changes every time you start a new notebook server.

To stop the server, press Ctrl+C in the terminal where Jupyter is running.

Batch mode¶

If you prefer not to wait in the terminal for resources, you can submit a batch script that starts the Jupyter server for you. Once the job starts running, you check the log file for the connection info and set up the tunnel as usual.

Step 1: Create the batch script¶

Save the following as jupyter_batch.sh:

#!/bin/bash
#SBATCH --job-name=jupyter
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --mem=20G
#SBATCH --time=8:00:00
#SBATCH --qos=regular
#SBATCH --output=jupyter-%j.log

module load Miniforge3

# Print connection info to the log file
echo "Jupyter running on: $(hostname)"
echo "To create the SSH tunnel, run on your local machine:"
echo "  ssh -L 8888:$(hostname):8888 $USER@<login_node> -N"

jupyter notebook --no-browser --ip 0.0.0.0 --port 8888

Replace <login_node> in the echo line with the login address of your cluster (see the table above).

Step 2: Submit and wait for it to start¶

sbatch jupyter_batch.sh

Check the status with squeue:

squeue -u $USER

Once the job is in RUNNING state, the log file will contain everything you need:

cat jupyter-<JOBID>.log

You will see something like this:

Jupyter running on: hyperion-039
To create the SSH tunnel, run on your local machine:
  ssh -L 8888:hyperion-039:8888 <username>@hyperion.sw.ehu.es -N

[C 2026-03-09 11:53:36.918 ServerApp]

    To access the server, open this file in a browser:
        file:///home/<username>/.local/share/jupyter/runtime/jpserver-1528950-open.html
    Or copy and paste one of these URLs:
        http://hyperion-039:8888/tree?token=58ba7c2deaca627fc8af44854714327ff2a2ec610884c85c
        http://127.0.0.1:8888/tree?token=58ba7c2deaca627fc8af44854714327ff2a2ec610884c85c

Step 3: Connect¶

From your local machine, create the SSH tunnel using the command printed in the log:

ssh -L 8888:hyperion-039:8888 <username>@hyperion.sw.ehu.es -N

Then copy the http://127.0.0.1:8888/... URL and paste it in your browser, exactly as in interactive mode.

Adding custom kernels¶

If you have conda environments or virtual environments with specific packages, you can register them as Jupyter kernels so they appear in the notebook kernel selector.

Activate the environment and install the IPython kernel:

conda activate my_environment
python -m ipykernel install --user --name=my_environment --display-name "My Environment"

The new kernel will appear in the notebook's kernel menu:

To list all installed kernels:

jupyter kernelspec list

To remove a kernel you no longer need:

jupyter kernelspec uninstall my_environment

See also¶