---
title: Singularity
description: Run Nextflow pipeline tasks in Singularity containers, including image caching and Docker registry support.
---

# Singularity

[Singularity](https://sylabs.io/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](https://www.sylabs.io/docs/).

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](https://en.wikipedia.org/wiki/OverlayFS) and is disabled by default.

## How it works

Enable Singularity in the Nextflow configuration file:

```groovy
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:

```bash
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`.

:::warning
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.
:::

<ChangedInVersion version="23.10">
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`.
</ChangedInVersion>

<ChangedInVersion version="23.10">
Nextflow mounts host paths in the container automatically. To re-enable the old behavior, set the environment variable `NXF_SINGULARITY_AUTO_MOUNTS` to `false`.
</ChangedInVersion>

<ChangedInVersion version="23.10">
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`.
</ChangedInVersion>

## Singularity and Docker Hub

Nextflow can pull remote container images from the [Singularity Library](https://cloud.sylabs.io/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:

```groovy
singularity.enabled = true
process.container = 'file:///path/to/singularity.img'
```

:::warning
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:

```groovy
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.

:::note
On a compute cluster, the Singularity cache directory must reside on a shared file system that all compute nodes can access.
:::

:::warning
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`][config-singularity] configuration scope for advanced Singularity settings.

[config-singularity]: ../reference/config/singularity
