Quick Start

These docs are for Singularity Version 2.5.1. For older versions, see our archive

This guide is intended for running Singularity on a computer where you have root (administrative) privileges. If you are learning about Singularity on a system where you lack root privileges, you can still complete the steps that do not require the sudo command. If you need to request an installation on your shared resource, check out our requesting an installation help page for information to send to your system administrator.

Overview of the Singularity Interface

Singularity’s command line interface allows you to build and interact with containers transparently. You can run programs inside a container as if they were running on your host system. You can easily redirect IO, use pipes, pass arguments, and access files, sockets, and ports on the host system from within a container.

The --help option gives an overview of Singularity options and subcommands as follows:

$ singularity help container.simg # See the container's help, if provided
$ singularity help --app foo container.simg # See the help for foo, if provided

Download pre-built images

You can use the pull and build commands to download pre-built images from an external resource like Singularity Hub or Docker Hub. When called on a native Singularity images like those provided on Singularity Hub, pull simply downloads the image file to your system.

Singularity images can also be pulled and named by an associated GitHub commit or content hash.

You can also use pull with the docker:// uri to reference Docker images served from a registry. In this case pull does not just download an image file. Docker images are stored in layers, so pull must also combine those layers into a usable Singularity file.

Pulling Docker images reduces reproducibility. If you were to pull a Docker image today and then wait six months and pull again, you are not guaranteed to get the same image. If any of the source layers has changed the image will be altered. If reproducibility is a priority for you, try building your images from Singularity Hub.

You can also use the build command to download pre-built images from an external resource. When using build you must specify a name for your container like so:

build is like a “Swiss Army knife” for container creation. In addition to downloading images, you can use build to create images from other images or from scratch using a recipe file. You can also use build to convert an image between the 3 major container formats supported by Singularity. We discuss those image formats below in the Build images from scratch section.

Interact with Images

Once you have an image, you can interact with it in several ways. For these examples we will use a hello-world.simg image that can be downloaded from Singularity Hub like so.

$ singularity pull --name hello-world.simg shub://vsoch/hello-world

Shell

The shell command allows you to spawn a new shell within your container and interact with it as though it were a small virtual machine.

exec also works with the shub:// and docker:// URIs. This creates an ephemeral container that executes a command and disappears.

$ singularity exec shub://singularityhub/ubuntu cat /etc/os-release

Running a container

Singularity containers contain “runscripts”. These are user defined scripts that define the actions a container should perform when someone runs it. The runscript can be triggered with the run command, or simply by calling the container as though it were an executable.

$ singularity run hello-world.simg
$ ./hello-world.simg

run also works with shub:// and docker:// URIs. This creates an ephemeral container that runs and then disappears.

Working with Files

This example works because hello-kitty.txt exists in the user’s home directory. By default singularity bind mounts /home/$USER, /tmp, and $PWD into your container at runtime.

You can specify additional directories to bind mount into your container with the --bind option. In this example, the /data directory on the host system is bind mounted to the /mnt directory inside the container.

Build images from scratch

As of Singularity v2.4 by default build produces immutable images in the squashfs file format. This ensures reproducible and verifiable images.

However, during testing and debugging you may want an image format that is writable. This way you can shell into the image and install software and dependencies until you are satisfied that your container will fulfill your needs. For these scenarios, Singularity supports two other image formats: a sandbox format (which is really just a chroot directory), and a writable format (the ext3 file system that was used in Singularity versions less than 2.4).

For more details about the different build options and best practices, read about the singularity flow.

Sandbox Directory

To build into a sandbox (container in a directory) use the build --sandbox command and option:

$ sudo singularity build --sandbox ubuntu/ docker://ubuntu

This command creates a directory called ubuntu/ with an entire Ubuntu Operating System and some Singularity metadata in your current working directory.

You can use commands like shell, exec, and run with this directory just as you would with a Singularity image. You can also write files to this directory from within a Singularity session (provided you have the permissions to do so). These files will be ephemeral and will disappear when the container is finished executing. However if you use the --writable option the changes will be saved into your directory so that you can use them the next time you use your container.

Writable Image

If you prefer to have a writable image file, you can build a container with the --writable option.

$ sudo singularity build --writable ubuntu.img docker://ubuntu

This produces an image that is writable with an ext3 file system. Unlike the sandbox, it is a single image file. Also by convention this file name has an “.img” extension instead of “.simg” .

When you want to alter your image, you can use commands like shell, exec, run, with the --writable option. Because of permission issues it may be necessary to execute the container as root to modify it.

$ sudo singularity shell --writable ubuntu.img

Converting images from one format to another

The build command allows you to build a container from an existing container. This means that you can use it to convert a container from one format to another. For instance, if you have already created a sandbox (directory) and want to convert it to the default immutable image format (squashfs) you can do so:

$ singularity build new-squashfs sandbox

Doing so may break reproducibility if you have altered your sandbox outside of the context of a recipe file, so you are advised to exercise care.

You can use build to convert containers to and from writable, sandbox, and default (squashfs) file formats via any of the six possible combinations.

Singularity Recipes

For a reproducible, production-quality container, we recommend that you build a container with the default (squashfs) file format using a Singularity recipe file. This also makes it easy to add files, environment variables, and install custom software, and still start from your base of choice (e.g., Singularity Hub).

A recipe file has a header and a body. The header determines what kind of base container to begin with, and the body is further divided into sections (called scriptlets) that do things like install software, setup the environment, and copy files into the container from the host system.

To build a container from this definition file (assuming it is a file named Singularity), you would call build like so:

$ sudo singularity build ubuntu.simg Singularity

In this example, the header tells singularity to use a base Ubuntu image from Singularity Hub. The %runscript section defines actions for the container to take when it is executed (in this case a simple message). The %files section copies some files into the container from the host system at build time. The %environment section defines some environment variables that will be available to the container at runtime. The %labels section allows for custom metadata to be added to the container. And finally the %post section executes within the container at build time after the base OS has been installed. The %post section is therefore the place to perform installations of custom apps.

This is a very small example of the things that you can do with a recipe file. In addition to building a container from Singularity Hub, you can start with base images from Docker Hub, use images directly from official repositories such as Ubuntu, Debian, Centos, Arch, and BusyBox, use an existing container on your host system as a base, or even take a snapshot of the host system itself and use that as a base image.

If you want to build Singularity images without having singularity installed in a build environment, you can build images using Singularity Hub instead. If you want a more detailed rundown and examples for different build options, see our singularity flow page