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 [options] [namespace/name]

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

The following options are available:

-kind (Process)

The kind of module to scaffold: Process (default) or Workflow.

-legacy

Scaffold a module without static typing. By default a module is scaffolded with typed input/output declarations.

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:

-force

Reinstall the module even if it is already installed. Without this flag, Nextflow reuses an installed module and does not overwrite a locally modified one.

-update-deps

Re-vendor an installed module's dependencies from its meta.yml, leaving the module itself untouched. Nextflow installs each declared dependency at its pinned version, transitively, and removes any of the module's own direct dependencies that are no longer declared. If the module is not installed, Nextflow installs it as usual. Cannot be combined with -force.

-version

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

list [options]

List the modules installed in your project. Shows each module's name, version, kind (Process or Workflow), 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. Workflow modules must be typed in order to be executed with nextflow module run.

The following additional options are available:

-version

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

search [options] [query]

Search for modules in the registry by keyword or name. Returns the name and description of each matching module.

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:

• All required files are present (main.nf, meta.yml, README.md).
• The module spec contains all required fields (name, version, description, and license).
• Every module included by the module script is a registry module, not a local module.
• The dependencies declared in requires.modules are exactly the modules included by the module script, each pinned to an exact version.

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