Skip to content

Apptainer: Apptainer Container System

Overview of package

Package: Apptainer
Description: Apptainer Container System
For more information: https://apptainer.org/
Categories: SoftwareDevelopment
Utilities
License: OpenSource (BSD-3 clause)

General Usage

Apptainer (formerly Singularity) is a secure and portable container system which works well with HPC systems.

This module will add the apptainer command to your path. You can use that to run container images that you built, downloaded from the web, or otherwise obtained. Due to the portability of containers, containers generated on other systems generally will run on Zartan.

Available versions by cluster

This section lists the available versions of the package Apptaineron the UMD HPC clusters.

Versions available on the Zaratan cluster

Version Module tags CPU(s) optimized for GPU ready?
1.3.6 1.3.6 x86_64 Yes

What is Apptainer?

Apptainer (formerly known as Singularity) is container platform, similar to Docker, but specifically designed to meet the requirements of HPC clusters.

Container platforms allow software to be packaged into containers which can encapsulare the desired software package(s) and all of their dependencies typically in a single file. These containers are quite portable; a container generated on one platform or cluster can generally be run on other platforms/clusters.

The containers are quite isolated from the computer environment on which they are running; this is what makes them portable. But that isolation has some costs --- generally the containers will not be able to avail themselves of software in the Research Software Library (RSWL) or other software the installed on the system. However, this also means that the containers are not dependent on the exact software packages and versions installed on the system; depending on what you are trying to do containers might or might not make sense.

Containerization platforms like Apptainer provide more isolation from system software than Python virtual environments or Conda environments. Containers are, however, less isolated than virtual machines; the container shares the kernel and hardware drivers and actual hardware with the system the container being run on. As such, only containers for built for Linux and a compatible architecture (e.g. x86_64) can be run on the Zaratan cluster. You can generally use containers built upon other distributions of Linux (e.g. Debian, Ubuntu, etc.).

Performance of codes inside a container are generally the same as for natively installed packages.

Using Apptainer

Apptainer has a command line interface from which you can build, run, and interact with containers. The command line will allow you to redirect I/O, use pipes, pass arguments, etc.

Apptainer users a positional syntax, so the order of commands and options matter. Global options should be given immediately after the apptainer command, followed by the the subcommand and then the options and arguments for the subcommand.

The rest of this is only a quick guide to some of the most common commands, for more detail see the Apptainer Documentation page especially the quick start page.

The most commonly used subcommands are:

  • help to get usage help
  • pull downloads a container the web, etc.
  • run to run the container's default command inside the container
  • exec runs a command inside the container
  • shell starts a shell inside the container
  • build builds a container

Help

The command apptainer help will display a basic usage screen for the command.

Pull: Downloading images

You can download a container from the web using the apptainer pull command. You will need to provide an URI to the container you wish to download. There are some special URI schemes (the part before the ://) available for this: - 'docker://' This will download Docker formatted (e.g. OCI format) containers. Apptainer will call the build subcommand under the hood to convert the container to the Apptainer sif file.
- 'oras://' This will download from an OCI registry which supports OCI artifacts - 'library://' This will download from the Library API Container Registries - 'shub://' Download from the Singularity Hub

The following command download a container with the lolcow application. The downloaded container will be saved to lolcow_latest.sif (about 75 MB). This is just a "toy" application which outputs an ASCII art picture of a cow with specified text in a quotation or thought bubble.

Example

apptainer pull docker://ghcr.io/apptainer/lolcow

Run, Exec, and Shell Subcommands

The run, exec, and shell subcommands all execute commands within the containarized environment. In each case, you should provide the path to the container file on the cluster as the first argument after the subcommand.
While in theory you can pass an URI to a container on the web, containers should generally only be run on the compute nodes which do not have public internet access, so you should download the container on the login node first, and then run the downloaded container on the compute node.

Containers generally contain runscripts which defines what the container should do when someone "runs" it. Typically these runscripts will run the application you downloaded the container for, but this is up to the container creator.

To run the container (or more precisely the runscript for the container) you can use the run subcommand. This can be followed by arguments (depending on how the container was created, arguments might or might not be used). You can also just run the container directly, as if it were a command (you will need to add the execute permission to the downloaded container file with the chmod command).

continuing with our previous lolcow example, the runscript will have the "cow" tell you the current time. You can obtain this with

Example

login-1: apptainer run ./lolcow_latest.sif
 _____________________________
< Wed Mar 5 13:31:24 EST 2025 >
 -----------------------------
    \   ^__^
     \  (oo)\_______
        (__)\       )\/\
        ||----w |
        ||     ||

You can do the sane thing with:

Example

login-1: chmod u+x ./lolcow_latest.sif
login-1: ./lolcow_latest.sif
 _____________________________
< Wed Mar 5 13:31:28 EST 2025 >
 -----------------------------
    \   ^__^
     \  (oo)\_______
        (__)\       )\/\
        ||----w |
        ||     ||

More generally, you can use the exec subcommand to run an arbitrary command inside the container environment. The exec subcommand should be followed by the path to the container, then by the path to the command to run inside the container and any arguments to that command. Typically the common commands which you would tend to use are in the default PATH for use inside the container, so usually you will not need to give more than command name.

Returning our lolcow example, the container defines the cowsay and cowthink commands, which we can use with something like:

Example

login-1: apptainer exec ./lolcow_latest.sif cowsay 'Go Terps!'
 ___________
< Go Terps! >
 -----------
    \   ^__^
     \  (oo)\_______
        (__)\       )\/\
        ||----w |
        ||     ||
 login-1: apptainer exec lolcow_latest.sif cowthink  'fearless ideas' 
 ________________
( fearless ideas )
 ----------------
    o   ^__^
     o  (oo)\_______
        (__)\       )\/\
        ||----w |
        ||     ||

For more interactive use, you can use the shell subcommand. This will open a shell session inside the named container, and you can then interactively run commands inside the container. This is often useful when you are testing a container you just built, or exploring a newly downloaded container.

Back to our lolcow example:

Example

login-1: apptainer shell lolcow_latest.sif 
Apptainer> cowsay  'Go Terps!'
 ___________
< Go Terps! >
 -----------
    \   ^__^
     \  (oo)\_______
        (__)\       )\/\
        ||----w |
        ||     ||
Apptainer> exit
exit
login-1:

Build subcommand

The build subcommand can be used to create containers, or to convert containers from one format to another. Building containers can be quite complex, and so this section only touches on some of the highlights. See the Apptainer online documentation for more information.

General usage of this subcommand is apptainer build OPTIONAL_FLAGS IMAGE_PATH BUILD_SPEC

The IMAGE_PATH is the path to which the new container will be built. This will normally be default Apptainer SIF (Singularity Image Format), which is a read-only compressed file format. This is the best format for finished containers, but the read-only nature often makes it less than desireable for active development. For development work, you might wish to use the --sandbox flag and provide the path to a directory to store a sandbox format container. This is a writable constainer format. Often it works best to develop the container in a sandbox format and then convert to SIF format (using the build subcommand) when done.

The BUILD_SPEC can be an URI, using the same schemas and format as for the pull subcommand, or the path to an existing container image or sandbox directory, or the path to a Apptainer container definition file.

If you provide an URI, or the path to an existing container file or sandbox container directory, the build command will convert the container into SIF format. (The pull subcommand will sometimes do that behind the scenes for Docker and other image formats that use overlays and cannot be represented in a single file).

You can also provide a definition file which will specify how the container should be created. Using definition files is a powerful way to construct containers, giving you full control and reproducibility, but is really too complex to discuss here. For more information about definition files, please see: