Skip to main content

nextflow module

Added in version 26.04

Manage Nextflow modules.

Usage​

$ nextflow module <subcommand> [options]

Description​

The module command manages registry-based modules. Use it to install modules from a registry, run them directly, search for available modules, and publish your own modules to a registry.

Options​

-h, -help​

Print the command usage.

Subcommands​

create [namespace/name]​

Create a new module with a basic main.nf, meta.yml, and README.md.

install [options] [namespace/name]​

Install a module from the registry into your project. Nextflow stores downloaded modules in the modules/ directory and writes a .module-info file in each module directory to record the installed version.

The following options are available:

-version​

Module version to install, for example 1.0.0. Defaults to the latest version.

-force​

Reinstall the module even if a locally modified copy exists. Without this flag, Nextflow does not overwrite locally modified modules.

list [options]​

List the modules installed in your project. Shows each module's name, version, and integrity status, which reports whether the module was modified locally.

The following options are available:

-o, -output (table)​

Output mode for list results. Options: table (default), json.

publish [options] [namespace/name | path]​

Publish a module to the registry so that others can install it. The argument can be either a namespace/name reference to an already-installed module, or a local directory path containing the module files. Authenticate with the NXF_REGISTRY_TOKEN environment variable or the registry.apiKey config option. The module directory must contain main.nf, meta.yml, and README.md.

The following options are available:

-dry-run​

Validate the module structure and metadata without uploading it to the registry.

-registry​

Registry to publish the module to (default: https://registry.nextflow.io).

remove [options] [namespace/name]​

Remove a module from your project. By default, removes both the local files and the configuration entries.

The following options are available:

-force​

Remove the module even if it has local modifications, or has no .module-info file because it was not installed from a registry.

-keep-files​

Remove the .module-info file but keep the local files in the modules/ directory.

run [options] [namespace/name | path] [--<input_name> <input-value>]​

Run a module directly. The argument can be a remote module (namespace/name) or a local module path beginning with ./, ../, or /. Nextflow downloads the module if it is not already installed.

Accepts all standard Nextflow run options, such as -profile, -resume, and -c. Nextflow infers the command-line params, written as --<input_name>, from the module's declared inputs.

The following additional options are available:

-version​

Module version to run, for example 1.0.0. Defaults to the latest version.

Search for modules in the registry by keyword or name. Returns the matching modules with their names, versions, descriptions, and download statistics.

The following options are available:

-limit​

Maximum number of results to return (default: varies by registry).

-o, -output (simple)​

Output mode for search results. Options: simple (default), json.

spec [options] <namespace/name or path>​

Generate the meta.yml for a local module from the source code (main.nf).

The generated file includes TODO placeholders for fields you do not specify. If a spec file already exists, Nextflow incorporates it into the new file.

The following options are available:

-namespace <namespace>​

Module namespace, used to construct the module name. Required when the argument is a path, and ignored when it is a module name.

-version <version>​

Module version string, for example 1.0.0. Defaults to TODO: Add version.

-description <text>​

Short description of what the module does. Defaults to TODO: Add description.

-license <identifier>​

SPDX license identifier, for example MIT or Apache-2.0. Defaults to TODO: Add license (e.g., MIT).

-author <name>​

Module author. Can be specified multiple times, once per author. Defaults to [TODO: Add author].

-dry-run​

Print the generated spec to standard output without writing any file.

view [options] [namespace/name]​

Display detailed information about a module from the registry. Shows the module name, version, description, and other metadata, along with example usage.

The following options are available:

-version​

Module version to query, for example 1.0.0. Defaults to the latest version.

-o, -output (text)​

Output mode for info results. Options: text (default), json.

validate [options] <scope/name or path>​

Validate a module before publishing to the registry.

Verifies that the required files main.nf, meta.yml, and README.md are present, and that the module spec contains the required name, version, description, and license fields.

Examples​

Install the latest module version:

$ nextflow module install nf-core/fastqc

Display the installed modules as a table:

$ nextflow module list

Validate the module structure without publishing:

$ nextflow module publish myorg/my-module -dry-run

Publish a module to the Nextflow registry:

$ export NXF_REGISTRY_TOKEN=your-token
$ nextflow module publish myorg/my-module

Display information for the latest module version:

$ nextflow module view nf-core/fastqc

Display information for a specific version:

$ nextflow module view nf-core/fastqc -version 1.0.0

Create a module:

$ nextflow module create

Remove a module completely:

$ nextflow module remove nf-core/fastqc

Run a remote module:

$ nextflow module run nf-core/fastqc \
    --input 'data/*.fastq.gz'

Run a remote module with a specific version and run options:

$ nextflow module run nf-core/fastqc \
    -version 1.0.0 \
    --input 'data/*.fastq.gz' \
    -with-conda \
    -resume

Run a local module:

$ nextflow module run ./modules/nf-core/fastqc/main.nf \
      --input 'data/*.fastq.gz'

Search for alignment-related modules:

$ nextflow module search alignment

Generate a spec for a local module by name:

$ nextflow module spec nf-core/fastqc

Generate a spec for a local module by path, which requires a namespace:

$ nextflow module spec -namespace nf-core ./modules/my-module

Provide additional fields to avoid TODO placeholders:

$ nextflow module spec \
    -namespace nf-core \
    -version 1.0.0 \
    -description "Quality control of raw sequencing reads" \
    -license MIT \
    -author "@drpatelh" \
    -author "@joseespinosa" \
    ./modules/nf-core/fastqc

Validate a module by name:

$ nextflow module validate myorg/my-module

Validate a module by path:

$ nextflow module validate ./modules/myorg/my-module
On this Page