164 lines
4.7 KiB
Markdown
164 lines
4.7 KiB
Markdown
(using-modules-page)=
|
|
|
|
# Using modules
|
|
|
|
:::{versionadded} 26.04.0
|
|
:::
|
|
|
|
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:
|
|
|
|
```console
|
|
$ 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 {ref}`module search <cli-module-search>` for the full command reference.
|
|
|
|
## Installing modules
|
|
|
|
Use the `module install` command to download modules from a registry into your project:
|
|
|
|
```console
|
|
$ nextflow module install nf-core/fastqc
|
|
$ nextflow module install nf-core/fastqc -version 0.0.0-0c7146d
|
|
```
|
|
|
|
:::{note}
|
|
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.
|
|
|
|
:::{tip}
|
|
Commit the `modules/` directory to your Git repository to ensure reproducibility.
|
|
:::
|
|
|
|
See {ref}`module install <cli-module-install>` for the full command reference.
|
|
|
|
## Listing installed modules
|
|
|
|
View all modules installed in your project with the `module list` command:
|
|
|
|
```console
|
|
$ 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 {ref}`module list <cli-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:
|
|
|
|
```console
|
|
$ 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 {ref}`module view <cli-module-view>` for the full command reference.
|
|
|
|
## Including modules
|
|
|
|
Modules installed from a registry can be included by name:
|
|
|
|
```nextflow
|
|
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:
|
|
|
|
```nextflow
|
|
include { FASTQC } from './modules/local/fastqc'
|
|
```
|
|
|
|
See {ref}`syntax-include` 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:
|
|
|
|
```console
|
|
$ nextflow module run nf-core/fastqc --meta.id test_sample --reads sample1_R1.fastq.gz
|
|
```
|
|
|
|
:::{tip}
|
|
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.):
|
|
|
|
```console
|
|
$ 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 `../`:
|
|
|
|
```console
|
|
$ nextflow module run ./modules/local/fastqc/main.nf \
|
|
--meta.id test_sample \
|
|
--reads sample1_R1.fastq.gz \
|
|
-with-docker
|
|
```
|
|
|
|
:::{note}
|
|
The local module should define a single process, or else the command will fail.
|
|
:::
|
|
|
|
See {ref}`module run <cli-module-run>` for the full command reference.
|
|
|
|
## Updating modules
|
|
|
|
To update a module to a newer version, reinstall it with the desired version:
|
|
|
|
```console
|
|
$ 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:
|
|
|
|
```console
|
|
$ nextflow module install nf-core/fastqc -version 0.0.0-c9h0bv4 -force
|
|
```
|
|
|
|
## Removing modules
|
|
|
|
Use the `module remove` command to uninstall a module from your project:
|
|
|
|
```console
|
|
$ 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-info` file but keep the module files in the `modules/` directory.
|
|
- `-force`: Remove the module directory even if it has no `.module-info` file or has local modifications.
|
|
|
|
See {ref}`module remove <cli-module-remove>` for the full command reference.
|