---
title: nextflow module
description: Reference for the nextflow module command. Manage Nextflow modules.
---

# `nextflow module`

<AddedInVersion version="26.04" />

Manage Nextflow modules.

## Usage

```console
$ 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]` {#module-create}

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

##### `install [options] [namespace/name]` {#module-install}

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]` {#module-list}

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]` {#module-publish}

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]` {#module-remove}

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>]` {#module-run}

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 [options] [query]` {#module-search}

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>` {#module-spec}

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]` {#module-view}

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>` {#module-validate}

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:

```console
$ nextflow module install nf-core/fastqc
```

Display the installed modules as a table:

```console
$ nextflow module list
```

Validate the module structure without publishing:

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

Publish a module to the Nextflow registry:

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

Display information for the latest module version:

```console
$ nextflow module view nf-core/fastqc
```

Display information for a specific version:

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

Create a module:

```console
$ nextflow module create
```

Remove a module completely:

```console
$ nextflow module remove nf-core/fastqc
```

Run a remote module:

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

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

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

Run a local module:

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

Search for alignment-related modules:

```console
$ nextflow module search alignment
```

Generate a spec for a local module by name:

```console
$ nextflow module spec nf-core/fastqc
```

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

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

Provide additional fields to avoid `TODO` placeholders:

```console
$ 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:

```console
$ nextflow module validate myorg/my-module
```

Validate a module by path:

```console
$ nextflow module validate ./modules/myorg/my-module
```
