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.
Installation
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.
The --help option gives an overview of Singularity options and subcommands as follows:
$ 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: http://singularity.lbl.gov/
Singularity uses positional syntax. Global options follow the singularity 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 isolated manner:
$ 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, pull 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
Unlike pull, 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. 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.
$ 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 shub:// and docker:// URIs. This creates an ephemeral container that disappears when the shell is exited.
$ singularity shell shub://vsoch/hello-world
Executing Commands
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 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.
$ 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 /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.
$ 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.
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.
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 vsochat@stanford.edu
%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). 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