Using plugins

Nextflow core plugins require no additional configuration. When a pipeline uses a core plugin, Nextflow automatically downloads and uses the latest compatible plugin version. In contrast, third-party plugins must be explicitly declared. When a pipeline uses one or more third-party plugins, Nextflow must be configured to download and use the plugin.

Identifiers

A plugin identifier consists of the plugin name and version, separated by an @ symbol:

nf-hello@0.5.0

The plugin version is optional. If it is not specified, Nextflow will download the latest version of the plugin that meets the minimum Nextflow version requirements specified by the plugin.

Note

Plugin versions are required for offline usage.

New in version 25.02.0-edge.

The plugin version can be prefixed with ~ to pin the major and minor versions and allow the latest patch release to be used. For example, nf-amazon@~2.9.0 will resolve to the latest version matching 2.9.x. When working offline, Nextflow will resolve version ranges against the local plugin cache defined by NXF_PLUGINS_DIR.

Tip

It is recommended to pin the major and minor version of each plugin that you use, in order to minimize the risk of breaking changes while allowing patch updates to be used automatically.

Configuration

Plugins can be configured via Nextflow configuration files or at runtime.

To configure a plugin via configuration files, use the plugins block. For example:

plugins {
    id 'nf-hello@0.5.0'
    id 'nf-amazon@2.9.0'
}

To configure plugins at runtime, use the -plugins option. For example:

nextflow run main.nf -plugins nf-hello@0.5.0,nf-amazon@2.9.0

Note

Plugin declarations in Nextflow configuration files are ignored when specifying plugins via the -plugins option.

Caching

When Nextflow downloads plugins, it caches them in the directory specified by NXF_PLUGINS_DIR ($HOME/.nextflow/plugins by default).

Offline usage

When running Nextflow in an offline environment, any required plugins must be downloaded and moved into the offline environment prior to any runs.

To use Nextflow plugins in an offline environment:

Install a self-contained version of Nextflow in an environment with an internet connection. See Standalone distribution for more information.
Run nextflow plugin install <PLUGIN_NAME>@<VERSION> for each required plugin to download it. Alternatively, run the pipeline once, which will automatically download all plugins required by the pipeline.
Copy the nextflow binary and $HOME/.nextflow directory to the offline environment.
Specify each plugin and its version in Nextflow configuration files or at runtime. See Configuration for more information.

Warning

Nextflow will attempt to download newer versions of plugins if their versions are not set. See Identifiers for more information.