8. How to Use Singularity

Singularity is a container platform designed for High Performance Computing (HPC) environments. It allows non-root users to run applications using existing container images from container registries such as Docker Hub and NVIDIA NGC.

8.1. Creating Container Images (pull)

You can pull container images from container registries like Docker Hub to create a single-file format .sif (Singularity Image Format).

  • Example of pulling an image from Docker Hub:

# Pull Ubuntu 24.04 image from Docker Hub to create a .sif file
$ singularity pull ubuntu_2404.sif docker://ubuntu:24.04

Once completed successfully, ubuntu_2404.sif is created in the current working directory.

Attention

  • Please pull or build container images on the frontend node in advance.

  • Please also download necessary datasets on the frontend node in advance.

8.2. Cleaning the Cache (cache clean)

When pulling or building container images with Singularity, downloaded layers and metadata are stored in the cache directory under your home directory ( ~/.singularity/cache ). To prevent exhausting the home directory quota, clean the cache every time after pulling images.

8.2.1. Checking Cached Images

You can check the current cache usage and stored entries with the singularity cache list command.

$ singularity cache list

To see a detailed list, specify the -v (verbose) option:

$ singularity cache list -v

8.2.2. Cleaning the Cache

To remove cached files, use the singularity cache clean command.

  • Interactive cleanup of all cache:

$ singularity cache clean

When prompted ( Do you want to continue? [y/N] ), enter y to proceed.

  • Force cleanup of all cache without confirmation:

You can clean all cache entries at once without confirmation by passing the --all ( -a ) and --force ( -f ) options:

$ singularity cache clean --all --force

8.3. How to Run Containers

Common commands to execute containers:

Command

Description

singularity exec <image.sif> <command>

Executes the specified command inside the container.

singularity shell <image.sif>

Starts an interactive shell inside the container.

singularity run <image.sif>

Executes the default runscript defined in the container.

Key options:

  • --nv : Enables NVIDIA GPU access inside the container (required on Accelerator Server).

  • -B <host_path>:<container_path> (or --bind): Binds host directories into the container.

8.4. Job Script Examples

Below are job script examples for submitting batch jobs.

8.4.1. Large-scale Parallel Computing Server (CPU)

Example of running commands inside an Ubuntu container pulled from Docker Hub.

#!/bin/sh
#PBS -l select=1:ncpus=4:mem=16gb
#PBS -q CP_001
#PBS -N singularity_cpu

cd $PBS_O_WORKDIR

singularity exec ubuntu_2404.sif cat /etc/os-release > result.out 2> result.err

8.4.2. Accelerator Server (GPU)

When running a container that utilizes GPUs, specify the --nv option.

#!/bin/sh
#PBS -l select=1:ncpus=2:ngpus=1:mem=32gb
#PBS -q CA_001
#PBS -N singularity_gpu

cd $PBS_O_WORKDIR

singularity exec --nv nvidia_container.sif nvidia-smi > result.out 2> result.err