Singularity
Singularity is a container runtime. Singularity runs without root privileges and without a separate daemon process, which suits high-performance computing (HPC) environments. Singularity can use existing Docker images and pull from Docker registries.
Prerequisites
Singularity must be installed in your execution environment.
Images
To create Singularity images, see the Singularity documentation.
Singularity can create and mount paths that do not exist in the container when you specify them on the command line. This feature requires a host that supports the Overlay file system and is disabled by default.
How it works
Enable Singularity in the Nextflow configuration file:
singularity.enabled = true
process.container = '/path/to/singularity.img'
Whenever your pipeline launches a task, Nextflow runs it inside a Singularity container created from the specified image using the singularity exec command.
You can also enable Singularity on the command line:
nextflow run main.nf -with-singularity
Nextflow automatically mounts the required host paths in the container. This requires the user bind control feature in your Singularity installation. To disable automatic mounts, set singularity.autoMounts to false.
When a process input is a symbolic link, store the linked file in a host directory that is accessible from a bind path defined in your Singularity installation. Otherwise, the task fails because the container cannot access the linked file.
Nextflow no longer mounts the home directory when launching a Singularity container. To re-enable the old behavior, set the environment variable NXF_SINGULARITY_HOME_MOUNT to true.
Nextflow mounts host paths in the container automatically. To re-enable the old behavior, set the environment variable NXF_SINGULARITY_AUTO_MOUNTS to false.
To set the execution command for Singularity and Apptainer containers to run, set the environment variable NXF_SINGULARITY_RUN_COMMAND. The default command is exec.
Singularity and Docker Hub
Nextflow can pull remote container images from the Singularity Library or any Docker-compatible registry. This requires Singularity in the launch environment, not on the compute nodes.
When you specify a container name, Nextflow first checks whether an image file with that name exists in the local file system. If it does, Nextflow uses that file to execute the container. If it does not, Nextflow pulls an image with that name from the container registry.
To use only local file images, prefix the container name with file://. For example:
singularity.enabled = true
process.container = 'file:///path/to/singularity.img'
Use three / slashes to specify an absolute file path. Otherwise, Nextflow interprets the path as relative to the workflow launch directory.
To pull an image from a specific registry, prefix the image name with shub://, docker://, docker-daemon://, or library:// as required by Singularity. For example:
singularity.enabled = true
process.container = 'docker://quay.io/biocontainers/multiqc:1.3--py35_2'
You do not need to specify docker:// to pull from a Docker registry. When Singularity is enabled, Nextflow prepends it to your image name. The Docker engine does not work with containers specified as docker://.
By default, Nextflow caches Singularity images in the singularity directory, in the pipeline work directory. Use the NXF_SINGULARITY_CACHEDIR environment variable or the singularity.cacheDir config setting to define a centralized cache directory.
Nextflow uses the library directory to determine the location of local Singularity container images. Use the NXF_SINGULARITY_LIBRARYDIR environment variable or the singularity.libraryDir config setting to define it. The configuration file option overrides the environment variable if both are set.
When resolving a container image, Nextflow first checks the library directory, then the cache directory. Use the library directory as a read-only container repository, and the cache directory as a writable location where container images can be cached.
On a compute cluster, the Singularity cache directory must reside on a shared file system that all compute nodes can access.
When pulling Docker images, Singularity cannot determine the container size if the image uses an old Docker format. The pipeline execution then fails with an error. See the Singularity documentation for details.
Advanced settings
See the singularity configuration scope for advanced Singularity settings.