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.
There are many ways to install Singularity but this quick start guide will only cover one.
git clone https://github.com/singularityware/singularity.git cd singularity ./autogen.sh ./configure --prefix=/usr/local make sudo make install
Singularity must be installed as root to function properly.
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.
--help option gives an overview of Singularity options and subcommands as
$ singularity --help USAGE: singularity [global options...] <command> [command options...] ... GLOBAL OPTIONS: -d|--debug Print debugging information -h|--help Display usage summary -s|--silent Only print errors -q|--quiet Suppress all normal output --version Show application version -v|--verbose Increase verbosity +1 -x|--sh-debug Print shell wrapper debugging information GENERAL COMMANDS: help Show additional help for a command or container selftest Run some self tests for singularity install CONTAINER USAGE COMMANDS: exec Execute a command within container run Launch a runscript within container shell Run a Bourne shell within container test Launch a testscript within container CONTAINER MANAGEMENT COMMANDS: apps List available apps within a container bootstrap *Deprecated* use build instead build Build a new Singularity container check Perform container lint checks inspect Display a container's metadata mount Mount a Singularity container image pull Pull a Singularity/Docker container to $PWD COMMAND GROUPS: image Container image command group instance Persistent instance command group CONTAINER USAGE OPTIONS: see singularity help <command> For any additional help or support visit the Singularity website: https://github.com/singularityware/singularity
For any additional help or support visit the Singularity website:
Singularity uses positional syntax. Global options follow the
invocation and affect the way that Singularity runs any command. Then
commands are passed followed by their options.
For example, to pass the
--debug option to the main
singularity command and run
Singularity with debugging messages on:
$ singularity --debug run shub://GodloveD/lolcow
And to pass the
--containall option to the
run command and run a Singularity image in an
$ singularity run --containall shub://GodloveD/lolcow
To learn more about a specific Singularity command, type one of the following:
$ singularity help <command> $ singularity --help <command> $ singularity -h <command> $ singularity <command> --help $ singularity <command> -h
Users can also write help docs specific to a container or for an internal module called an
app. If those help
docs exist for a particular container, you can view them like so.
$ 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,
simply downloads the image file to your system.
$ singularity pull shub://vsoch/hello-world # pull with default name, vsoch-hello-world-master.simg $ singularity pull --name hello.simg shub://vsoch/hello-world # pull with custom name
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.
$ singularity pull docker://godlovedc/lolcow # with default name $ singularity pull --name funny.simg docker://godlovedc/lolcow # with custom name
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:
$ singularity build hello-world.simg shub://vsoch/hello-world $ singularity build lolcow.simg docker://godlovedc/lolcow
build will convert your image to the latest Singularity image format
after downloading it.
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 <container-recipes>. 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
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.
$ singularity shell hello-world.simg Singularity: Invoking an interactive shell within container... # I am the same user inside as outside! Singularity hello-world.simg:~/Desktop> whoami vanessa Singularity hello-world.simg:~/Desktop> id uid=1000(vanessa) gid=1000(vanessa) groups=1000(vanessa),4(adm),24,27,30(tape),46,113,128,999(input)
shell also works with the
docker:// URIs. This creates an ephemeral container that
disappears when the shell is exited.
$ singularity shell shub://vsoch/hello-world
The exec command allows you to execute a custom command within a container by specifying the image file. For instance, to list the root (/) of our hello-world.simg image, we could do the following:
$ singularity exec hello-world.simg ls / anaconda-post.log etc lib64 mnt root singularity tmp bin home lost+found opt run srv usr dev lib media proc sbin sys var
exec also works with the
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
docker:// URIs. This creates an ephemeral container that runs
and then disappears.
$ singularity run shub://GodloveD/lolcow
Working with Files¶
Files on the host are reachable from within the container.
$ echo "Hello World" > $HOME/hello-kitty.txt $ singularity exec vsoch-hello-world-master.simg cat $HOME/hello-kitty.txt Hello World
This example works because
hello-kitty.txt exists in the user’s home directory. By
default singularity bind mounts
$PWD into your container at
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.
$ echo "I am your father" >/data/vader.sez $ ~/sing-dev/bin/singularity exec --bind /data:/mnt hello-world.simg cat /mnt/vader.sez I am your father
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.
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
You can use commands like
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
--writable option the changes will be saved into your directory so that you
can use them the next time you use your container.
If you prefer to have a writable image file, you can
build a container with
$ 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
--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¶
buildcommand 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
You can use
build to convert containers to and from
sandbox, and default
(squashfs) file formats via any of the six possible combinations.
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. Here is an example of a recipe file:
Bootstrap: shub From: singularityhub/ubuntu %runscript exec echo "The runscript is the containers default runtime command!" %files /home/vanessa/Desktop/hello-kitty.txt # copied to root of container /home/vanessa/Desktop/party_dinosaur.gif /opt/the-party-dino.gif # %environment VARIABLE=MEATBALLVALUE export VARIABLE %labels AUTHOR email@example.com %post apt-get update && apt-get -y install python3 git wget mkdir /data echo "The post section is where you can install, and configure your container."
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).
%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
executes within the container at build time after the base OS has been
%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
instead. If you want a more detailed rundown and examples for
different build options, see our singularity flow page.