Skip to content

JupyterHubHPC

Overview

JupyterHubHPC (or JupyterHub at the Cyfronet Centre) service lets you configure and start JupyterLab servers on Cyfronet's computing clusters (Ares and Athena).

JupyterHubHPC functionality is based on JupyterHub technology with customizations tailored for HPC environments at Cyfronet.

Getting started

Requirements

Starting the first JupyterLab server

  1. Log in to JupyterHubHPC with your PLGrid account
  2. Configure parameters for the job that will start JupyterLab. Take into account all resources you will need to perform planned computations. Note that JupyterHubHPC jobs are limited to a single computing node. Available options are as follows:
    • Cluster - Cluster on which you'd like to start the JupyterLab server
    • Slurm account - For details, please refer to the general PLGrid documentation
    • Partition - For details, please refer to the general PLGrid documentation
    • Number of nodes - Number of nodes to be reserved for the job
    • Number of CPU cores per node - Number of CPU cores per node to be reserved for the job
    • Number of GPUs per node - Field available only if selected Slurm account is dedicated for GPU resources (-gpu suffix)
    • Job memory limit per node - Maximum amount of memory (RAM) per node for the job. The job may be ceased without notice when the limit is exceeded.
    • Job time limit - Note that all computations started using the JupyterLab server will be ceased when the time limit is exceeded
    • Tooolchain - See Toolchains section below
    • Memfs - Enables memfs
    • Localfs - Enables localfs
    • Addons - Enable integration of JupyterLab with external software
      • Visual Studio Code - with this addon, a web-based version of Visual Studio Code can be started from JupyterLab's interface
  3. Click Start

The newly configured job will now be queued to run on the selected cluster.

Depending on the amount of requested resources and cluster occupancy, it may take longer for the job to start.

In case of any recurring errors during that step, please contact the Helpdesk.

Named Servers

Apart from the default (unnamed) JupyterLab server, JupyterHubHPC allows multiple so-called named servers to be started simultaneously.

In order to start a new named server:

  • Navigate to the Home tab in JupyterHubHPC Control Panel
  • In the Named Servers section, type the name of the new server and click Add New Server
  • Configure job parameters as in the default server configuration step

Managing servers (Control Panel)

The list of started servers is available under the Home tab in the JupyterHubHPC Control Panel. To access JupyterHubHPC Control Panel from active JupyterLab, navigate to File -> Hub Control Panel. Once in the Control Panel, one can open JupyterLab's interface or stop servers.

Toolchains

Toolchain defines a set of software modules that are loaded upon the start of the job. Most importantly, they include Python and JupyterHub modules.

  • 2025b - The most recent toolchain based on GCC 14.3.0. Includes Python 3.13.5 and JupyterHub 4.5.6. Current default.
  • 2023b - Legacy toolchain based on GCC 13.2.0. Includes Python 3.11.5. and JupyterHub 4.2.0.

User-defined Python kernels

By default, JupyterLab servers started via JupyterHubHPC use Python version default for the selected toolchain and the user's global environment. However, one can configure virtualenv or conda environments to be available as JupyterLab kernels.

Environment location

As Python environments tend to grow quickly and extend the size of the user's home directory, we recommend putting them in the $PLG_GROUPS_STORAGE/<group name> directory.

The base procedure is as follows:

Virtualenv

Python versions

While it is usually possible to use virtualenvs based on Python versions other than toolchain-default as kernels, we do not provide support for such environments and suggest using the default Python as the base to avoid potential compatibility issues.

  1. Load the Python module. For the 2025b toolchain:

    • On the Ares cluster: 
      module load python/3.13.5-gcccore-14.3.0
    • On Helios and Athena clusters 
      module load GCCcore/14.3.0 Python/3.13.5

  2. Create and activate your virtualenv 

    python -m virtualenv "<env_path>"
source <env_path>/bin/activate

  3. Install the ipykernel package 

    pip install ipykernel

Virtualenvs and modules

If any additional modules have been used to create a virtualenv-based environment and kernel, the same set of modules must be loaded inside the JupyterLab session for the kernel to work correctly.

JupyterLabs started with JupyterHubHPC have a plugin for managing modules enabled by default. This can be done from the Software Modules tab in the JupyterLab's Activity Bar.

GCCcore/13.2.0 and Python/3.11.5 modules are loaded automatically for every JupyterLab session.

Conda

Support for Conda environments

We do not provide additional support for Conda environments. For the best compatibility, please use virtualenvs.

  1. Create and activate your Conda environment with the Python version specified (this part is required for the environment to work within JupyterLab started via PLGridHub) 
    conda create --prefix <env_path> python=<python_version>
conda activate <env_path>
  2. Install the ipykernel package 
    conda install ipykernel

Registering the kernel in JupyterLab

Finally, register the environment (both Conda and virtualenv) on the list of kernels in JupyterLab. 

python -m ipykernel install --user --name "<kernel_name>" --display-name "<kernel_display_name>" --env PYTHONPATH ""
The JupyterLab server needs to be restarted to recognize the new configuration. After that, you should see your newly configured environment on the list of available Python kernels.

Common issues

sbatch: command not found

This error message might occur when you have modified .bashrc file causing global cluster settings to not propagate correctly.

Please make sure your .bashrc file contains the following code, and it is always executed

.bashrc
# Source global definitions
if [ -f /etc/bashrc ]; then
        . /etc/bashrc
fi

Spawn failed: The Jupyter batch job has disappeared while pending in the queue or died immediately after starting.

This error message might occur when .bashrc file contains echo commands or prints in other ways.

Please make sure your .bashrc file does not output anything to stdout or stderr.

Note that we do not provide support for shells other than Bash.

If the above solutions does not help, please contact Helpdesk.