Setup

In this document we use the names Apptainer and Singularity interchangeably. See the Introduction for more details about existing Apptainer and Singularity versions and the differences between them.

Option 1: Use pre-installed apptainer on a cluster

Apptainer/Singularity has become popular and usually it is available in the institutional computing resources. Check if apptainer or singularity are available with

apptainer --version
singularity --version

If installed, you will see apptainer version ... or singularity version ..., depending on the flavor installed. Apptainer is preferable but either one is OK, so if apptainer is there, no need to check for singularity (which most likely will be a link to apptainer). This tutorial requires at least Apptainer 1.0.x or Singularity 3.5.x. Previous versions may not have all the required features. If none is in your $PATH or if the available version is too old, you may still be able to use an updated apptainer via CVMFS: check if you have user namespaces enabled and CVMFS to run singularity that way:

[[ $(cat /proc/sys/user/max_user_namespaces) -gt 0 ]] && ls /cvmfs/oasis.opensciencegrid.org/mis/ &>/dev/null && { export PATH=/cvmfs/oasis.opensciencegrid.org/mis/apptainer/bin/:"$PATH"; echo "Success: Added to PATH"; singularity --version; } || echo "Failure: Unable to run Apptainer/Singularity via CVMFS"

If this works, it will be added to your path and you will see your apptainer/singularity version.

If your local computing system does not have Apptainer/Singularity installed, you may request it to your system administrator as suggested here.

Option 2: Install Apptainer/Singularity

You will need a Linux system to run Apptainer/Singularity natively. If you have Linux, go to the Linux install instructions below.

On Windows you can use WSL (Windows Subsystem for Linux). You can run a Linux system on your Windows computer. We recommend AlmaLinux9. Then follow the Linux instructions to install Apptainer as root.

On macOS you also need a Linux VM to be able to use Apptainer. There are different solutions; here we describe how to use Lima.

Install on a Mac

To avoid architecture problems we recommend using an x86_64 VM also on ARM Macs. It will be less performant but you’ll avoid architecture errors when images are available only for x86_64. To do so you can use QEMU and Lima via Homebrew.

1. Install QEMU and Lima via Homebrew:

   # Install Homebrew if you don't have it already
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   # Install QEMU and Lima
   brew install qemu lima
   

2. Prepare an x86_64 VM. Here we use an Ubuntu image:

   # Prepare the VM configuration file
   cat > ubuntu-x86_64.yaml << EOF
   arch: "x86_64"
   images:
     - location: "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
       arch: "x86_64"
     - location: "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-arm64.img"
       arch: "aarch64"
   # Disable mounts and containerd, otherwise booting up may time out if the host is slow
   mounts: []
   containerd:
     system: false
     user: false
   EOF
   # Create and start the VM
   limactl start ubuntu-x86_64.yaml --name=ubuntu
   limactl shell ubuntu
   

3. In the VM install and use apptainer:

   sudo add-apt-repository -y ppa:apptainer/ppa
   sudo apt install -y apptainer
   # Check your Apptainer version
   apptainer --version
   # You can exit the VM with Ctrl+D (exit)
   

Now you’re ready to use Apptainer on your Mac. To use Apptainer (and all commands in this tutorial) you have to first enter your VM with limactl shell ubuntu and when you are done you can go back to the Mac shell using exit (Ctrl+d). If you reboot your Mac you may have to restart the VM with limactl start ubuntu. For more commands to control and configure the Lima VM you can check Lima’s documentation.

On Linux, If you have root access

It is easiest to install if you have root access.

On Linux, If not

If the above is not possible and you cannot use the CVMFS distribution you still have an option if user namespaces are enabled on your system:

1. Check if user namespaces are enabled:

   # on Debian/Ubuntu
   grep -q 'kernel.unprivileged_userns_clone=1' /etc/sysctl.d/90-unprivileged_userns.conf && \
       echo "User namespaces enabled, continue the Apptainer installation" || \
       echo "User namespaces NOT enabled, your use of Apptainer will be very limited"
   # on RHEL/CentOS check that /proc/sys/user/max_user_namespaces is bigger than 0
   [[ $(cat /proc/sys/user/max_user_namespaces) -gt 0 ]] && \
       echo "User namespaces enabled, continue the Apptainer installation" || \
       echo "User namespaces NOT enabled, your use of Apptainer will be very limited"
   

   See these full instructions for more about checking for and enabling user namespaces.

2. If enabled, install unprivileged Apptainer with one of these three methods (in order of preference):

   1. Choose your INSTALL_DIR and install there the relocatable Apptainer (recommended). Run:

      curl -s https://raw.githubusercontent.com/apptainer/apptainer/main/tools/install-unprivileged.sh | \
          bash -s - INSTALL_DIR
      

   2. Alternatively install from source without root privileges.

   3. Or use cvmfsexec to get CVMFS. This is a bit more complex, you can follow the instructions summarized also in this paper.

If user namespaces are not enabled, apptainer/singularity is not installed, and you have no root access to the host, then your use of apptainer/singularity will be very limited even if you install it with one of the three methods above. You need to request to your system administrator to either install Apptainer/Singularity or to enable user namespaces.