---
title: Using the Nextflow Gradle plugin
description: Use the Nextflow Gradle plugin to build, test, and publish Nextflow plugins.
---

# Using the Nextflow Gradle plugin

Nextflow provides a new `plugin create` command that simplifies the creation of Nextflow plugins. This command leverages the [nf-plugin-template](https://github.com/nextflow-io/nf-plugin-template) project, which uses the [Nextflow Gradle plugin](https://github.com/nextflow-io/nextflow-plugin-gradle) to streamline plugin development.

The [Nextflow Gradle plugin](https://github.com/nextflow-io/nextflow-plugin-gradle) configures default dependencies needed for Nextflow integration and defines Gradle tasks for building, testing, and publishing Nextflow plugins. The Gradle plugin is versioned and published to the [Gradle Plugin Portal](https://plugins.gradle.org/), allowing developers to manage it like any other dependency. As the plugin ecosystem evolves, the Gradle plugin will enable easier maintenance and adoption of improvements. This page introduces [Nextflow Gradle plugin](https://github.com/nextflow-io/nextflow-plugin-gradle) and how to use it.

## Creating a plugin

<AddedInVersion version="25.04" />

The best way to create a plugin with the Nextflow Gradle plugin is to use the `nextflow plugin create` sub-command and create a plugin project based on the [Nextflow plugin template](https://github.com/nextflow-io/nf-plugin-template/). See [Nextflow plugin template][dev-plugins-template] for more information about the Nextflow plugin template.

To create Nextflow plugins with the Gradle plugin:

1. Run `nextflow plugin create`.

2. Follow the prompts to add your plugin name, plugin provider, and project path.

    :::note
    Your plugin provider is usually your organization. This must match the provider specified when claiming your plugin.
    :::

3. Develop your plugin extension points. See [Extension points][dev-plugins-extension-points] for more information.

4. Develop your tests. See [Testing a plugin][gradle-plugin-test] for more information.

5. In the plugin root directory, run `make assemble`.

## Installing a plugin

Plugins can be installed locally without being published.

To install plugins locally:

1. In the plugin root directory, run `make install`.

    :::note
    Running `make install` will add your plugin to your `$HOME/.nextflow/plugins` directory.
    :::

2. Run your pipeline:

    ```bash
    nextflow run main.nf -plugins <plugin-name>@<version>
    ```

    Replace `<plugin-name>@<version>` with your plugin name and version.

    :::note
    Plugins can also be configured via Nextflow configuration files. See [Using plugins][using-plugins-page] for more information.
    :::

## Testing a plugin

Testing your Nextflow plugin requires unit tests and end-to-end tests.

<h3>Unit tests</h3>

Unit tests are small, focused tests designed to verify the behavior of individual plugin components.

To run unit tests:

1. Develop your unit tests. See [MyObserverTest.groovy](https://github.com/nextflow-io/nf-plugin-template/blob/main/src/test/groovy/acme/plugin/MyObserverTest.groovy) in the [plugin template](https://github.com/nextflow-io/nf-plugin-template) for an example unit test.

2. In the plugin root directory, run `make test`.

<h3>End-to-end tests</h3>

End-to-end tests are comprehensive tests that verify the behavior of an entire plugin as it would be used in Nextflow pipelines.

End-to-end tests should be tailored to the needs of your plugin, but generally take the form of a small Nextflow pipeline. See the `validation` directory in the [plugin template](https://github.com/nextflow-io/nf-plugin-template) for an example end-to-end test.

## Publishing a plugin

The Nextflow Gradle plugin allows you to publish plugins to the [Nextflow plugin registry](https://registry.nextflow.io/) from the command line.

### README.md requirement

When publishing to the registry, your project must include a `README.md` file in the plugin project root directory. This file will be used as the plugin description in the registry.

**Required sections:**

1. **Summary** - Explain what the plugin does
2. **Get Started** - Setup and configuration instructions
3. #### Examples - Code examples with code blocks
4. **License** - Specify the plugin's license (e.g., Apache 2.0, MIT, GPL)

**Optional sections:**

- **What's new** - Recent changes or new features
- **Breaking changes** - Incompatible changes users should be aware of

**Requirements:**

- Content must be meaningful (no placeholder text like TODO, TBD, Lorem ipsum)
- Content must be in English

### Publishing steps

To publish plugins to the [Nextflow plugin registry](https://registry.nextflow.io/):

1. [Claim your plugin][plugin-registry-claim] in the registry.

    :::note
    You can claim a plugin even if it doesn't exist in the registry yet.
    :::

2. Create a file named `$HOME/.gradle/gradle.properties`, where `$HOME` is your home directory.

3. Add your API key to the file:

    ```
    npr.apiKey=<api-key>
    ```

    Replace `<api-key>` with your plugin registry API key. See [Creating an access token][plugin-registry-access-token] for more information.

4. Run `make release`.

## Additional resources

For additional Nextflow Gradle plugin configuration options, see the [Nextflow Gradle plugin](https://github.com/nextflow-io/nextflow-plugin-gradle) repository.

[plugin-registry-claim]: ../plugins/plugin-registry#claiming-a-plugin
[dev-plugins-extension-points]: ../plugins/developing-plugins#extension-points
[dev-plugins-template]: ../plugins/developing-plugins#nextflow-plugin-template
[gradle-plugin-page]: ./gradle-plugin
[gradle-plugin-test]: ./gradle-plugin#testing-a-plugin
[plugin-page-migrate]: ./migrate-plugin
[plugin-registry-claim]: ../plugins/plugin-registry#claiming-a-plugin
[plugin-registry-access-token]: ../plugins/plugin-registry#creating-an-access-token
[plugin-registry-page]: ../plugins/plugin-registry
[using-plugins-page]: ../plugins/using-plugins
