Apptainer - HPC Container Management
Overview
The apptainer command manages Apptainer (formerly Singularity) containers for HPC-compatible workloads. It provides SIF image management with automatic GPU detection.
Key Concept: Apptainer is the HPC standard. Unlike Docker/Podman, containers run as the user (no root). SIF files are single-file images.
Quick Reference
| Action | Command | Description |
|---|---|---|
| Build | ujust apptainer build DEF | Build SIF from definition file |
| Cache | ujust apptainer cache [clean|status] | Manage Apptainer cache |
| Exec | ujust apptainer exec IMAGE CMD | Execute specific command in container |
| Inspect | ujust apptainer inspect IMAGE | Show SIF file metadata |
| Pull | ujust apptainer pull IMAGE | Download container image to SIF file |
| Run | ujust apptainer run IMAGE | Run container with default command |
| Shell | ujust apptainer shell [-- CMD] | Open interactive shell in container |
Parameters
| Parameter | Long Flag | Short | Default | Description |
|---|---|---|---|---|
| action | (positional) | - | required | Action: pull, run, shell, exec, build, inspect, gpu, cache |
| image | --image | -i | "" | SIF file path, image name, or DEF file |
| tag | --tag | -t | "" | Image tag, output file, or cache subaction |
| cmd | (variadic) | - | "" | Command to execute (use -- separator) |
Pull Images
bazzite-ai Pod Images
# Pull nvidia-python (long form)
ujust apptainer pull --image=nvidia-python
# Pull with tag (long form)
ujust apptainer pull --image=nvidia-python --tag=testing
# Pull nvidia-python (short form)
ujust apptainer pull -i nvidia-python
# Pull with tag (short form)
ujust apptainer pull -i nvidia-python -t testing
# Pull jupyter
ujust apptainer pull --image=jupyter --tag=stable
External Images
# Docker Hub
ujust apptainer pull --image=docker://ubuntu:22.04
# NVIDIA NGC
ujust apptainer pull --image=docker://nvcr.io/nvidia/pytorch:latest
# Sylabs Cloud
ujust apptainer pull --image=library://sylabsed/examples/lolcow
Pull Output
Images are saved as SIF files:
~/.local/share/apptainer/bazzite-ai-pod-nvidia-python.sif
Run Containers
Run with Default Command
# Run nvidia-python (long form)
ujust apptainer run --image=nvidia-python
# Run nvidia-python (short form)
ujust apptainer run -i nvidia-python
# Run specific SIF file
ujust apptainer run --image=./my-container.sif
Run with Command
# Run Python in container (use -- separator for commands)
ujust apptainer run --image=nvidia-python -- python
# Run script
ujust apptainer run --image=nvidia-python -- python script.py
# Short form
ujust apptainer run -i nvidia-python -- python train.py
GPU Auto-Detection
GPU flags are auto-detected:
- NVIDIA: Adds
--nv - AMD: Adds
--rocm
# GPU is automatically enabled
ujust apptainer run --image=nvidia-python -- python -c "import torch; print(torch.cuda.is_available())"
Interactive Shell
# Shell into container (long form)
ujust apptainer shell --image=nvidia-python
# Shell into container (short form)
ujust apptainer shell -i nvidia-python
# Now inside container
python --version
nvidia-smi
exit
Execute Commands
# Execute single command (use -- separator)
ujust apptainer exec --image=nvidia-python -- pip list
# Execute Python one-liner
ujust apptainer exec -i nvidia-python -- python -c 'print(1+1)'
Build from Definition
Definition File Example
Bootstrap: docker
From: ubuntu:22.04
%post
apt-get update
apt-get install -y python3 python3-pip
%runscript
python3 "$@"
Build
# Build SIF from definition (image=DEF, tag=OUTPUT)
ujust apptainer build --image=mydef.def --tag=myimage.sif
# Build to default location
ujust apptainer build --image=mydef.def
# Short form
ujust apptainer build -i mydef.def -t myimage.sif
GPU Support
Test GPU
# Detect and test GPU
ujust apptainer gpu
GPU Flags
| GPU | Flag | Auto-Detection |
|---|---|---|
| NVIDIA | --nv | Yes |
| AMD | --rocm | Yes |
| Intel | (none yet) | No |
Manual GPU Override
# Direct apptainer command with GPU
apptainer run --nv nvidia-python.sif nvidia-smi
Cache Management
List Cache
# Long form
ujust apptainer cache --tag=list
# Or
ujust apptainer cache list
Clean Cache
# Long form
ujust apptainer cache --tag=clean
# Or
ujust apptainer cache clean
Cache is stored in ~/.apptainer/cache/.
Common Workflows
HPC Development
# Pull HPC-ready image
ujust apptainer pull --image=nvidia-python
# Test GPU
ujust apptainer gpu
# Development shell
ujust apptainer shell --image=nvidia-python
# Run production workload
ujust apptainer run --image=nvidia-python -- python train.py
Use NGC Images
# Pull NVIDIA PyTorch
ujust apptainer pull --image=docker://nvcr.io/nvidia/pytorch:23.10-py3
# Run training
ujust apptainer run --image=pytorch_23.10-py3.sif -- python train.py
Build Custom Image
# Create definition file
cat > myenv.def << 'EOF'
Bootstrap: docker
From: python:3.11
%post
pip install numpy pandas scikit-learn
%runscript
python "$@"
EOF
# Build
ujust apptainer build --image=myenv.def --tag=myenv.sif
# Test
ujust apptainer run --image=myenv.sif -- python -c "import numpy; print(numpy.__version__)"
Apptainer vs Docker/Podman
| Feature | Apptainer | Docker/Podman |
|---|---|---|
| Root required | No | Sometimes |
| Single file | Yes (SIF) | No (layers) |
| HPC compatible | Yes | Limited |
| GPU support | --nv, --rocm | nvidia-docker |
| Security model | User namespace | Container namespace |
Use Apptainer when:
- Running on HPC clusters
- Need single-file portability
- Can't run as root
- Need reproducibility
Troubleshooting
Pull Failed
Check:
# Test network
curl -I https://ghcr.io
# Check registry auth
apptainer remote list
Fix:
# Login to registry
apptainer remote login docker://ghcr.io
GPU Not Available
Check:
ujust apptainer gpu
nvidia-smi # or rocm-smi
Fix:
# Ensure drivers installed
# For NVIDIA:
nvidia-smi
# For AMD:
rocm-smi
SIF File Corrupted
Fix:
# Remove and re-pull
rm ~/.local/share/apptainer/*.sif
ujust apptainer pull --image=nvidia-python
Cache Too Large
Check:
du -sh ~/.apptainer/cache/
Fix:
ujust apptainer cache --tag=clean
Cross-References
- Related Skills:
pod(build OCI images),jupyter(uses containers) - GPU Setup:
ujust config gpu setup - Apptainer Docs: https://apptainer.org/docs/
When to Use This Skill
Use when the user asks about:
- "apptainer", "singularity", "HPC container"
- "SIF file", "pull image", "build container"
- "apptainer GPU", "run with GPU"
- "HPC workload", "cluster container"