Apptainer/Singularity

Guidance last updated: 27 October 2026

Designed around the notion of extreme mobility of compute and reproducible science, Apptainer (previously known as Singularity) enables users to have full control of their operating system environment. This means that a non-privileged user can “swap out” the operating system on the host for one they control. So if the host system is running AlmaLinux but your application runs in Ubuntu, you can create an Ubuntu image, install your applications into that image, and run your application on that host in its native Ubuntu environment. Images can also be copied between hosts, so you could build your image on your local system, upload it to the HPC, and then run it there.

Apptainer also allows you to leverage the resources of whatever host you are on. This includes high-speed cluster interconnects, resource managers, file systems, GPUs and/or accelerators, etc.

About Apptainer Containers and Images

Similar to Docker, an Apptainer container (image) is a self-contained software stack. As Apptainer does not require a root-level daemon to run its images it is compatible for use with Stanage’s scheduler inside your job scripts. Running images use the credentials of the person who started them.

In practice, this means that an image created on your local machine with all your research software installed for local development can also run on the HPC cluster when its architecture is compatible (for example x86_64). Containers share the host kernel.

You can bring an existing SIF image or import an OCI image as shown below (see Interactive Usage of Apptainer Images). Creating or modifying images may require root privileges or a supported rootless build configuration. The privileged build examples below are for your local machine, not Stanage (see Creating Your Own Apptainer Images).

Apptainer versus Singularity

The Singularity project forked into the Apptainer and the Singularity CE projects in 2021. If you’ve previously used Singularity on TUOS’s HPC systems and now want to use Apptainer then be aware that:

  • Apptainer is (currently) almost identical in behaviour and usage to the latest release of Singularity: it understands the same image format and has very similar command-line behaviour;

  • You should run apptainer instead of singularity

  • Singularity behaviour could previously be modified using environment variables with prefixes SINGULARITY_ and SINGULARITYENV_; you should now use APPTAINER_ and APPTAINERENV_ prefixes instead (but the old prefixes will still work for now);

  • The per-user configuration directory has changed from ~/.singularity to ~/.apptainer.

  • If you tried pulling images from a remote repository using Singularity without specifying the repository hostname then this would default to pulling images from the Sylabs Cloud. With Apptainer there is no default remote repository; see the Remote Endpoints documentation.

For more information on the differences between Apptainer and Singularity see the Apptainer 1.0.0 release notes.

Interactive Usage of Apptainer Images

Request an interactive session before running these commands.

Check that Apptainer is available in your allocation with apptainer --version. To get an interactive shell in the image, use the following command:

apptainer shell path/to/image.sif

Or if you prefer bash:

apptainer exec path/to/image.sif /bin/bash

Note that the exec command can also be used to execute other applications/scripts inside the image or from the mounted directories (See Automatic Mounting of Stanage Filestore Inside Images):

apptainer exec path/to/image.sif ./my_script.sh

Submitting Batch Jobs That Uses Apptainer Images

When submitting a job that uses an Apptainer image, it is not possible to use the interactive shell (e.g. apptainer shell or apptainer exec path/to/image.sif /bin/bash). You must use the exec command to call the desired application or script directly.

The following example batch submission script, my_apptainer_job.sh, shows two ways to list the root directory inside your image:

#!/bin/bash
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=1
#SBATCH --mem-per-cpu=8000
#SBATCH --time=00:10:00

set -e
export SLURM_EXPORT_ENV=ALL

# Calling ls directly using the exec command
apptainer exec path/to/image.sif ls /

# Have Apptainer call a custom script from your home or other mounted directories
# Don't forget to make the script executable before running by using chmod
chmod +x ~/myscript.sh
apptainer exec path/to/image.sif ~/myscript.sh

Where the content of ~/myscript.sh is shown below:

#!/bin/bash

ls /

The job can then be submitted as normal with sbatch:

sbatch my_apptainer_job.sh

Using Nvidia GPUs with Apptainer Images

You can use GPUs in your image by adding the --nv flag to the command e.g. for running interactively:

apptainer shell --nv myimage.sif

or when running within the batch file:

apptainer exec --nv myimage.sif ./myscript.sh

Within a GPU allocation, check GPU visibility inside the container with:

apptainer exec --nv myimage.sif nvidia-smi

This checks device visibility. Your image must also supply the user-space libraries required by its GPU application.

Automatic Mounting of Stanage Filestore Inside Images

When running Apptainer containers on the cluster, your home directory ($HOME), /mnt/parscratch and temporary directories are automatically bind-mounted (exposed) from the host operating system into your container, i.e. the cluster’s ordinary filestores will be automatically visible within a container started on the cluster without that directory being explicitly created when the corresponding Apptainer image was built.

Warning

Binding your HPC home directory makes its files visible inside the container. Applications may then read configuration files or load packages and libraries from your home directory, depending on their startup behaviour and environment variables. Binding alone does not activate these files or environments.

Potential sources of unintended behaviour include:

  • Shell initialisation files such as ~/.bashrc or ~/.profile

  • R startup files such as ~/.Rprofile and ~/.Renviron, and personal packages in the library selected by R_LIBS_USER (see R)

  • Python/Conda configuration and packages such as ~/.condarc, ~/.conda and ~/.local

  • User executables and libraries such as ~/bin and ~/lib

Installing Apptainer on Your Local Machine

You will need Apptainer installed on your machine in order to locally run, create and modify images. See the Apptainer project’s installation instructions.

Manually Mounting Paths

When using an Apptainer image on Stanage or your local machine, it may be useful to mount the existing directories in the image to your own path. This can be done with the flag -B local/path:image/path with the path outside of the image left of the colon and the path in the image on the right side, e.g.

apptainer shell -B local/datapath:/data,local/anotherpath3:/anotherpath3 path/to/image.sif

The command mounts the path local/datapath on your local machine to the /data path in the image. Multiple mount points can be joined with , as shown above where we additionally specify that local/anotherpath3 mounts to /anotherpath3. The /home folder is automatically mounted by default.

For ordinary read-only images, Apptainer can create missing bind points when supported by the host configuration. With --writable, destinations for both explicit and automatic binds must already exist inside the image. On Stanage this includes the home-directory path under /users and /mnt/parscratch. See the bind-path documentation.

Creating Your Own Apptainer Images

You can import an existing Docker/OCI image as a SIF file without sudo inside a Stanage worker allocation:

apptainer build myimage.sif docker://ubuntu:24.04

Custom definition files that install packages require a suitable privileged or fakeroot build environment. The following example is for your local machine.

Important

Run the sudo examples below only on your own machine where you have administrator access. Modern Apptainer also supports unprivileged builds when the host has suitable user-namespace/fakeroot configuration; this is a host requirement, not something an ordinary cluster user can enable. See the container-build documentation.

First create an Apptainer definition file for bootstrapping your image. An example definition file we’ll name apptainer-test.def is shown below

Bootstrap: docker
From: ubuntu:24.04

%setup
  # Runs on host. The path to the image is $APPTAINER_ROOTFS

%post
  #Post setup, runs inside the image

  # Default mount paths
  mkdir -p /scratch /data /shared /fastdata /users /mnt/parscratch

  # Install the packages you need
  apt-get update
  apt-get install -y --no-install-recommends git vim cmake


%runscript
  # Runs inside the image every time it starts up

%test
  # Test script to verify that the image is built and running correctly

The definition file takes a base image from DockerHub, in this case Ubuntu 24.04 ubuntu:24.04. Other images on the hub can also be used as the base for the Apptainer image. Choose a published NVIDIA CUDA image tag compatible with your application and the host driver when building a GPU container.

After creating a definition file, use the build command to build the image from your definition file:

sudo apptainer build apptainer-test.sif apptainer-test.def

By default, build creates a SIF image containing a read-only filesystem. Use --sandbox to create a writable directory instead:

sudo apptainer build --sandbox myimage_folder apptainer-test.def

You will also need to add the --writable flag to the command when going in to change the contents of an image:

sudo apptainer shell --writable myimage_folder

Installation notes

Apptainer, unlike much of the other key software packages on Stanage, is not activated using module files. This is because module files are primarily for the purpose of being able to install multiple version of the same software and for security reasons only the most recent version of Apptainer is installed. The security risks associated with providing outdated builds of Apptainer are considered to outweigh the risk of upgrading to backwards incompatible versions.

Apptainer is provided on worker nodes. It is not currently available on the login nodes, so run the examples within an interactive session. Check the installed version with apptainer --version.

Stanage currently disables unprivileged user namespaces. Do not assume that fakeroot builds from definition files are available; use a suitably configured local machine for those builds.