Skip to main content
The evm command is a developer utility for exercising the Ethereum Virtual Machine in isolation. It is useful for:
  • Running bytecode snippets and inspecting output or gas usage
  • Executing full state transitions for consensus testing (t8n)
  • Validating raw transactions against a fork spec (t9n)
  • Assembling sealed block RLPs (b11r)
  • Running the Ethereum state test suite

​
Installation

evm is built alongside the rest of go-ethereum: 
git clone https://github.com/ethereum/go-ethereum.git
cd go-ethereum
make all
# binary at ./build/bin/evm
Or install it directly: 
go install github.com/ethereum/go-ethereum/cmd/evm@latest

​
Subcommands

SubcommandAliasDescription
run—Execute arbitrary EVM bytecode
statetest—Run Ethereum state test JSON files
transitiont8nStateless state transition utility
transactiont9nValidate a set of raw transactions
block-builderb11rAssemble and seal a full block RLP
verklevktBinary trie helper commands

​
Running bytecode (evm run)

The run subcommand executes raw EVM bytecode against an in-memory state.

​
Basic usage

# Pass bytecode as the first positional argument (hex, no 0x prefix required).
evm run 6001600201

# Read bytecode from a file.
evm run --codefile contract.bin

# Read bytecode from stdin.
echo '6001600201' | evm run --codefile -

​
Tracing execution

Use --trace to emit a structured execution trace to stderr. 
# JSON trace (default format).
evm run --trace 6001600201

# Structured (human-readable) format.
evm run --trace --trace.format struct 6001600201

# Markdown format.
evm run --trace --trace.format md 6001600201

​
Example: PUSH and ADD

The bytecode 6001 6002 01 pushes 1 and 2 onto the stack, then adds them. 
evm run --trace --trace.format struct 6001600201
Expected output on stdout: 
0x03
With --trace --trace.format struct, stderr shows each opcode step, the stack state, gas consumed, and the final result.

​
Inspecting state after execution

# Dump the full post-execution state trie.
evm run --dump 6001600201

# Print memory and heap allocation stats.
evm run --statdump 6001600201

​
Benchmarking

evm run --bench 6001600201
--bench runs the bytecode repeatedly using Go’s testing benchmarker and prints average gas used, execution time, and allocations.

​
run flags reference

FlagDefaultDescription
--gas10000000000Gas limit for the execution
--price0Gas price (wei)
--value0ETH value sent with the call (wei)
--sender"sender"Originating address of the transaction
--receiver"receiver"Address of the contract being called
--input—ABI-encoded calldata (hex)
--inputfile—File containing calldata (hex)
--codefile—File containing bytecode. Use - for stdin.
--prestate—JSON genesis file used as the initial state
--createfalseTreat the execution as a contract creation rather than a call
--benchfalseBenchmark the execution
--dumpfalseDump the state trie after execution
--statdumpfalsePrint stack and heap memory info
FlagDefaultDescription
--tracefalseEnable opcode-level tracing
--trace.formatjsonTrace output format: json, struct, or md
--trace.nomemorytrueDisable memory output in traces
--trace.nostackfalseDisable stack output in traces
--trace.nostoragefalseDisable storage output in traces
--trace.noreturndatatrueDisable return data in traces

​
Running state tests (evm statetest)

The statetest subcommand runs Ethereum state test JSON files from the official test suite. 
# Run a single file.
evm statetest tests/GeneralStateTests/stExample/add11.json

# Run all JSON files in a directory.
evm statetest tests/GeneralStateTests/stExample/

# Restrict to a specific fork and emit a structured trace.
evm statetest --statetest.fork Berlin --trace tests/GeneralStateTests/stExample/add11.json

# Filter by test name (regex).
evm statetest --run 'add.*' tests/GeneralStateTests/stExample/

​
State transition tool (evm t8n)

The transition subcommand (alias t8n) applies a set of transactions to a pre-state and produces a post-state. It is the core primitive used in consensus testing across multiple client implementations. 
evm t8n \
  --input.alloc=alloc.json \
  --input.txs=txs.json \
  --input.env=env.json \
  --state.fork=Cancun \
  --output.result=result.json \
  --output.alloc=post-alloc.json
Pipe output to a second transition to chain blocks: 
evm t8n \
  --input.alloc=alloc.json \
  --input.txs=txs.json \
  --input.env=env.json \
  --state.fork=Berlin \
  --output.alloc=stdout \
| evm t8n \
  --input.alloc=stdin \
  --input.txs=txs2.json \
  --input.env=env2.json \
  --state.fork=Berlin
Pass stdout or stderr as the value for any --output.* flag to write that artifact to the corresponding stream instead of a file.

​
Transaction validation tool (evm t9n)

The transaction subcommand (alias t9n) validates raw transactions without applying them to state. 
evm t9n --state.fork London --input.txs testdata/signed_txs.rlp

​
Block builder tool (evm b11r)

The block-builder subcommand (alias b11r) assembles a complete block RLP from a header, transactions, and optional ommer/withdrawal data. 
evm b11r \
  --input.header=header.json \
  --input.txs=txs.rlp \
  --output.block=block.json

Build docs developers (and LLMs) love

Get started for freeTalk to us