Singularity runtime

Run commands inside a container image using Singularity.

Singularity is a container system freely-available for Linux platforms. It is commonly available on institutional HPC systems as an alternative to Docker, which is often not supported on such systems. When you use Singularity with the Nextstrain CLI, you don’t need to install any other Nextstrain software dependencies as validated versions are already bundled into a container image by the Nextstrain team.

The Singularity runtime uses the same images built for the Docker runtime by automatically converting them to local Singularity images. Local images are stored as files named ~/.nextstrain/runtimes/singularity/images/repository/tag.sif.

Added in version 6.1.0.

Setup

Run nextstrain setup singularity to get started. Singularity version 3.0.0 or newer is required, but we recommend at least version 3.10.0 or newer when possible.

This will download image layers totaling about 750 MB in size which are converted to a final on-disk image of about 650 MB. Transient disk usage during this process peaks at about 2 GB. These numbers are current as of August 2023, as observed on Linux. Numbers will vary over time, with a tendency to slowly increase, and vary slightly by OS.

Note that the Singularity project forked into two separate projects in late 2021: SingularityCE under Sylabs and Apptainer under the Linux Foundation. Either fork should work with Nextstrain CLI, as both projects still provide very similar interfaces and functionality via the singularity command. You can read Sylab’s announcement and Apptainer’s announcement for more information on the fork.

Config file variables

Defaults for the corresponding command line options, specified in the config file.

singularity.image

Default for --image when using the Singularity runtime, e.g. docker://nextstrain/base:build-20230525T143814Z.

Typically set initially by nextstrain setup and subsequently by nextstrain update.

Environment variables

Warning

For development only. You don’t need to set these during normal operation.

Defaults for the corresponding command line options, potentially overriding defaults set by config file variables.

NEXTSTRAIN_SINGULARITY_IMAGE: Default for --image when using the Singularity runtime.