For AI agents: a documentation index is available at /llms.txt. Markdown versions of pages are available by appending .md to any documentation URL.
Skip to main content

Deploy a plugin

Build your plugin distribution and deploy it to a running Besu installation.

Prerequisites​

Steps​

1. Build the distribution​

Run the distZip task provided by the Gradle plugin to package your plugin:

./gradlew distZip

The output archive at build/distributions/<project-name>.zip contains only your plugin JAR and any extra runtime dependencies that Besu does not already provide. JARs already in Besu's lib directory are excluded from the ZIP.

tip

If your plugin has no extra dependencies, the ZIP contains a single JAR.

To inspect the contents of the archive before deploying:

unzip -l build/distributions/<project-name>.zip

2. Deploy to Besu​

The method for deploying your plugin depends on how you installed Besu.

Standard installation​

Create a plugins directory at the root of your Besu installation if it doesn't already exist, then unzip the archive into it. The -j flag flattens the ZIP so all JARs land directly in plugins/:

unzip -j build/distributions/<project-name>.zip -d /path/to/besu/plugins/

Start Besu. By default, Besu loads all JARs found in the plugins directory automatically. To load only specific plugins, pass a comma-separated list to --plugins.

Homebrew​

The installation lives in the Homebrew Cellar (for example, /opt/homebrew/Cellar/besu/<version>, which brew --prefix besu resolves to). By default, Besu looks for plugins in a plugins directory there, but Homebrew replaces the entire Cellar directory on brew upgrade, which removes any plugins you add.

Instead, keep your plugins in a stable location outside the Cellar and point Besu at it using the besu.plugins.dir system property via BESU_OPTS:

mkdir -p ~/besu/plugins
unzip -j build/distributions/<project-name>.zip -d ~/besu/plugins/

export BESU_OPTS="-Dbesu.plugins.dir=$HOME/besu/plugins"
besu [options]

Docker​

The Besu Docker image doesn't include a plugins directory. Use a bind mount to inject your plugin JARs into the container at /opt/besu/plugins:

# Unzip the distribution into a local directory.
unzip -j build/distributions/<project-name>.zip -d /host/path/to/plugins/

# Mount that directory when starting the container.
docker run \
  -v /host/path/to/plugins:/opt/besu/plugins \
  hyperledger/besu:latest

To use a different path inside the container, override the plugins directory using the besu.plugins.dir system property via BESU_OPTS:

docker run \
  -e BESU_OPTS="-Dbesu.plugins.dir=/data/plugins" \
  -v /host/path/to/plugins:/data/plugins \
  hyperledger/besu:latest

3. Verify startup​

Check the Besu startup logs to confirm your plugin was detected and registered. Besu logs a plugin registration summary that lists registered plugins and any plugins that were detected but skipped.

Use --plugins-verification-mode to control how Besu handles plugin verification failures:

  • NONE (default) logs a warning and continues.
  • FULL logs an error and stops Besu.

Next steps​

Troubleshoot common issues.