Skip to content
You are reading Hyperledger Besu development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.
Last update: September 2, 2021

EVM tool

The Besu EVM tool is a CLI program that executes arbitrary EVM programs and Ethereum State Tests outside the context of an operating node. Use the EVM tool for benchmarking and fuzz testing.

Getting the EVM tool

The Besu EVM tool does not have a standard zip file distribution. To use, you need to either build from the source repository or use a pre-published docker image.

Building from source

To build from source, run the following from the root of the Besu repository:

./gradlew :ethereum:evmTool:installDist

An extractable archive files is created in ethereum/evmtool/build/distributions and an executable installation in ethereum/evmtool/build/install/evmtool.

Execute the EVM tool:

ethereum/evmtool/build/install/evmtool/bin/evm <evmtool options>

Executing with Docker

To run the Besu EVM tool in a container:

docker run -rm <docker options> hyperledger/besu-evmtool:develop <evmtool options>
  • Because no data is stored in local directories we recommended using the -rm docker option. The -rm option deletes the container at the end of execution.
  • If you use an option that requires input from standard in, use the -i docker option. The -i option pipes standard input to the EVM tool.
  • If you need to reference files we recommend using a docker file binding, such as -v ${PWD}:/opt/data, which maps the current directory to the /opt/data directory in the container.


The latest tag is the latest released version of Besu, starting with 1.5.3. The develop tag is the current main branch code that will go into a future release version of Besu.

EVM tool run options

The first mode of the EVM tool runs an arbitrary EVM and is invoked without an extra command. Command line options specify the code and other contextual information.

The EVM tool also has a state-test sub command that allows the Ethereum State Tests to be evaluated. Most of the options from EVM execution do not apply.

The EVM tool reference provides more information on both modes.

Questions or feedback? You can discuss issues and obtain free support on Hyperledger Besu chat channel.
For Hyperledger Besu community support, contact the mailing list