Apptainer Containers on amplitUDE

Apptainer (formerly Singularity) is the recommended container solution on the amplitUDE system.
It enables users to run containerized applications securely in multi-user HPC environments without requiring root privileges.

Apptainer allows you to:

  • package complex scientific software environments

  • ensure reproducible workflows

  • run consistent environments across laptops, servers, and HPC nodes

  • integrate seamlessly with SLURM and GPU hardware

This guide explains how to use Apptainer on UDE systems.

1. Loading Apptainer

module load apptainer

apptainer --version

2. Running Containers

Interactive Shell

apptainer shell image.sif

Execute a Single Command

apptainer exec image.sif python3 script.py

Run the Default Entrypoint

apptainer run image.sif

3. Bind Mounting Directories

apptainer exec --bind /path/on/host:/path/in/container image.sif <command>

Example:

apptainer exec --bind $SCRATCH/data:/data image.sif python3 process.py

4. GPU Support

apptainer exec --nv image.sif python3 -c "import torch; print(torch.cuda.is_available())"

5. Pulling Images

Pull from Docker Hub

apptainer pull docker://ubuntu:22.04

Pull from NVIDIA NGC

apptainer pull docker://nvcr.io/nvidia/pytorch:24.01-py3

6. Creating Writable Sandboxes

Create a sandbox

apptainer build --sandbox my_sandbox image.sif

Enter sandbox with fakeroot

apptainer shell --fakeroot --writable my_sandbox

7. Building Images with Definition Files

Example: example.def

Bootstrap: docker
From: ubuntu:22.04

%post
    apt-get update
    apt-get install -y python3 python3-pip

%environment
    export PATH=/usr/local/bin:$PATH

Build the image (not on login nodes):

sudo apptainer build example.sif example.def

8. Using Apptainer in SLURM Jobs

CPU Job

#!/bin/bash
#SBATCH --job-name=apptainer-test
#SBATCH --output=apptainer_%j.out
#SBATCH --time=01:00:00
#SBATCH --mem=4G

module load apptainer

srun apptainer exec image.sif python3 script.py

GPU Job

#!/bin/bash
#SBATCH --gres=gpu:1

module load apptainer

srun apptainer exec --nv pytorch.sif python3 train.py

9. Best Practices on UDE HPC

  • Store large images in $SCRATCH

  • Do not build on login nodes

  • Use definition files for reproducibility

  • Bind-mount needed directories explicitly

  • Use –nv for GPU workloads

  • Keep images minimal

10. Troubleshooting

Directory not visible

apptainer exec --bind $SCRATCH/data:/data image.sif <cmd>

CUDA not detected

apptainer exec --nv image.sif nvidia-smi

Cannot install packages in .sif

Use a sandbox:

apptainer build --sandbox my_sandbox image.sif
apptainer shell --fakeroot --writable my_sandbox

11. Further Resources