Software requirements

The keywords “MUST”, “MUST NOT”, “SHOULD”, etc. are to be interpreted as described in RFC 2119.

BioContainers is a registry of Docker and Singularity containers automatically created from all of the software packages on Bioconda. Where possible nf-core will use BioContainers to fetch pre-built software containers and Bioconda to install software using Conda.

1 Use of container directives

Software requirements SHOULD be declared within the module file using the Nextflow container directive. For single-tool BioContainers, the nf-core modules create command will automatically fetch and fill in the appropriate Conda / Docker / Singularity definitions by parsing the information provided in the first part of the module name:

conda "bioconda::fastqc=0.11.9"
container "${ workflow.containerEngine == 'singularity' && !task.ext.singularity_pull_docker_container ?
    'https://depot.galaxyproject.org/singularity/fastqc:0.11.9--0' :
    'biocontainers/fastqc:0.11.9--0' }"

2 Use of conda directive

If the software is available on Conda, also define it in an environment.yml file alongside the main.nf of the module, and pass it to the Nextflow conda directive within main.nf.

Using bioconda::bwa=0.7.17 as an example, pin software to the channel (i.e., bioconda) and version (i.e., 0.7.17).

Do not pin Conda packages to a build because they can vary on different platforms.

3 Re-use of multi-tool containers

Multi-tool containers are also available on BioContainers. For example, bwa and samtools. Install and use the galaxy-tool-util package to search for both single- and multi-tool containers available in Conda, Docker and Singularity format. For example, to search for Docker (hosted on Quay.io) and Singularity multi-tool containers with both bowtie and samtools installed, use the following command:

mulled-search --destination quay singularity --channel bioconda --search bowtie samtools | grep "mulled"

4 Creation of new multi-tool containers

It is also possible for a new multi-tool container to be built and added to BioContainers by submitting a pull request on their multi-package-containers repository.

• Fork the multi-package-containers repository

• Make a change to the hash.tsv file in the combinations directory see here for an example where pysam=0.16.0.1,biopython=1.78 was added.

• Commit the code and then make a pull request to the original repo, for example

• Once the PR has been accepted a container will get built and you can find it using a search tool in the galaxy-tool-util conda package

  mulled-search --destination quay singularity conda  --search pysam biopython  | grep "mulled"
  quay         mulled-v2-3a59640f3fe1ed11819984087d31d68600200c3f  185a25ca79923df85b58f42deb48f5ac4481e91f-0  docker pull quay.io/biocontainers/mulled-v2-3a59640f3fe1ed11819984087d31d68600200c3f:185a25ca79923df85b58f42deb48f5ac4481e91f-0
  singularity  mulled-v2-3a59640f3fe1ed11819984087d31d68600200c3f  185a25ca79923df85b58f42deb48f5ac4481e91f-0  wget https://depot.galaxyproject.org/singularity/mulled-v2-3a59640f3fe1ed11819984087d31d68600200c3f:185a25ca79923df85b58f42deb48f5ac4481e91f-0

• Copy and paste the mulled-* path into the relevant Docker and Singularity lines in the Nextflow process definition of the module

• To confirm that this is correct, spin up a temporary Docker container:

  docker run --rm -it quay.io/biocontainers/mulled-v2-3a59640f3fe1ed11819984087d31d68600200c3f:185a25ca79923df85b58f42deb48f5ac4481e91f-0  /bin/sh

  And in the command prompt type:

  $ grep specs /usr/local/conda-meta/history
  # update specs: ['biopython=1.78', 'pysam=0.16.0.1']

  The packages should reflect those added to the multi-package-containers repo hash.tsv file.

• If the multi-tool container already exists, use this helper tool to obtain the mulled-* path.

5 GPU-capable modules

Modules MAY provide GPU-accelerated containers. One of three container approaches SHOULD be chosen according to the tool:

• A single container, when GPU overhead is minimal or a CPU fallback fits in one image. This is simplest and preferred.
• A dual CPU/GPU container, when the GPU build is substantially larger (e.g., CUDA PyTorch). The module SHOULD switch containers based on task.accelerator, and a separate environment.gpu.yml SHOULD be provided for the GPU dependencies. The CPU environment.yml MUST remain unchanged.
• A vendor-provided GPU container, when no conda equivalent exists (e.g., NVIDIA Parabricks). These modules SHOULD guard against conda/mamba profiles.

GPU containers SHOULD be built with Wave, and both Docker and Singularity URLs MUST be provided. cuda-version MUST be pinned exactly; version ranges are not allowed. GPU modules SHOULD emit the CUDA runtime version on the versions topic channel. Tools that provide separate GPU and CPU binaries SHOULD select between them based on task.accelerator.

For the dual-container pattern, CUDA version pinning strategy, runtime configuration, GPU-enabled Python packages, and worked examples, see the GPU-capable modules guide.

6 Software not on Bioconda

If the software is not available on Bioconda a Dockerfile MUST be provided within the module directory. nf-core will use GitHub Actions to auto-build the containers on the GitHub Packages registry.