Apptainer
Apptainer is a container runtime and an open source fork of Singularity. Apptainer runs without root privileges and without a separate daemon process, which suits high-performance computing (HPC) environments. Apptainer can use existing Docker images and pull from Docker registries.
Prerequisites
Apptainer must be installed in your execution environment.
Images
To create Apptainer images, see the Apptainer documentation.
Apptainer 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 Apptainer in the Nextflow configuration file:
apptainer.enabled = true
process.container = '/path/to/apptainer.img'
Whenever your pipeline launches a task, Nextflow runs it inside an Apptainer container created from the specified image using the apptainer exec command.
You can also enable Apptainer on the command line:
nextflow run main.nf -with-apptainer
Nextflow automatically mounts the required host paths in the container. This requires the user bind control feature in your Apptainer installation. To disable automatic mounts, set apptainer.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 Apptainer installation. Otherwise, the task fails because the container cannot access the linked file.
Nextflow no longer mounts the home directory when launching an Apptainer container. To re-enable the old behavior, set the environment variable NXF_APPTAINER_HOME_MOUNT to true.
Apptainer and Docker Hub
Nextflow can pull remote container images from any Docker-compatible registry. This requires Apptainer 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:
apptainer.enabled = true
process.container = 'file:///path/to/apptainer.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://, or docker-daemon:// as required by Apptainer. For example:
apptainer.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 Apptainer is enabled, Nextflow prepends it to your image name. The Docker engine does not work with containers specified as docker://.
By default, Nextflow caches Apptainer images in the apptainer directory, in the pipeline work directory. Use the NXF_APPTAINER_CACHEDIR environment variable or the apptainer.cacheDir config setting to define a centralized cache directory.
Nextflow uses the library directory to determine the location of local Apptainer container images. Use the NXF_APPTAINER_LIBRARYDIR environment variable or the apptainer.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 Apptainer cache directory must reside on a shared file system that all compute nodes can access.
When pulling Docker images, Apptainer cannot determine the container size if the image uses an old Docker format. The pipeline execution then fails with an error. See the Apptainer documentation for details.
Advanced settings
See the apptainer configuration scope for advanced Apptainer settings.