Using modules
The Nextflow module system allows you to discover, install, and manage reusable modules from centralized registries. This page describes how to use modules in your pipelines.
Discovering modules
Search for available modules using the module search command:
$ nextflow module search alignment
$ nextflow module search "quality control" -limit 10
Results include module names and descriptions.
Use -output json for machine-readable output.
See module search for the full command reference.
Installing modules
Use the module install command to download modules from a registry into your project:
$ nextflow module install nf-core/fastqc
$ nextflow module install nf-core/fastqc -version 0.0.0-0c7146d
Modules mirrored from nf-core do not follow standard semantic versioning.
Instead, they use the format 0.0.0-<hash>, where the suffix is a short portion of the nf-core module's commit hash.
Nextflow stores installed modules in the modules/ directory and creates a .module-info file alongside the module to record installation metadata such as the module checksum and registry URL.
Commit the modules/ directory to your Git repository to ensure reproducibility.
See module install for the full command reference.
Listing installed modules
View all modules installed in your project with the module list command:
$ nextflow module list
The output shows each module's name, installed version, and whether it has been modified locally.
Use -output json for machine-readable output.
See module list for the full command reference.
Viewing module information
Use the module view command to view metadata and a usage template for a module:
$ nextflow module view nf-core/fastqc
$ nextflow module view nf-core/fastqc -version 0.0.0-0c7146d
The output includes the module's version, URL, description, authors, maintainers, keywords, tools, input/output channels, and a generated usage template.
Use -output json for machine-readable output.
See module view for the full command reference.
Including modules
Modules installed from a registry can be included by name:
include { FASTQC } from 'nf-core/fastqc'
workflow {
reads = channel.fromPath('data/*.fastq')
reads = reads.map { fastq -> tuple([id: fastq.baseName], fastq) }
FASTQC(reads)
}
Local modules must be included by relative path:
include { FASTQC } from './modules/local/fastqc'
See include declarations for a full description of the include syntax.
Running modules directly
For ad-hoc tasks or testing, run a module directly without creating a wrapper workflow:
$ nextflow module run nf-core/fastqc --meta.id test_sample --reads sample1_R1.fastq.gz
Run nextflow module view to see the available inputs for a module.
The command automatically downloads the module if it is not already installed.
It accepts all standard Nextflow run options (-profile, -resume, etc.):
$ nextflow module run nf-core/fastqc \
--meta.id test_sample \
--reads sample1_R1.fastq.gz \
-with-docker
Run a local module by specifying a path starting with ./ or ../:
$ nextflow module run ./modules/local/fastqc/main.nf \
--meta.id test_sample \
--reads sample1_R1.fastq.gz \
-with-docker
The local module must define a single process or named workflow.
See module run for the full command reference. Parameters are inferred from the module's declared inputs: the Type conversions are handled the same way as typed parameters. Workflow modules use the following additional rules for dataflow types: A A Consider the following workflow: It can be run directly: Workflow modules must be typed in order to be executed directly. Process modules do not need to be typed. Each declared output is reported as a workflow output. Output files are reported by their work directory path; they are not published to an output directory.Module parameters
input: section for a process, or the take: section for a named workflow.
Channel<E> input accepts a samplesheet path, which Nextflow loads as a channel of records. The samplesheet file can be CSV, JSON, or YAML. The element type must be Map, Record, or a record type. Each row is validated against and converted to the declared type.Value<V> input accepts a value of type V, which Nextflow wraps in a value channel.nextflow.enable.types = true
workflow RNASEQ {
take:
samples: Channel<Sample>
index: Value<Path>
strandedness: String?
main:
// ...
emit:
aligned: Channel<AlignedSample> = ch_aligned
}
record Sample {
id: String
fastq_1: Path
fastq_2: Path
}
record AlignedSample { /* ... */ }$ nextflow module run ./rnaseq.nf \
--samples samples.csv \
--index genome.faModule outputs
Updating modules
To update a module to a newer version, reinstall it with the desired version:
$ nextflow module install nf-core/fastqc -version 0.0.0-c9h0bv4
Nextflow automatically verifies module integrity using a checksum stored in the .module-info file.
If the module has local modifications, it will not be updated.
Use the -force flag to overwrite local changes:
$ nextflow module install nf-core/fastqc -version 0.0.0-c9h0bv4 -force
Updating a workflow module's dependencies
A workflow module declares its dependencies in meta.yml (requires.modules), and they are vendored under the module's own modules/ directory. If you edit the declared dependency versions of an already-installed module by hand, use -update-deps to re-vendor them to match the edited meta.yml, without reinstalling the module itself:
$ nextflow module install nf-core/my-workflow -update-deps
This installs newly declared dependencies, updates changed versions, and removes dependencies that are no longer declared. A vendored dependency with local modifications is not overwritten or removed; an error is raised instead. The module itself is left untouched, so its local (unpublished) modification status is preserved.
Removing modules
Use the module remove command to uninstall a module from your project:
$ nextflow module remove nf-core/fastqc
By default, Nextflow removes both the module files and the .module-info file.
Use flags to control this behavior:
-keep-files: Remove the.module-infofile but keep the module files in themodules/directory.-force: Remove the module directory even if it has no.module-infofile or has local modifications.
See module remove for the full command reference.