This lesson is in the early stages of development (Alpha version)

Using Containers in HPC with Singularity


Teaching: 10 min
Exercises: 20 min
  • What is the difference between Docker and Singularity?

  • Why is Singularity more suitable for HPC?

  • Understand the main differences between Singularity and Docker.

  • Learn the basic commands of Singularity.

Quick Start

After having successfully installed Singularity on your system the initial step is to run your first container.

$ singularity run library://sylabsed/examples/lolcow

The leading library:// part in the image name tells Singularity to look for the image in the Singularity Cloud Library. This is the equivalent to Docker Hub in the Singularity world. The output will look something like this:

INFO:    Downloading library image
79.9MiB / 79.9MiB [======================================================================================================================================================] 100 % 11.6 MiB/s 0s
/ You are scrupulously honest, frank, and \
| straightforward. Therefore you have few |
\ friends.                                /
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Let’s try another example by running an Ubuntu image using Singularity. Therefore, let us use the library/default/ubuntu:20.04 image from the Singularity Cloud Library.

$ singularity run library://library/default/ubuntu:20.04

Using this command we are presented a shell inside the Ubuntu Singularity container. Once inside the container, you are the same user as you are on the host system.

Singularity> whoami

Singularity automatically makes your home directory (/home/$USER) available in the container. Unlike with Docker, it is not necessary to explicitly mount the directories. They are made available by default.

With Singularity, you can easily reuse existing Docker images from Docker Hub and run them as a Singularity container. Let us run the python:3.9 Docker image as a Singularity container. Therefore, we pull the image first.

$ singularity pull docker://python:3.9

This command downloads the image from Docker Hub (docker://) and converts it into the Singularity specific image format called SIF file. A file called python_3.9.sif was created in your current directory. Run it as shown below.

$ singularity run python_3.9.sif
Python 3.9.2 (default, Mar 12 2021, 18:54:15) 
[GCC 8.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.

Building Containers from Singularity Definition Files

As demonstrated in the Docker build lesson we want to build our first custom Singularity image as well. Therefore, we need to create the Singularity definition file, i.e. the equivalent to Dockerfile. We will recreate the lolcow image used for the first run command in this episode. Therefore, we create a file called lolcow.def using the editor of your choice. This file contains the construction manual for the Singularity image.

Bootstrap: docker
From: ubuntu:20.04

  apt-get -qy update
  apt-get -qy install fortune cowsay lolcat

  export LC_ALL=C
  export PATH=/usr/games:$PATH

  fortune | cowsay | lolcat

Build the image using the singularity build command.

$ sudo singularity build lolcow.sif lolcow.def

Note: The Singularity build command requires root privileges.

This command creates the file lolcow.sif. It is run using the singularity run command.

$ sudo singularity run lolcow.sif
/ Good day for overcoming obstacles. Try \
\ a steeplechase.                        /
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Let’s take apart the Singularity definition file.

Each Singularity definition file needs to start with the header part consisting of at least the Bootstrap keyword. In our example we use the docker bootstrap agent telling Singularity to get the image from a Docker registry. This agent needs to be combined with the From keyword to let Singularity know, which base image to use.

Bootstrap: docker
From: ubuntu:20.04

Use Images From Other Container Registries

If you want to use another registry, e.g. the GitLab container registry, it is easily possible. Specify the full name of the image according to the GitLab container registry naming convention as described in the documentation.

Generic example:

Bootstrap: docker
From: <registry URL>/<namespace>/<project>/<image>

A list of preferred bootstrap agents is available here.


The main content of the definition file is broken into sections. In our example we used three different sections:

Please refer to the official documentation for a complete list of available sections and their usage.

Singularity vs Docker in a Nutshell

  Docker Singularity
Isolation from host Shares little by default. Isolation not the primary focus. By default shares most everything.
Supported Host Operating Systems (OS) Windows, Mac, Linux Linux
Security Users running docker commands need to be in a special docker group to gain elevated system access. Users can run Singularity containers without special privileges.
Data Persistence No host filesystem available by default. Writable bind-mounts of the user home directory are automatically created.
Primary target group Developers, DevOps Scientific Application Users/Developers
HPC Not suitable for HPC: requires elevated permissions Integrates well with MPI, GPUs, Infiniband and Schedulers (e.g. SLURM)
Ecosystem Larger ecosystem; more sophisticated registries and preconfigured images Smaller ecosystem; is able to use Docker images.

Key Points

  • Use the singularity run command to run a Singularity image.

  • Define the construction manual of a Singularity image in a definitions file.

  • Singularity is more often available in HPC systems.