shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

apptainer

Apptainer (Singularity) container management for HPC workloads. Build SIF images, run containers with GPU passthrough. Use when users need HPC-compatible containerization or need to pull/run Apptainer images.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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"