Skip to main content

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.

Added in version 25.04

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 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).

note

The plugin cache is shared across pipelines and is not access-controlled. On multi-tenant or shared systems, use a private cache directory per user (set NXF_PLUGINS_DIR to a location only you can write) to avoid loading plugin artifacts populated by another user.

Lockfile​

Added in version 26.07

A plugins.lock file pins the exact plugin code a pipeline expects. For each plugin it records a sha512 hash of the extracted plugin directory — the code Nextflow actually loads and runs — keyed by id@version. The file is meant to be committed to the pipeline repository so that everyone running the pipeline executes the same plugin code.

The lockfile is populated automatically, like go.sum or package-lock.json — there is no separate command. To enable it, create an empty file in the pipeline directory and run the pipeline once:

touch plugins.lock

The first time each plugin is loaded, its hash is added to plugins.lock. Review the resulting file and commit it. On subsequent runs Nextflow re-hashes each plugin's extracted directory and verifies it against the committed hash. When no plugins.lock file is present, the feature is dormant and has no effect.

Verification is fully offline — it re-hashes the files already in the local cache and never contacts the plugin registry. Because it hashes the extracted code rather than the download, it detects both a tampered or compromised download and a plugin directory that was modified after extraction (for example by another user on a shared cache), independently of file ownership or permissions. An existing entry is never rewritten automatically — if a plugin legitimately changes, delete its entry and run again to re-pin it.

Use NXF_PLUGINS_LOCK_MODE to control what happens on a mismatch: warn (default) logs a warning and continues, strict aborts the run, and off skips verification.

The lockfile complements the private-cache guidance above: keeping the cache private prevents untrusted code from being written in the first place, while the lockfile detects any change to the plugin code that is actually loaded.

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:

  1. Install a self-contained version of Nextflow in an environment with an internet connection. See Standalone distribution for more information.

  2. 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.

  3. Copy the nextflow binary and $HOME/.nextflow directory to the offline environment.

  4. 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.

On this Page