liminfoSingularity Reference
Free reference guide: Singularity Reference
About Singularity Reference
The Singularity/Apptainer Reference is a practical command reference for researchers and system administrators using Apptainer (formerly Singularity) containers in HPC environments. It covers the core concepts including the SIF (Singularity Image Format) single-file read-only container format, Docker image conversion, and the key commands: apptainer build for creating images from Docker Hub or .def files, apptainer exec for running commands inside containers, apptainer shell for interactive sessions, apptainer run for executing the container runscript, and apptainer pull for downloading remote images from Docker Hub, NGC, and OCI registries.
The definition file (.def) section provides complete build recipe documentation covering Bootstrap source selection (docker, library, localimage, debootstrap, yum, oras, scratch), the %post section for package installation and compilation during build, %environment for runtime PATH and LD_LIBRARY_PATH configuration, %files for copying host files into the container, %runscript for default execution behavior, %test for automated build verification, and %labels for metadata. Bind mount and overlay filesystem options are documented including --bind for directory mapping, --mount for advanced mount syntax, --overlay for adding writable layers to read-only SIF images, and --no-home for isolating the home directory.
HPC-specific features are covered extensively: GPU passthrough with --nv (NVIDIA CUDA library auto-binding) and --rocm (AMD ROCm), MPI support in both Bind model (host MPI launches container) and Hybrid model (container internal MPI with PMI2/PMIx), SLURM scheduler integration with srun and environment variables (APPTAINER_BIND, APPTAINER_NV), background instance management for daemons, remote registry operations (push/pull to Sylabs Cloud, OCI registries), PGP-based image signing and verification, security options (seccomp, AppArmor profiles), and fakeroot for non-root container building using user namespaces.
Key Features
- Core commands: apptainer build (from Docker/def/sandbox), exec, shell, run, pull with options like --fakeroot and --force
- Definition file sections: Bootstrap sources, %post install, %environment vars, %files copy, %runscript, %test validation
- Bind mounts and overlays: --bind directory mapping, --mount advanced syntax, --overlay writable layers, --no-home isolation
- GPU passthrough: --nv for NVIDIA CUDA auto-bind, --rocm for AMD ROCm, with host driver compatibility notes
- MPI parallel execution: Bind model (mpirun + apptainer exec) and Hybrid model with PMI2/PMIx support
- SLURM integration: srun with apptainer exec, SBATCH directives, and APPTAINER_* environment variable configuration
- Security: --fakeroot for non-root builds, PGP image signing/verification, seccomp and AppArmor profiles
- Instance management, remote registry push/pull, Docker conversion, apptainer inspect, and cache configuration
Frequently Asked Questions
What is the difference between Singularity and Apptainer?
Apptainer is the current name of the project, formerly known as Singularity. The project was transferred to the Linux Foundation in 2021 and renamed to Apptainer. The command-line tool changed from singularity to apptainer, and environment variables from SINGULARITY_* to APPTAINER_*. Core functionality and SIF image format remain the same. Singularity CE (Community Edition) is maintained separately by Sylabs.
How do I build a container from a Docker image?
Use apptainer build my_container.sif docker://ubuntu:22.04 to pull a Docker image and convert it to SIF format. For GPU workloads: apptainer build container.sif docker://nvidia/cuda:12.0-runtime. You can also build from a definition file: apptainer build container.sif my.def. Use --sandbox for a writable directory instead of SIF, and --fakeroot for building without root privileges.
What is a .def definition file and what sections does it contain?
A .def file is the build recipe for an Apptainer container. Key sections: Bootstrap/From (base image source), %labels (metadata), %post (build-time commands for installing packages), %environment (runtime environment variables like PATH), %files (copy host files into container), %runscript (default command when container is run), %test (automated build validation), and %help (usage documentation).
How do I use GPU acceleration with Apptainer?
Add the --nv flag for NVIDIA GPUs: apptainer exec --nv container.sif python3 train.py. This automatically binds host CUDA libraries and GPU devices into the container. For AMD GPUs, use --rocm instead. The container does not need GPU drivers installed; it uses the host drivers. Ensure your CUDA toolkit version in the container is compatible with the host driver version.
How does MPI work with Apptainer containers?
The Bind model (recommended) uses the host MPI to launch the container: mpirun -np 4 apptainer exec container.sif ./my_mpi_app. Host and container MPI versions must be ABI-compatible. The Hybrid model uses the container internal MPI with PMI2/PMIx for process management. With SLURM: srun apptainer exec container.sif ./my_mpi_app. Performance is comparable to bare-metal execution.
How do I persist data with read-only SIF containers?
Use --bind to mount host directories: apptainer exec --bind /data:/mnt container.sif command. Default mounts include $HOME, /tmp, /proc, /sys, /dev. For writable layers on SIF, use --overlay: create an overlay with apptainer overlay create --size 500 overlay.img, then apptainer exec --overlay overlay.img container.sif bash. Changes in the overlay persist across sessions.
How do I integrate Apptainer with SLURM?
In your SLURM batch script, use srun apptainer exec container.sif your_command. Set GPU access with --gres=gpu:1 in SBATCH and --nv in apptainer. Use environment variables for configuration: APPTAINER_BIND for mounts, APPTAINER_NV=1 for GPU. Load apptainer as a module if required. The container sees the same resources allocated by SLURM to the job.
How do I build containers without root access on HPC?
Use --fakeroot: apptainer build --fakeroot container.sif my.def. This uses user namespaces to emulate root inside the build environment. The system administrator must configure /etc/subuid and /etc/subgid for your user (apptainer config fakeroot --add username). Alternatively, build on a local machine with root access and transfer the SIF file to the HPC cluster.