Running Containers on HPC

Last updated on 2025-11-12 | Edit this page

Estimated time: 30 minutes

Overview

Questions

  • How is Singularity different to Docker?
  • How do I use my Docker images on a shared HPC?

Objectives

  • Learn how to convert Docker images to SIF
  • Distinguish the run and exec subcommands
Callout

You can find more detail about using Singularity in the singularity-introduction Carpentries workshop.

Singularity is a container engine, like Docker and Podman. However, unlike Docker, container images are stored as single files called .sif (Singularity Image Format). For a number of reasons, Singularity suits shared High Performance Computing (HPC) environments much better than Podman/Docker, so is valuable to learn if you work in these environments. A related tool called Apptainer is a fork of Singularity that generally has the same command line interface.

Install Singularity/Apptainer

Singularity or Apptainer are installed on many HPC systems, often as a loadable module which can be accesed with the module load command.

If they are not installed you can install Apptainer yourself using the unprivileged pre-built binaries.

BASH 

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

Apptainer also has a symlink for the singularity command to run apptainer.

Discussion

Singularity Command Line Interface

Like we did with Docker, try to work out what commands Singularity has. Which one do you think is the equivalent of docker run?

singularity run behaves similarly to docker run, but as we will see, the arguments are somewhat different.

Running Docker Containers

Since Singularity containers have their own file format, if we have a Docker image we want to run, it first has to be converted. We can do this using singularity pull. For example, we can pull the container we previously pushed to Docker Hub:

BASH 

singularity pull docker://alice/alpine-python

This creates a file called alpine_python.sif in our working directory. To run this container, we then use singularity run:

BASH 

singularity run alpine_python.sif

Singularity Exec

If we want to modify the command run in the container, we have to use singularity exec. For example, to make Python add numbers like in our sum example, we could do:

BASH 

apptainer exec alpine_python.sif python -c 'print(1 + 1)'