JupyterLab Module (Loki)

Overview

The legacy Jupyter modules are being deprecated and replaced with the modern JupyterLab interface for Loki. This update ensures improved stability, compatibility with modern Python stacks, and better integration with Slurm-based interactive sessions.

Example Slurm Submission Script

Below is an example batch script demonstrating how to launch JupyterLab interactively on Loki.

Warning

Jobs must be submitted from a batch node. Do not launch JupyterLab directly from login or build nodes. Always submit through the batch environment using a Slurm job script.

Using JupyterLab

JupyterLab sessions should be started as batch jobs through the Slurm workload manager.

A JupyterLab job allows users to connect a local web browser to a compute node environment where the notebook server is running. The workflow typically follows these steps:

  1. Create a submission script on a batch node (for example, jupyter.sbatch ).

  2. Load the JupyterLab module within that script.

  3. Start an interactive JupyterLab server on a compute node.

  4. Create an SSH tunnel from your workstation to access the notebook interface.

Example Job Script Outline

Below is a template-style example illustrating the key parts of a JupyterLab submission job. Modify parameters (memory, time, email, etc.) as appropriate for your session.

#!/bin/bash
#SBATCH --job-name=jupyterlab
#SBATCH --mail-user=<YOUR_AU_EMAIL>
#SBATCH --ntasks=4
#SBATCH --mem=32G
#SBATCH --partition=interactive_q
#SBATCH --time=02:00:00

# Load the JupyterLab module
module load slurm JupyterLab/4.2.5-GCCcore-13.3.0

# Generate a one-time token
# export JUPYTER_TOKEN=<RANDOMIZED_TOKEN>
export JUPYTER_TOKEN=$(openssl rand -hex 32)

# Get the node’s IP address
# readonly IPADDRESS=$(hostname -I | tr ' ' '\n' | grep '<IPADDRESS>:')
readonly IPADDRESS=<IP_ADDRESS>

# Display SSH tunnel connection info
echo "SSH tunnel from your workstation using:"
echo "ssh -4 -L 9000:${IP_ADDRESS}:9000 ${USER}@hpc-inter-sub.augusta.edu"
echo
echo "Then open your browser to:"
echo "http://localhost:9000/lab?token=${JUPYTER_TOKEN}"
echo
echo "When finished, close the browser tab to end the session."
echo "Double-check with: squeue -u ${USER}"
echo "If still active, terminate manually with: scancel -f ${SLURM_JOB_ID}"

# Launch JupyterLab
jupyter-lab --port=9000 --ip=${IP_ADDRESS} --no-browser

Running and Monitoring the Job

Once the script is saved, submit it as a normal batch job:

[jsnow@Loki_batch_submission ~]$ sbatch jupyter.sbatch

Submitted batch job 228823

To check progress or confirm that the job is running:

[jsnow@Loki_batch_submission ~]$ squeue -u $USER
             JOBID PARTITION     NAME     USER ST       TIME  NODES NODELIST(REASON)
            228823 interacti jupyterl    jsnow  R       2:19      1   gnode029

When the job is running, an output file such as slurm-228823.out will appear in your directory. You can view it to find your connection information:

------------------------------------------------------
SSH tunnel from your workstation using the command:

ssh -4 -L 9000:<IP ADDRESS>:9000 jsnow@hpc-inter-sub.augusta.edu

Then open your browser to:
http://localhost:9000/lab?token=4439e436151ddc4f4334a2c60e4139be0d5d530630574d2975453652c2757205

When done, close your Jupyter tab to end the session.
Double-check with: squeue -u jsnow
If still active, terminate manually with: scancel -f ${SLURM_JOB_ID}
------------------------------------------------------

[I 2025-11-06 10:14:03.274 ServerApp] Jupyter Server 2.14.2 is running at:
[I 2025-11-06 10:14:03.274 ServerApp] http://<IP ADDRESS>:9000/lab?token=...
[I 2025-11-06 10:14:03.274 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).

When finished, close your browser tab. The session will normally cancel automatically, but you should always verify:

squeue -u $USER

If still running, cancel it manually:

scancel -f <JOBID>

Tips and Troubleshooting

  • Ensure port 9000 is open on your workstation for the SSH tunnel.

  • If multiple users run JupyterLab simultaneously, choose an alternate port (e.g., 8888, 8890).

  • Remember that all jobs launched this way consume compute resources. Close unused sessions promptly with scancel.

  • Session output and logs will appear in the submission directory unless otherwise redirected.