Topics Map > Computing


Apptainer is a container platform. It allows you to create and run containers that package up pieces of software in a way that is portable and reproducible. You can build a container using Apptainer on your laptop, and then run it on many of the largest HPC clusters in the world, local university or company clusters, a single server, in the cloud, or on a workstation down the hall. Your container is a single file, and you don’t have to worry about how to install all the software you need on each different operating system and system. Apptainer used to be known as Singularity, and some existing documentation still has that old name. Additionally, the image files are still called Singularity Image Files, or .sif files.

Basic Commands

 Command Description
apptainer help To see list of all commands and descriptions
apptainer build Create a basic container
apptainer pull Pull an image from a URI
apptainer shell Enter the shell
apptainer run Run a Apptainer Image File (sif)
apptainer exec Run a command within the container
Obtaining Singularity container images
1. Pulling pre-built images
From Docker Hub, use the docker:// registry prefix. Most Docker container images will convert to the Singularity image format. For example, to get an image containing pytorch runtime, enter:
apptainer pull docker://pytorch/pytorch:1.11.0-cuda11.3-cudnn8-runtime

From Singularity Cloud Library, use the library:// registry prefix. For example, to get a basic Pytorch-geometric image, enter:
apptainer pull library://emiletura/pytorch-geometric/pyg-1-11-0-cuda11-3-cudnn8:latest
2. Building Singularity images
To build Singularity containers, you need root access to the build system. Therefore, you cannot build a Singularity container on the cluster. Depending on whether or not you have an access to a Linux machine, possible options are:
  • If you have a Linux system to which you have root (admin) access, you can install Apptainer and build your Singularity containers there. See Install Singularity on Linux for more information.
  • If you don’t have a Linux system you could easily install one in a virtual machine using software like VirtualBox, Vagrant, or VMware. See Install on Windows or Mac for specific Windows or MacOS instructions.
  • Build a Singularity image using Sylabs Cloud, which is explained below.
In addition to your own Linux environment, you will also need a definition file to build a Singularity container from scratch. You can find some simple definition files for a variety of Linux distributions in the /example directory of the source code. Detailed documentation about building Singularity container images is available at the Singularity website.
Running Singularity container images
There is a separate root file system within containers to store installed software and files, but containers can still access and interact with file systems on the host system. Singularity will automatically mount the following directories to a container:
  • /home
  • /tmp
  • /var/tmp
  • /proc
  • /sys
  • /dev
  • And the mounted file systems on the host (/mnt/dv/wid/projects1..7)
To start an interactive shell within a container, enter:
apptainer shell pytorch_geometric.sif
Notice that your shell prompt changes to Apptainer>; to indicate that you are now working within the container. Enter exit to exit the container.
To non-interactively execute commands within a container, enter:
apptainer exec pytorch_geometric_docker.sif <command> <arg-1> <arg-2> ... <arg-N>

apptainer exec pytorch_geometric_docker.sif python3

To run the default command within the Singularity image use, for example:

apptainer run pytorch_geometric_docker.sif <arg-1> <arg-2> ... <arg-N>

Running GPU jobs with Apptainer

To run a GPU-enabled container on a GPU node, use the --nv option to allow the container to access the NVIDIA driver on the node:

apptainer exec --nv pytorch_geometric_docker.sif python3
Additional Resources

If you have questions about or need help with Apptainer, please submit a help desk ticket and we will assist you.

KeywordsDocker, Singularity, container, cluster, apptainer   Doc ID119720
OwnerEmile T.GroupDiscoverIT
Created2022-07-15 10:40:59Updated2023-03-15 11:16:56
SitesDiscovery Building IT
Feedback  0   0