Nextflow

Nextflow

Overview

Nextflow is a workflow language and runtime for building reproducible, portable, scalable data pipelines. It is dominant in bioinformatics but works for any data-heavy computation. nf-core is a community curating production-grade Nextflow pipelines, reusable modules, and the nf-core tooling on top of Nextflow.

Key ideas:

• Dataflow programming: pipelines are process tasks connected by channels. Nextflow infers execution order and parallelism from data dependencies — there is no explicit scheduler to write.
• Write once, run anywhere: the same pipeline runs locally, on HPC (SLURM, SGE, LSF, PBS), and on cloud (AWS Batch, Google Batch, Azure Batch, Kubernetes) by changing config/profiles, not code.
• Reproducibility: per-task containers (Docker/Singularity/Apptainer/Conda/Wave) + -resume caching + pinned pipeline revisions.
• DSL2 is the modern, required syntax: modular process/workflow/include definitions.

This skill covers both running existing pipelines and developing your own (Nextflow language + nf-core conventions, testing with nf-test, configuration, and deployment).

When to Use This Skill

Use this skill when the user wants to:

• Run an nf-core or custom Nextflow pipeline, or debug a failing/resuming run.
• Write or modify .nf scripts, nextflow.config, profiles, or nextflow_schema.json.
• Author or test nf-core-style modules/subworkflows (main.nf, meta.yml, tests/, nf-test).
• Configure executors, containers, or resources; scale to HPC or cloud.
• Build a reproducible scientific/bioinformatics workflow (even if "Nextflow" is not named).
• Understand processes, channels, operators, take/emit, publishDir, ext.args, meta maps.

Setup

Nextflow needs Bash and Java 17 or newer (17–25 supported). Verify with java -version.

# Install Nextflow (self-contained launcher)
curl -s https://get.nextflow.io | bash      # creates ./nextflow
sudo mv nextflow /usr/local/bin/             # put on PATH
nextflow info                                # verify

# Or via conda/bioconda (also gets a managed Java)
conda create -n nf -c bioconda -c conda-forge nextflow nf-core

# nf-core tools (Python) for creating/linting/running nf-core assets
pip install nf-core            # or: conda install -c bioconda nf-core
nf-core --version

Pin the engine for reproducibility: export NXF_VER=24.10.0 (use an [edge] release only if needed). For air-gapped/HPC, see references/running-pipelines.md (offline mode) and references/configuration.md.

Two Modes of Work

Decide which path the user is on — it changes everything:

Quick Start

Run an nf-core pipeline

Always smoke-test with the bundled test profile first; it uses tiny data and proves your environment works.

# 1. Confirm setup works (downloads pipeline + tiny test data)
nextflow run nf-core/rnaseq -profile test,docker --outdir results

# 2. Real run: pin a revision (-r), pick a container engine, pass inputs
nextflow run nf-core/rnaseq -r 3.14.0 \
  -profile docker \
  --input samplesheet.csv \
  --genome GRCh38 \
  --outdir results \
  -resume

• -profile (single dash) selects bundled config profiles; combine them comma-separated, e.g. test,docker. Container/infra profiles (docker, singularity, conda) are mutually exclusive — pick one.
• --input, --genome, --outdir (double dash) are pipeline parameters. nf-core pipelines take a samplesheet CSV, not loose files.
• -resume reuses cached results from the last run. -r <version> pins a release for reproducibility.

Use nf-core pipelines launch <name> for an interactive, schema-validated way to build the command and a -params-file. See references/running-pipelines.md.

Write a minimal pipeline

#!/usr/bin/env nextflow

process SAYHELLO {
    tag "$greeting"
    publishDir "results", mode: 'copy'

    input:
    val greeting

    output:
    path "${greeting}.txt"

    script:
    """
    echo '$greeting world' > ${greeting}.txt
    """
}

workflow {
    channel.of('hello', 'bonjour', 'hola') | SAYHELLO
}

nextflow run main.nf            # add -resume on reruns

The full language (processes, channels, operators, DSL2 workflows with take/main/emit, modules) is in references/language.md.

Core Concepts at a Glance

• Process: a unit of work that runs a script (Bash by default). Declares input:, output:, optional directives (resources, container, publishDir, tag, errorStrategy), and a script:/shell:/exec: block. Each task runs in its own isolated work directory (work/xx/yy…).
• Channel: the async queues that connect processes. Queue channels are consumable streams; value channels hold a single reusable value. Created with factories like channel.of, channel.fromPath, channel.fromFilePairs, channel.value.
• Operator: transforms/combines channels — map, filter, collect, groupTuple, join, combine, mix, flatten, branch, multiMap, splitCsv, view, set.
• Workflow: composes processes. DSL2 workflows can declare take: (inputs), main: (logic), emit: (named outputs) and be included as subworkflows. The unnamed workflow {} is the entry point.
• Module: a .nf file exposing processes/workflows via include { NAME } from './path' (supports as aliasing).
• Configuration: nextflow.config sets params, process directives, executor, container engines, and named profiles. Selectors withName:/withLabel: target specific processes. See references/configuration.md.
• meta map (nf-core): the convention of carrying a metadata map ([ id:'sample1', single_end:false ]) alongside files in input/output tuples so samples stay labeled through the pipeline. See references/developing.md.

nf-core tools CLI

nf-core tools (v3+) group subcommands under pipelines, modules, and subworkflows. (Bare forms like nf-core lint still work but warn — prefer the grouped form.)

Full command reference, flags, and examples: references/nf-core-tools.md.

Essential nextflow CLI

Config, executors, caching internals, and tracing details: references/configuration.md.

Best Practices (high-value habits)

• Always `test` first: -profile test,docker (or singularity/conda) before real data — fast and catches environment problems.
• Pin everything: pipeline revision (-r), NXF_VER, and tool versions (containers). Don't run latest for science you'll publish.
• Use `-resume` and understand caching: a task re-runs if its inputs, script, or container change. See cache-debugging in references/configuration.md.
• Parameterize via config/params-file, not hardcoded paths. Keep params and profiles in nextflow.config.
• One container/conda env per process; never rely on tools installed on the host.
• For nf-core dev: reuse existing modules (nf-core modules install) before writing new ones; pass tool flags through ext.args (not hardcoded in the script); always include a stub: block and nf-test tests; run nf-core pipelines lint and prettier before committing.
• Right-size resources with process_low/medium/high labels and errorStrategy 'retry' with dynamic task.attempt scaling instead of one giant request.
• Write forward-compatible syntax: the strict-syntax parser becomes the default in Nextflow 26.04. Prefer lowercase channel.of(...), explicit closure params ({ v -> ... }), def for all variables, and emit:-named outputs. Check with nextflow lint.

Reference Files

Read the relevant file when you need depth — each is self-contained:

• references/language.md — DSL2 language: processes, directives, channels, operators, workflows (take/emit), modules, dynamic resources, error handling.
• references/configuration.md — nextflow.config, scopes, profiles, withName/withLabel selectors, executors (local/SLURM/cloud), caching/-resume internals, tracing/reports, the nextflow CLI.
• references/containers.md — Docker, Singularity/Apptainer, Podman, Conda, Wave containers; choosing and enabling engines; common gotchas.
• references/running-pipelines.md — finding/running nf-core pipelines, samplesheets, params files, reference genomes (iGenomes), offline runs, institutional configs, Seqera Platform.
• references/nf-core-tools.md — complete nf-core CLI reference (pipelines/modules/subworkflows), flags, and workflows.
• references/developing.md — authoring nf-core pipelines & modules: template layout, module main.nf/meta.yml, meta maps, ext.args/modules.config, subworkflows, resource labels, linting & Harshil alignment style.
• references/testing.md — nf-test for modules/subworkflows/pipelines: test structure, assertions, snapshots, tags, running tests, CI.

Official docs: Nextflow https://www.nextflow.io/docs/latest/ · nf-core https://nf-co.re/docs/ · Training https://training.nextflow.io/

Nextflow Configuration, Executors & CLI

How to configure, scale, cache, observe, and drive Nextflow runs. Source: https://www.nextflow.io/docs/latest/config.html and related pages.

Table of Contents

• nextflow.config and scopes
• Profiles
• Process selectors
• Executors
• Cloud executors
• Caching and -resume
• Tracing and reports
• The nextflow CLI
• Environment variables

nextflow.config and scopes

nextflow.config configures a run without touching pipeline code. Files are auto-loaded and merged in increasing precedence: (1) $NXF_HOME/config (~/.nextflow/config), (2) nextflow.config in the project dir (where the script lives), (3) nextflow.config in the launch dir (current working dir), (4) each -c custom.config (repeatable). Using -C file instead loads only that file and ignores every other source. CLI --param/-params-file override config params. Values are grouped into scopes.

// nextflow.config
params {
    input  = null
    outdir = 'results'
    genome = 'GRCh38'
}

process {
    cpus   = 2
    memory = '4 GB'
    errorStrategy = 'retry'
    maxRetries    = 2
    container = 'ubuntu:22.04'
}

executor {
    queueSize     = 100        // max parallel tasks submitted
    submitRateLimit = '10/1min'
}

docker.enabled = true          // pick ONE container engine
// singularity.enabled = true
// conda.enabled = true

timeline.enabled = true
report.enabled   = true
trace.enabled    = true

manifest {
    name = 'my/pipeline'
    nextflowVersion = '!>=24.04.0'   // enforce a minimum engine version
}

Key scopes: params, process, executor, docker/singularity/apptainer/podman/conda/wave, aws/google/azure/k8s, tower (Seqera Platform), report/timeline/trace/dag, manifest, env, cleanup.

Assignment uses =. Use the dotted form (docker.enabled = true) or block form (docker { enabled = true }) interchangeably.

Profiles

A profile is a named bundle of config, activated with -profile. nf-core pipelines ship profiles for each container engine plus a test profile.

profiles {
    standard { process.executor = 'local' }

    docker      { docker.enabled = true; docker.runOptions = '-u $(id -u):$(id -g)' }
    singularity { singularity.enabled = true; singularity.autoMounts = true }
    conda       { conda.enabled = true }

    slurm {
        process.executor = 'slurm'
        process.queue    = 'compute'
    }

    test {
        params.input  = "${baseDir}/assets/test_samplesheet.csv"
        params.genome = 'R64-1-1'
    }
}

Activate (combine with commas; order matters — later profiles override earlier):

nextflow run main.nf -profile test,singularity

Container/infra profiles (docker, singularity, conda) are mutually exclusive — choose one. If no -profile is given, the standard profile (if defined) is used.

Ordering caveat: with the legacy parser, profiles are applied in the order they are defined in the config, regardless of CLI order; with the strict parser (default in 26.04) they apply in CLI order. To stay safe, avoid combining profiles that set the same option to conflicting values.

Process selectors (withName, withLabel)

Target configuration at specific processes inside the process scope. This is how nf-core sets per-tool resources and arguments without editing modules.

process {
    // by resource label
    withLabel: 'process_low'    { cpus = 2;  memory = 6.GB;  time = 4.h }
    withLabel: 'process_medium' { cpus = 6;  memory = 36.GB; time = 8.h }
    withLabel: 'process_high'   { cpus = 12; memory = 72.GB; time = 16.h }

    // by process name (regex / fully-qualified WORKFLOW:SUB:PROCESS)
    withName: 'FASTQC' { cpus = 4 }
    withName: '.*:ALIGN' {
        container = 'quay.io/biocontainers/bwa:0.7.17--hed695b0_7'
        ext.args  = '-M'                 // injected into the script as task.ext.args
        publishDir = [ path: { "${params.outdir}/bam" }, mode: 'copy' ]
    }
}

Precedence: withName overrides withLabel overrides generic process settings. nf-core keeps all withName blocks in conf/modules.config.

Executors

The executor maps tasks onto compute. Default is local (subprocesses on the current machine). Set globally or per-process.

process.executor = 'slurm'        // global
// or
process { withLabel: 'process_high' { executor = 'slurm'; queue = 'bigmem' } }

SLURM example with cluster options:

process {
    executor   = 'slurm'
    queue      = 'compute'             // SLURM partition
    clusterOptions = '--account=lab123'
}
executor {
    queueSize       = 200              // max jobs queued at once
    submitRateLimit = '10/1min'        // throttle submissions
    perCpuMemAllocation = true         // emit --mem-per-cpu instead of --mem (some clusters require this)
}

Cloud executors

Each cloud needs its scope configured (region, work bucket, etc.). Always set workDir to cloud storage.

// AWS Batch
process.executor = 'awsbatch'
process.queue    = 'my-batch-queue'
aws {
    region = 'us-east-1'
    batch.cliPath = '/home/ec2-user/miniconda/bin/aws'
}
workDir = 's3://my-bucket/work'

// Google Cloud Batch
process.executor = 'google-batch'
google.project   = 'my-gcp-project'
google.location  = 'us-central1'
workDir = 'gs://my-bucket/work'

For Azure use azurebatch + the azure scope with workDir = 'az://...'. For Kubernetes use k8s + nextflow kuberun. Wave + Fusion can accelerate cloud I/O (see references/containers.md). Seqera Platform (Tower) monitoring: set tower.enabled = true and TOWER_ACCESS_TOKEN, or run with -with-tower.

Caching and -resume

-resume skips tasks whose inputs are unchanged, reusing outputs from the work/ directory.

nextflow run main.nf -resume                 # resume the last run
nextflow run main.nf -resume <session-id>    # resume a specific session (see `nextflow log`)

How caching works: each task gets a hash of its inputs (file content/metadata), the script text, the container, and key directives. If the hash matches a previous run, the cached output is reused.

Debugging cache misses (a task re-runs when you expected a hit):

• Run nextflow log <run> -f hash,name,status,workdir to inspect tasks.
• Diff the task hashes of two runs: nextflow -log a.log run … -dump-hashes json then nextflow -log b.log run … -resume -dump-hashes json, and compare the cache hash entries to see exactly what changed.
• Common causes: a changed input file timestamp/content, an edited script, a different container tag, a non-deterministic input order, an undeclared closure variable (use def), or using cache false.
• cache 'lenient' hashes file size+timestamp (path) instead of content — useful on shared filesystems where content hashing is slow or timestamps shift. cache 'deep' hashes file content.
• Caching is per work directory; deleting work/ or changing -w/workDir loses the cache.

Work directory management: work/ grows fast. Clean with:

nextflow clean -f -before <run_name>    # remove work data before a run
nextflow clean -f -but <run_name>       # keep one run, remove others

Set cleanup = true in config to auto-remove work/ on successful completion (note: this disables -resume).

Tracing and reports

Observability flags (or enable the matching config scope):

nextflow run main.nf -profile docker \
  -with-report -with-trace -with-timeline -with-dag flow.html

The nextflow CLI

nextflow run <pipeline> [options]   # <pipeline> = path, .nf file, or github user/repo

Other top-level commands:

nextflow log [run] [-f fields]      # list past runs / fields of a run
nextflow pull   user/repo           # download/update a remote pipeline
nextflow list                       # list downloaded pipelines
nextflow info   user/repo           # show pipeline metadata
nextflow drop   user/repo           # delete a downloaded pipeline
nextflow clean  -f -before <run>    # delete work data
nextflow config [-profile p]        # print the resolved configuration
nextflow inspect <pipeline>         # resolve per-process containers without running
nextflow lint   <file|dir>          # check/format scripts & config (strict syntax)
nextflow self-update                # update the Nextflow engine

Environment variables

On HPC, always set a shared NXF_SINGULARITY_CACHEDIR so image pulls are reused across jobs. See references/running-pipelines.md for offline execution.

Software Dependencies: Containers & Conda

Nextflow runs each process in an isolated software environment so pipelines are reproducible and portable. Never depend on tools installed on the host. Source: https://www.nextflow.io/docs/latest/container.html , https://www.nextflow.io/docs/latest/conda.html , https://www.nextflow.io/docs/latest/wave.html

Choosing an engine

Enable exactly one container engine. nf-core ships these as profiles, so users typically just pass -profile docker / -profile singularity / -profile conda.

The container directive

Each process declares its image; the engine config decides how it runs.

process SAMTOOLS_SORT {
    container 'quay.io/biocontainers/samtools:1.19.2--h50ea8bc_0'
    conda     'bioconda::samtools=1.19.2'    // fallback when -profile conda is used
    script:
    """
    samtools sort -@ $task.cpus -o sorted.bam $input
    """
}

nf-core modules declare both a container (often a Biocontainers/Galaxy depot image) and a conda line, so the same module works under any engine. In nf-core modules the conda directive references a separate file — conda "${moduleDir}/environment.yml" — rather than an inline string. Biocontainers images live on quay.io/biocontainers/... (and https://depot.galaxyproject.org/singularity/... for Singularity), auto-built from Bioconda recipes.

Docker

docker {
    enabled    = true
    runOptions = '-u $(id -u):$(id -g)'   // avoid root-owned output files
}

Singularity / Apptainer

singularity {
    enabled    = true
    autoMounts = true                      // auto-bind host paths
    cacheDir   = '/shared/singularity'     // or set NXF_SINGULARITY_CACHEDIR
}

• Nextflow auto-converts Docker images to SIF on first use and caches them. On clusters, set a shared cacheDir/NXF_SINGULARITY_CACHEDIR so all jobs reuse pulls.
• Bind extra paths with runOptions = '-B /scratch' if autoMounts misses them.
• Apptainer (the renamed Singularity) uses the same options under the apptainer scope.

Conda / Mamba

conda {
    enabled    = true
    useMamba   = true                       // faster solver
    channels   = 'conda-forge,bioconda'     // priority order (this is the default since 26.04)
    cacheDir   = '/shared/conda_envs'
}
process.conda = 'bioconda::bwa=0.7.17 bioconda::samtools=1.19'

Conda is the least reproducible option (solver drift, no OS isolation); prefer containers for published results. Use NXF_CONDA_CACHEDIR to reuse built envs.

Wave + Fusion

Wave builds/augments containers on demand from a conda directive or a Dockerfile, pushes to a registry, and can mount private registries. Fusion is a virtual distributed file system that lets tasks read/write cloud object storage (S3/GCS) as if local — big speedups on cloud.

wave {
    enabled  = true
    strategy = 'conda'           // build images from process conda directives
}
fusion.enabled = true            // pair with Wave on cloud executors
tower.accessToken = secrets.TOWER_ACCESS_TOKEN   // some Wave features use Seqera creds

Common gotchas

• Two engines enabled at once → errors or surprising behavior. Enable one (use profiles).
• Root-owned outputs with Docker → set runOptions = '-u $(id -u):$(id -g)'.
• Singularity can't see input files → enable autoMounts or add -B binds; ensure the work dir and inputs are on bound paths.
• HPC pull storms / quota blowups → set a shared NXF_SINGULARITY_CACHEDIR and pre-pull with nf-core pipelines download (see references/running-pipelines.md).
• Pinning: always use a fully versioned image tag (and digest where possible). latest breaks reproducibility.
• Offline: pre-stage all images (Singularity SIFs or a local Docker registry) and set NXF_OFFLINE=true.

Developing nf-core Pipelines, Modules & Subworkflows

Conventions for building nf-core-compliant components. Sources: https://nf-co.re/docs/developing/ (guides) and https://nf-co.re/docs/specifications/ (the normative MUST/SHOULD spec).

Table of Contents

• Pipeline directory layout
• The meta map convention
• Anatomy of a module
• meta.yml
• ext.args and modules.config
• Subworkflows
• Resource labels and base.config
• Schema and parameters
• Linting and the Harshil alignment style

Pipeline directory layout

nf-core pipelines create scaffolds this structure:

my-pipeline/
├── main.nf                     # entry: includes the main workflow
├── nextflow.config             # params defaults, profiles, includes conf/*
├── nextflow_schema.json        # parameter schema (validation + docs + launch GUI)
├── workflows/
│   └── mypipeline.nf           # the primary workflow (orchestrates subworkflows)
├── subworkflows/
│   ├── local/                  # pipeline-specific subworkflows
│   └── nf-core/                # installed shared subworkflows
├── modules/
│   ├── local/                  # pipeline-specific modules
│   └── nf-core/                # installed shared modules
├── conf/
│   ├── base.config             # default resources keyed by process_* labels
│   ├── modules.config          # per-process ext.args, publishDir (withName:)
│   ├── test.config             # tiny test profile inputs
│   └── igenomes.config         # reference genome keys
├── assets/                     # samplesheet schema, email templates, MultiQC config
├── bin/                        # executable helper scripts (on PATH in tasks)
├── docs/                       # usage.md, output.md, parameter docs
├── modules.json                # pins installed nf-core modules/subworkflows by SHA
└── .nf-core.yml                # tools config (lint rules, template features)

main.nf includes the workflow in workflows/; that workflow includes subworkflows and modules. Parameters are declared in nextflow.config + nextflow_schema.json; per-process behavior lives in conf/modules.config. Keep logic in workflows/modules, not in main.nf.

The meta map convention

nf-core carries a metadata map alongside every sample's files in input/output tuples. This keeps samples labeled and lets groupTuple/join operate on the key as data flows through the pipeline.

// channel item shape:
[ [ id:'sample1', single_end:false ], [ sample1_R1.fastq.gz, sample1_R2.fastq.gz ] ]

• Only two keys are standard: meta.id (unique sample identifier) and meta.single_end (paired vs single reads). No new standard keys are being defined — this is deliberate, to keep modules flexible.
• Inside a module, reference only meta.id/meta.single_end (for tag/prefix). A module MUST NOT hardcode custom meta keys; pass per-sample values in via ext.args from conf/modules.config instead (e.g. ext.args = { "--strandedness ${meta.strandedness}" }).
• The first meta in a tuple is named meta, the second meta2, etc. — not custom names.
• Outputs re-emit the same `meta` so downstream steps stay aligned: tuple val(meta), path("*.bam").
• Build it from the samplesheet with splitCsv + map (see references/language.md). Subworkflows may create/emit new meta keys (document them in meta.yml).

Why it matters: decoupling metadata from module logic lets any pipeline name its metadata however it likes while reusing the same module unchanged.

Anatomy of a module

A module lives in modules/nf-core/<tool>/<subtool>/ (all lowercase, one command/subcommand per module) with these files:

modules/nf-core/samtools/sort/
├── environment.yml     # Conda channels + pinned deps
├── main.nf             # the process
├── meta.yml            # documented I/O + tools (schema-validated)
└── tests/
    ├── main.nf.test    # nf-test tests (required, incl. a stub test)
    └── main.nf.test.snap

environment.yml (pin the version, not the build):

channels:
  - conda-forge
  - bioconda
dependencies:
  - bioconda::samtools=1.19.2

Annotated main.nf:

process SAMTOOLS_SORT {
    tag "$meta.id"                        // per-sample label (only meta.id / meta.single_end allowed here)
    label 'process_medium'                // exactly ONE bundled resource label (conf/base.config)

    conda "${moduleDir}/environment.yml"  // references the file above (NOT inline package strings)
    container "${ workflow.containerEngine in ['singularity', 'apptainer'] && !task.ext.singularity_pull_docker_container ?
        'https://depot.galaxyproject.org/singularity/samtools:1.19.2--h50ea8bc_0' :
        'quay.io/biocontainers/samtools:1.19.2--h50ea8bc_0' }"

    input:
    tuple val(meta), path(bam)            // meta map is ALWAYS the first tuple element

    output:
    tuple val(meta), path("*.bam"), emit: bam
    path "versions.yml",            emit: versions   // version reporting (see note below)

    when:
    task.ext.when == null || task.ext.when           // frozen line; gate via ext.when in config

    script:
    def args   = task.ext.args   ?: ''               // tool flags come from config, never hardcoded
    def prefix = task.ext.prefix ?: "${meta.id}"
    """
    samtools sort $args -@ $task.cpus -o ${prefix}.bam $bam

    cat <<-END_VERSIONS > versions.yml
    "${task.process}":
        samtools: \$(samtools --version | sed '1!d; s/samtools //')
    END_VERSIONS
    """

    stub:                                            // required: every output channel gets ≥1 file
    def prefix = task.ext.prefix ?: "${meta.id}"
    """
    touch ${prefix}.bam
    cat <<-END_VERSIONS > versions.yml
    "${task.process}":
        samtools: \$(samtools --version | sed '1!d; s/samtools //')
    END_VERSIONS
    """
}

Key module rules:

• Both conda "${moduleDir}/environment.yml" and container are declared (works under any engine). Containers are Biocontainers (quay.io/biocontainers/...) / Galaxy depot (https://depot.galaxyproject.org/singularity/...) images pinned by version+build.
• Tool arguments are not hardcoded — they come from task.ext.args (and args2, args3, … for piped tools). The output filename prefix comes from task.ext.prefix; output names SHOULD be ${prefix} + suffix.
• The when: line is boilerplate — never edit it; gate execution via ext.when in config.
• Always include a stub: block (touch ≥1 file per output channel; for gzip outputs use echo '' | gzip > x.gz, not bare touch).
• One tool/subcommand per module; no pipeline-specific logic; no reading params.* inside a module.

Reporting tool versions (current vs legacy)

Two patterns exist — know both:

• `versions.yml` (shown above): a HEREDOC writes a YAML file emitted as path "versions.yml", emit: versions. This is what most installed modules use today and is the clearest to read.
• Topic channels + `eval()` (what nf-core modules create now generates): the tool version is captured declaratively and routed to a versions topic, removing the HEREDOC:

output:
tuple val("${task.process}"), val('samtools'),
      eval('samtools --version | sed "1!d; s/samtools //"'),
      topic: versions, emit: versions_samtools

Either way, the version string MUST start with a digit (strip a leading v). Subworkflows/pipelines aggregate versions (mix the versions channels or consume the topic) and feed MultiQC.

meta.yml

Machine-readable description of the module's interface (generated by nf-core modules create, validated by nf-core modules lint, used by nf-core modules info and docs). Current schema: input is a nested list (meta and its file are separate entries), output is a mapping keyed by emit name, each file entry carries an ontologies list, and each tool has an identifier (bio.tools ID where available):

name: "samtools_sort"
description: Sort a BAM/CRAM/SAM file
keywords:
  - sort
  - bam
  - genomics
tools:
  - samtools:
      description: Tools for manipulating SAM/BAM/CRAM
      homepage: http://www.htslib.org/
      licence: ["MIT"]
      identifier: biotools:samtools
input:
  - - meta:
        type: map
        description: "Groovy Map with sample info, e.g. [ id:'test', single_end:false ]"
    - bam:
        type: file
        description: Input BAM/CRAM/SAM file
        pattern: "*.{bam,cram,sam}"
        ontologies: []
output:
  bam:
    - - meta:
          type: map
          description: Groovy Map with sample info
      - "*.bam":
          type: file
          description: Sorted BAM file
          pattern: "*.bam"
          ontologies: []
  versions:
    - "versions.yml":
        type: file
        description: File containing software versions
        pattern: "versions.yml"
        ontologies: []
authors:
  - "@author"
maintainers:
  - "@maintainer"

ext.args and modules.config

Per-process configuration (tool flags, output paths, naming) is injected from conf/modules.config using withName: selectors — never edit the module to change behavior.

// conf/modules.config
process {
    withName: 'SAMTOOLS_SORT' {
        // use a closure so it is evaluated lazily and can read params/meta; .minus("").join(' ') drops empties
        ext.args   = { [ '-l 9', params.fast ? '-@ 8' : '' ].minus("").join(' ') }
        ext.prefix = { "${meta.id}.sorted" }         // closures can read meta
        publishDir = [
            path: { "${params.outdir}/samtools" },
            mode: params.publish_dir_mode,
            pattern: "*.bam"
        ]
    }
    withName: '.*:ALIGN_BWA:BWA_MEM' { ext.args = '-M' }   // target a fully-qualified path
}

Permitted ext keys: ext.args/args2/args3/argsN (numbered by tool order in a piped script), ext.prefix/prefix2, ext.when, ext.use_gpu, ext.singularity_pull_docker_container. Rule of thumb: optional flags → ext.args; but any value whose change could break results MUST be a real input: channel (documented in meta.yml), not an ext key. This separation (logic in the module, config in modules.config) is what makes nf-core modules reusable across pipelines.

Subworkflows

A subworkflow chains modules into a reusable unit, in subworkflows/nf-core/<name>/main.nf with take/main/emit and a meta.yml. It MUST contain ≥2 modules and MUST aggregate/emit a versions channel. Name it <file-type>_<operation(s)>_<tool(s)>, e.g. bam_sort_stats_samtools.

include { SAMTOOLS_SORT  } from '../../../modules/nf-core/samtools/sort/main'
include { SAMTOOLS_INDEX } from '../../../modules/nf-core/samtools/index/main'

workflow BAM_SORT_SAMTOOLS {
    take:
    ch_bam            // channel: [ val(meta), path(bam) ]

    main:
    ch_versions = Channel.empty()

    SAMTOOLS_SORT(ch_bam)
    ch_versions = ch_versions.mix(SAMTOOLS_SORT.out.versions)

    SAMTOOLS_INDEX(SAMTOOLS_SORT.out.bam)
    ch_versions = ch_versions.mix(SAMTOOLS_INDEX.out.versions)

    emit:
    bam      = SAMTOOLS_SORT.out.bam        // [ val(meta), path(bam) ]
    bai      = SAMTOOLS_INDEX.out.bai
    versions = ch_versions                  // collect versions from all modules
}

Convention: collect each module's versions into one channel and emit it; document channel shapes in comments and meta.yml.

Resource labels and base.config

Modules carry a process_* label; conf/base.config maps labels → resources (with task.attempt scaling for retries):

process {
    cpus   = { 1    * task.attempt }
    memory = { 6.GB * task.attempt }
    time   = { 4.h  * task.attempt }
    errorStrategy = { task.exitStatus in ((130..145) + 104 + (175..177)) ? 'retry' : 'finish' }
    maxRetries    = 1

    withLabel: process_single      { cpus = { 1 };             memory = { 6.GB  * task.attempt }; time = { 4.h  * task.attempt } }
    withLabel: process_low         { cpus = { 2 * task.attempt }; memory = { 12.GB * task.attempt }; time = { 4.h  * task.attempt } }
    withLabel: process_medium      { cpus = { 6 * task.attempt }; memory = { 36.GB * task.attempt }; time = { 8.h  * task.attempt } }
    withLabel: process_high        { cpus = { 12 * task.attempt }; memory = { 72.GB * task.attempt }; time = { 16.h * task.attempt } }
    withLabel: process_long        { time = { 20.h * task.attempt } }
    withLabel: process_high_memory { memory = { 200.GB * task.attempt } }
    withLabel: error_ignore        { errorStrategy = 'ignore' }
    withLabel: error_retry         { errorStrategy = 'retry'; maxRetries = 2 }
}

Attach exactly one bundled label (process_single/low/medium/high) per module and optionally stack a modifier (process_long, process_high_memory). Resources auto-scale with task.attempt and retry on out-of-resource exit codes. To cap escalation to what the platform allows, set process.resourceLimits = [ cpus: 16, memory: 128.GB, time: 24.h ] (the modern replacement for the old check_max()/--max_cpus/--max_memory pattern) in nextflow.config or an institutional config.

Schema and parameters

nextflow_schema.json is a JSON-Schema description of every pipeline parameter. It powers CLI/-params-file validation (via the nf-schema plugin), the nf-core pipelines launch GUI, and auto-generated docs. Keep it in sync with params in nextflow.config:

nf-core pipelines schema build      # interactive web editor to add/edit params
nf-core pipelines schema lint       # CI checks schema ↔ params consistency

The samplesheet itself is validated against assets/schema_input.json.

Linting and the Harshil alignment style

• Run nf-core pipelines lint (pipelines) and nf-core modules lint <tool> / nf-core subworkflows lint <name> (components) before every PR; CI enforces them. Lint exceptions live in .nf-core.yml.
• Code must be free of Nextflow syntax warnings: NXF_SYNTAX_PARSER=v2 nextflow lint modules/nf-core/<tool> (strict syntax becomes the default in Nextflow 26.04 — see references/language.md). Common fixes: always def your variables, use explicit closure params ({ meta, file -> ... }) not it, avoid for loops.
• Code is formatted with Prettier (prettier -w .) and follows the Harshil alignment style: align assignment =, the commas/emit:/optional: in I/O declarations, and trailing comments into columns for readability. EditorConfig + pre-commit hooks ship in the template; comment @nf-core-bot fix linting on a PR to auto-fix.
• Other expectations: pinned tool versions, conda+container, a stub: block, nf-test tests for every module/subworkflow, and CHANGELOG.md/CITATIONS.md updates.

See references/testing.md for the testing requirements and references/nf-core-tools.md for the CLI. Full normative spec: https://nf-co.re/docs/specifications/components/modules/general .

Nextflow Language (DSL2)

The complete Nextflow scripting language: processes, channels, operators, workflows, and modules. Nextflow is a Groovy-based DSL; DSL2 is the default and only DSL (DSL1 is removed, so nextflow.enable.dsl=2 is unnecessary). Source: https://www.nextflow.io/docs/latest/

Current syntax conventions (a strict-syntax parser, NXF_SYNTAX_PARSER=v2, is opt-in in 25.x and becomes the default in 26.04 — write to it now, it also runs on the legacy parser):

• `channel.of(...)` (lowercase namespace) is canonical; Channel.of(...) still works but is discouraged.
• Explicit closure parameters ({ v -> v * 2 }) are preferred over the implicit it.
• Name process outputs with `emit:`; scale resources with `task.attempt`.
• `output {}` + `publish:` (full feature in 25.10) is the new declarative way to publish results; publishDir still works and remains dominant in nf-core — both are shown below.
• Avoid removed/deprecated idioms: for/while loops (use each/collect), import/custom class (use functions or lib/), process shell: (use script:), include … addParams().

Table of Contents

• Script structure
• Processes
• Process directives
• Channels
• Operators
• Workflows
• Modules
• Dynamic resources and error handling
• Groovy essentials and gotchas

Script structure

A Nextflow script (.nf) mixes process/workflow definitions with Groovy. Every script enables DSL2 implicitly (it is the default since 22.03). A run begins at the unnamed `workflow {}` block (the entry workflow).

#!/usr/bin/env nextflow

params.input = 'data/*.fastq'        // pipeline parameter with a default

process FASTQC { /* ... */ }          // a process definition

workflow {                            // entry point
    reads = channel.fromPath(params.input)
    FASTQC(reads)
}

Run with nextflow run main.nf --input 'data/*.fastq'. Parameters declared as params.x are overridable on the CLI (--x), in nextflow.config, or in a -params-file.

Processes

A process defines a task: a (usually Bash) script executed in its own isolated work directory. Nextflow stages declared inputs in and declared outputs out, so processes never read/write each other's files directly — they communicate only through channels.

process ALIGN {
    tag    "$meta.id"                 // label shown in the log/trace
    label  'process_high'             // maps to resources in config
    container 'quay.io/biocontainers/bwa:0.7.17--hed695b0_7'
    publishDir "${params.outdir}/bam", mode: 'copy'

    input:
    tuple val(meta), path(reads)      // a sample: metadata map + file(s)
    path  index                       // a shared reference (value channel)

    output:
    tuple val(meta), path("*.bam"), emit: bam
    path  "versions.yml",           emit: versions

    when:
    meta.run_alignment != false       // skip task if false

    script:
    def prefix = task.ext.prefix ?: meta.id
    def args   = task.ext.args  ?: ''   // extra flags injected from config
    """
    bwa mem $args -t $task.cpus $index ${reads} | samtools sort -o ${prefix}.bam

    cat <<-END_VERSIONS > versions.yml
    "${task.process}":
        bwa: \$(bwa 2>&1 | sed -n 's/Version: //p')
    END_VERSIONS
    """

    stub:
    """
    touch ${meta.id}.bam
    touch versions.yml
    """
}

Inputs

Declared one per line under input:. Each input consumes one item from a channel.

Inputs are positional and matched to channels in call order: ALIGN(reads_ch, index_ch).

Outputs

Declared under output:; each becomes a channel. Use emit: to name outputs so callers can reference ALIGN.out.bam instead of positional ALIGN.out[0].

Script, shell, exec

• `script:` (default) — a multi-line string run as Bash. Nextflow variables interpolate with $var/${expr}; escape shell vars you do NOT want Nextflow to touch as \$var.
• `shell:` — like script but Nextflow vars use !{var}, leaving $ for the shell. Deprecated as of 25.04 — use script: with \$ to escape shell vars.
• `exec:` — native Groovy, no external process (for in-line computation).
• A process can run any interpreter via a shebang (e.g. #!/usr/bin/env python).

process PY {
    input: val x
    output: stdout
    script:
    """
    #!/usr/bin/env python
    print(${x} ** 2)
    """
}

Conditional execution

• when: — skip the task when the expression is false (prefer filtering channels upstream when possible).
• A script: can branch with normal Groovy if/else returning different command strings.
• stub: — an alternate minimal script run with -stub-run to test pipeline wiring without the real tool. nf-core requires stubs.

Process directives

Set inside a process (or globally via config). Most-used:

Access the resolved values at runtime via task.* (task.cpus, task.memory, task.attempt, task.process, task.ext.args).

Channels

Channels are the asynchronous queues connecting processes. Two kinds:

• Queue channel: an ordered, consumable stream of items. Produced by most factories/operators and by process outputs. Can be consumed once.
• Value channel (singleton): holds one value that can be read an unlimited number of times. Created by channel.value(), by operators like collect/first, or implicitly from a single value. A process input bound to a value channel is reused for every task.

Channel factories

channel.of(1, 2, 3)                                  // emit given values (ranges expand: 1..23)
channel.fromList([1, 2, 3])                          // emit list items
channel.value('ref.fa')                              // singleton value channel
channel.fromPath('data/*.bam')                       // one item per matching file
channel.fromPath('data/**.fastq', checkIfExists: true)   // also: arity:'1', type:'file', hidden:true
channel.fromFilePairs('data/*_{1,2}.fastq.gz')       // -> [id, [r1, r2]] for paired reads
channel.topic('versions')                            // collect values emitted to a named topic (24.04+)
channel.empty()                                      // emits nothing

channel.fromSRA(...) exists but is deprecated as of 26.04 — prefer a samplesheet (splitCsv) over fetching reads by accession.

fromFilePairs is the idiomatic way to group paired-end reads; it yields [ sampleId, [read1, read2] ], which you typically map into the nf-core [ meta, [reads] ] shape.

Operators

Operators transform/combine channels. Chain with .; the dataflow graph is built from these connections.

// Build the nf-core [meta, reads] shape from a samplesheet
channel
    .fromPath(params.input)
    .splitCsv(header: true)
    .map { row -> tuple([id: row.sample, single_end: row.fastq_2 ? false : true],
                        row.fastq_2 ? [file(row.fastq_1), file(row.fastq_2)] : [file(row.fastq_1)]) }
    .set { reads_ch }

// Group per-sample results, then join two channels by meta
counts.groupTuple()
       .join(metadata)          // matches on the first (key) element
       .view()

Workflows

A workflow composes processes and other workflows. The unnamed workflow is the entry point. Named workflows are reusable (sub)workflows.

workflow RNASEQ {
    take:                       // typed inputs (channels)
    reads
    index

    main:                       // pipeline logic
    FASTQC(reads)
    ALIGN(reads, index)
    QUANT(ALIGN.out.bam)

    emit:                       // named outputs
    bam    = ALIGN.out.bam
    counts = QUANT.out.counts
    versions = FASTQC.out.versions.mix(ALIGN.out.versions)
}

workflow {                      // entry: wire inputs and call the named workflow
    reads = channel.fromFilePairs(params.reads)
    index = channel.value(file(params.index))
    RNASEQ(reads, index)
    RNASEQ.out.counts.view()
}

• Call a process/workflow like a function: ALIGN(reads, index). Outputs are on .out (use emit: names: ALIGN.out.bam).
• A process can only be called once per workflow; to reuse it, include it again under an alias.
• Pipe syntax works for simple chains: reads | FASTQC.
• Declarative outputs (25.10+): assign channels in the entry workflow's publish: section and describe them in a top-level output {} block — the recommended replacement for the publishDir directive (which still works and dominates nf-core):

workflow {
    main:
    ch = ANALYZE(input)
    publish:
    results = ch                       // name the published channel
}
output {
    results { path 'analysis' }        // -> <outputDir>/analysis (default outputDir: results/)
}

Modules

Modules are .nf files whose processes/workflows are imported with include. This is the basis of nf-core's reusable components.

include { FASTQC }                     from './modules/fastqc/main.nf'
include { ALIGN as ALIGN_TUMOR;
          ALIGN as ALIGN_NORMAL }      from './modules/align/main.nf'
include { RNASEQ }                     from './subworkflows/rnaseq.nf'

• as aliases let you include the same component multiple times.
• Includes are resolved relative to the including file; .nf extension optional.
• Params should be passed explicitly (as inputs), not read globally inside modules — this keeps modules portable (an nf-core requirement).

Dynamic resources and error handling

Make pipelines robust by retrying failures with more resources instead of over-provisioning everything. task.attempt increments on each retry.

process BIG_JOB {
    label 'process_high'
    cpus   { 4 * task.attempt }
    memory { 8.GB * task.attempt }
    time   { 4.h * task.attempt }

    errorStrategy { task.exitStatus in [137, 140, 143] ? 'retry' : 'terminate' }
    maxRetries 3
    // ...
}

• Exit codes 137/140/143 typically mean out-of-memory/walltime kills — retry with more resources.
• errorStrategy 'ignore' lets the pipeline continue past a failed task; 'finish' stops launching new tasks but lets running ones complete.
• In nf-core, resource scaling lives in conf/base.config keyed on process_* labels (see references/developing.md).

Groovy essentials and gotchas

• Strings: single-quoted are literal; double-quoted interpolate ("${x}"). In script: blocks, escape shell variables as \$VAR.
• Define helper values with def inside script:/closures to avoid leaking globals.
• Maps use Groovy syntax: [ id: 'x', single_end: false ]; access as meta.id.
• Common gotchas:
• Re-using a consumed queue channel yields nothing — use a value channel (or collect) for things consumed by many tasks (like a reference index).
• groupTuple may emit before all items arrive unless sizes are known; provide size: or use groupTuple(by:) carefully.
• A process called twice without aliasing is an error; include ... as.
• Globs in output: match the work directory, not publishDir.
• Prefer filtering channels over when: for clarity and caching.
• Strict syntax / language server: recent Nextflow ships a VS Code extension + nextflow lint and a stricter parser; nf-core is migrating pipelines to it. Keep scripts to documented DSL2 constructs and avoid deprecated DSL1 idioms (Channel.create(), .into{} overuse, top-level file() for inputs).

nf-core Tools CLI Reference

nf-core is a Python CLI for creating, linting, testing, and running nf-core-style pipelines, modules, and subworkflows. Source: https://nf-co.re/docs/nf-core-tools

Install

pip install nf-core            # PyPI
conda install -c bioconda nf-core
nf-core --version

In tools v3+ the commands are grouped under pipelines, modules, subworkflows, and test-datasets. (Older flat commands like nf-core create/nf-core lint still work but emit deprecation warnings — use the grouped form.) Run nf-core --help or nf-core <group> --help to see current options, or nf-core interface for a graphical TUI command explorer.

For modules/subworkflows, group-level options go before the subcommand, e.g. to target a non-default component repo: nf-core modules -g <git-url> -b <branch> install fastqc.

Pipelines

Create a pipeline

nf-core pipelines create                # interactive: name, description, author
# non-interactive:
nf-core pipelines create --name mypipe --description "My pipeline" --author me

This generates the full nf-core template (see references/developing.md for the layout) with CI, linting, schema, and a test profile wired up. Develop on a feature branch; keep the TEMPLATE branch for sync.

Lint before pushing

cd my-pipeline
nf-core pipelines lint                   # run in the repo root
nf-core pipelines lint --release         # stricter checks for a release

Linting enforces nf-core structure, required files, schema/params consistency, module versions, and formatting. CI runs this on every PR.

Modules

Manage reusable process modules from the central nf-core/modules repo, or author your own.

# Reuse before you rebuild: install an existing module
nf-core modules install fastqc
nf-core modules install samtools/sort

# Author a new one, then lint + test it
nf-core modules create mytool
nf-core modules lint mytool
nf-core modules test mytool

Tool naming uses tool or tool/subtool (e.g. samtools/sort). Installed modules are pinned by git SHA in modules.json.

Subworkflows

Same lifecycle as modules, for chains of modules. Source: https://nf-co.re/docs

nf-core subworkflows install bam_sort_stats_samtools
nf-core subworkflows create align_bwa
nf-core subworkflows test align_bwa

Test datasets

nf-core test-datasets list              # list test-data branches
nf-core test-datasets search <term>     # find small test files in nf-core/test-datasets

Use these tiny, version-controlled files in module/pipeline tests (see references/testing.md).

Typical developer loop

nf-core pipelines create                       # scaffold
nf-core modules install fastqc                 # reuse community modules
nf-core modules create mytool                  # add a custom one
nf-core modules test mytool                    # nf-test it
nf-core subworkflows install bam_sort_stats_samtools
nf-core pipelines schema build                 # keep schema in sync with params
nf-core pipelines lint                          # validate everything
prettier --write .                             # format (Harshil alignment)

See references/developing.md for what each generated file should contain, and references/testing.md for nf-test details.

Running nf-core & Custom Pipelines

End-to-end guidance for running pipelines reproducibly. Source: https://nf-co.re/docs/running/

Table of Contents

• Find a pipeline
• The standard run pattern
• Samplesheets (the input)
• Parameters and params files
• Profiles and containers
• Reference genomes / iGenomes
• Institutional configs
• Offline / air-gapped execution
• Monitoring and troubleshooting

Find a pipeline

nf-core pipelines list                 # all nf-core pipelines, sorted by activity
nf-core pipelines list rna             # keyword search
nf-core pipelines info rnaseq          # details about one pipeline

Browse the catalog at https://nf-co.re/pipelines. Each pipeline page documents its parameters, samplesheet format, and outputs.

The standard run pattern

1. Smoke-test the environment with the bundled tiny dataset:

nextflow run nf-core/rnaseq -r 3.14.0 -profile test,docker --outdir test_results

2. Real run — pin a revision, choose a container engine, provide a samplesheet:

nextflow run nf-core/<pipeline> \
  -r <version> \                # pin release for reproducibility
  -profile docker \             # or singularity / conda
  --input samplesheet.csv \     # the samples to process
  --outdir results \            # where results go (required by nf-core)
  -resume                       # reuse cache on reruns

nextflow run nf-core/rnaseq auto-pulls the pipeline from GitHub into ~/.nextflow/assets. Use nextflow pull nf-core/rnaseq to pre-fetch/update, and -r to pin a tag.

Interactive command builder

nf-core pipelines launch walks through every parameter (validated against the pipeline's nextflow_schema.json) and writes a nf-params.json you can reuse:

nf-core pipelines launch nf-core/rnaseq
nextflow run nf-core/rnaseq -profile docker -params-file nf-params.json

Samplesheets (the input)

nf-core pipelines take a CSV samplesheet (via --input), not loose files — this keeps sample metadata explicit. The exact columns are pipeline-specific (see each pipeline's docs), but a typical RNA-seq sheet:

sample,fastq_1,fastq_2,strandedness
CONTROL_REP1,s3://.../ctrl_1.fastq.gz,s3://.../ctrl_2.fastq.gz,auto
TREAT_REP1,/data/treat_1.fastq.gz,/data/treat_2.fastq.gz,auto

• Leave fastq_2 empty for single-end data.
• Paths can be local or remote (S3/GCS/https) — Nextflow stages them automatically.
• Validation (via the nf-schema/nf-validation plugin) fails fast with clear errors if columns/values are wrong.

Parameters and params files

Pass parameters three ways (later overrides earlier): config files → -params-file → --cli flags. For anything non-trivial, prefer a params file (reproducible, reviewable):

nf-core pipelines create-params-file nf-core/rnaseq   # generate documented YAML
nextflow run nf-core/rnaseq -profile docker -params-file params.yml --outdir results

# params.yml
input:  samplesheet.csv
outdir: results
genome: GRCh38
aligner: star_salmon

Profiles and containers

• Container engine: pick one — -profile docker (local/CI), -profile singularity (HPC), -profile conda (last resort).
• `test`: tiny bundled dataset; always combine with an engine, e.g. -profile test,docker.
• Combine comma-separated; order matters (later wins). Layer site config with -c custom.config and per-process tweaks via withName selectors (see references/configuration.md).

Reference genomes / iGenomes

Many pipelines accept --genome <KEY> (e.g. GRCh38, GRCm38, R64-1-1) and pull references from AWS iGenomes automatically. Alternatives:

• Provide your own references explicitly (--fasta, --gtf, --star_index, …) — recommended for control/reproducibility. Add --save_reference to keep built indices for reuse.
• Mirror iGenomes locally and set --igenomes_base to the local path for offline use.
• --igenomes_ignore disables the iGenomes logic entirely.

Gotcha: AWS iGenomes annotations are significantly outdated (the human GTF is ~Ensembl release 75 / 2015) and its GRCh38 comes from NCBI, not the soft-masked Ensembl assembly. For current/masked references, supply your own --fasta/--gtf.

Institutional configs

nf-core/configs provides ready-made profiles for many HPC systems and clouds (executor, queues, container cache, resource limits). Use one with -profile <institution> (e.g. -profile crick,singularity); Nextflow fetches it from the central repo. To write your own, see https://nf-co.re/docs/running/configuration/configuration-options and references/configuration.md. Point at a local/private config repo with --custom_config_base (offline).

Offline / air-gapped execution

# On a connected machine: bundle pipeline + configs + containers
nf-core pipelines download nf-core/rnaseq \
  --revision 3.14.0 \
  --container-system singularity \      # pre-convert images to SIF
  --compress none \
  --outdir nf-core-rnaseq

# Transfer the folder, then on the offline machine:
export NXF_OFFLINE=true
export NXF_SINGULARITY_CACHEDIR=/shared/sif
nextflow run nf-core-rnaseq/3_14_0 -profile singularity --input ... --outdir results

To reuse a shared image cache instead of copying images into the bundle, set $NXF_SINGULARITY_CACHEDIR and pass --container-cache-utilisation amend. Also pre-stage reference genomes locally and set the relevant --*_index/igenomes_base params, pin all plugin versions, and export NXF_OFFLINE=true. See https://nf-co.re/docs/running/run-pipelines-offline.

Monitoring and troubleshooting

• Logs: each run prints a live task table; the full .nextflow.log is in the launch dir. Find a failed task's work dir in the error message and inspect .command.sh, .command.out, .command.err, .exitcode there.
• Resume: fix the issue and rerun with -resume to avoid recomputing successful tasks.
• Reports: add -with-report -with-trace -with-timeline to profile resource usage and right-size requests (see references/configuration.md).
• Common failures: out-of-memory (exit 137) → raise memory via withName/withLabel or a custom config; missing input column → fix the samplesheet; container pull failure → check engine/profile and cache dir; wrong Java/Nextflow version → set NXF_VER and check nextflow info.
• Seqera Platform: run with -with-tower (and TOWER_ACCESS_TOKEN) for a web dashboard, or launch pipelines from Seqera Platform directly.

Testing with nf-test

nf-test is the standard test framework for Nextflow. nf-core requires nf-test coverage for every module, subworkflow, and pipeline. Sources: https://www.nf-test.com and https://nf-co.re/docs/developing/testing/overview

Table of Contents

• Setup
• Test file structure
• Testing a module (process)
• Assertions
• Snapshot testing
• Testing workflows and pipelines
• Running tests
• nf-core integration

Setup

# install (one of)
conda install -c bioconda nf-test
curl -fsSL https://get.nf-test.com | bash

nf-test init        # creates nf-test.config + tests/ scaffolding in a project

Test files end in .nf.test and live next to the component (tests/main.nf.test). Expected results are stored in a sibling .nf.test.snap snapshot file.

Test file structure

Three test scopes match what you're testing:

• nextflow_process — a single process/module
• nextflow_workflow — a (sub)workflow
• nextflow_pipeline — a whole pipeline (main.nf)

Common layout:

nextflow_process {

    name "Test SAMTOOLS_SORT"
    script "../main.nf"          // the module under test
    process "SAMTOOLS_SORT"

    tag "modules"
    tag "modules_nfcore"
    tag "samtools"
    tag "samtools/sort"

    test("sarscov2 - bam") {
        when {
            process {
                """
                input[0] = [
                    [ id:'test', single_end:false ],
                    file(params.modules_testdata_base_path + 'genomics/sarscov2/illumina/bam/test.bam', checkIfExists: true)
                ]
                """
            }
        }
        then {
            assertAll(
                { assert process.success },
                { assert snapshot(process.out).match() }
            )
        }
    }
}

• input[0], input[1], … bind positional process inputs.
• A setup { } block can run prerequisite processes to produce inputs.
• A params { } block sets parameters; a config "..." line loads a config for the test.
• nf-core requires a stub test alongside the real one — add options "-stub" inside a test(...) block to exercise the stub: script.

Testing a module (process)

The when block supplies inputs; the then block asserts on results. Use a setup block when a module needs another module's output first:

test("sort then index") {
    setup {
        run("SAMTOOLS_SORT") {
            script "../../sort/main.nf"
            process {
                """
                input[0] = [ [id:'test'], file(params.test_data + 'test.bam', checkIfExists:true) ]
                """
            }
        }
    }
    when {
        process {
            """
            input[0] = SAMTOOLS_SORT.out.bam
            """
        }
    }
    then {
        assert process.success
        assert snapshot(process.out).match()
    }
}

Assertions

Inside then, wrap multiple checks in assertAll(...) so all failures are reported at once. Useful handles and helpers:

There is no assertContainsInOrder. For ordered or substring checks on file contents, read the lines and assert directly, e.g. assert path(out[0][1]).readLines().any { it.contains('Done') } or assert path(out[0][1]).readLines().last().contains('completed').

Plugins extend assertions for domain files (e.g. nft-bam for BAM, nft-vcf for VCF, nft-utils); nf-core enables these in nf-test.config. Example with a file-content assertion:

then {
    assertAll(
        { assert process.success },
        { assert path(process.out.bam[0][1]).exists() },
        { assert snapshot(
            bam(process.out.bam[0][1]).getSamLinesMD5(),
            process.out.versions
          ).match() }
    )
}

Snapshot testing

snapshot(x).match() serializes x and compares it to the .nf.test.snap file. The first run records the snapshot; later runs fail if output changes.

• Snapshot stable things: file MD5s/checksums, versions.yml, list sizes — not absolute paths or timestamps.
• Regenerate intentionally-changed snapshots with nf-test test --update-snapshot.
• Name multiple snapshots in one test with .match("bam"), .match("versions").

Testing workflows and pipelines

nextflow_pipeline {
    name "Test full pipeline"
    script "../main.nf"
    test("default params") {
        when { params { outdir = "$outputDir"; input = "tests/samplesheet.csv" } }
        then {
            assert workflow.success
            assert workflow.trace.succeeded().size() > 0
        }
    }
}

Use tiny inputs from nf-core/test-datasets (nf-core test-datasets search ...) so tests stay fast.

Running tests

nf-test test                                  # run everything
nf-test test modules/nf-core/samtools/sort/   # a directory
nf-test test tests/main.nf.test               # one file
nf-test test --tag samtools                    # by tag
nf-test test --profile docker                  # choose container engine
nf-test test --update-snapshot                 # accept new snapshots
nf-test test --changed-since HEAD^             # only components changed since a ref
nf-test test --only-changed --ci               # CI mode: fail (don't write) on a missing snapshot

nf-test.config sets the test directory, default profile, and plugins. CI typically runs only changed components via --changed-since plus the nf-core nf-test GitHub Action.

nf-core integration

For nf-core components, prefer the wrapper commands — they run nf-test with the correct profiles, tags, and snapshot handling, and create scaffolds the test files:

nf-core modules create mytool         # scaffolds tests/main.nf.test
nf-core modules test mytool            # runs the module's nf-test suite
nf-core subworkflows test mysubwf

Every nf-core module/subworkflow must ship passing nf-test tests (including a stub test) with committed snapshots; nf-core modules lint checks their presence. See references/developing.md.