Install & Compatibility
Where this runs
tested against v0.3.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 1.9s
py 3.11
✕ build_error
✓ 2.15s
py 3.12
✕ build_error
✓ 1.75s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 2.9s
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
EVM
✓ from pyrevm import EVM
CfgEnv
✓ from pyrevm import CfgEnv
BlockEnv
✓ from pyrevm import BlockEnv
TxEnv
✓ from pyrevm import TxEnv
This quickstart demonstrates how to initialize an EVM instance, set up account states, and simulate both a contract call and a value transfer transaction using `pyrevm`. It requires `pyrevm` to be installed. Addresses and contract bytecode are provided as raw bytes for simplicity.
from pyrevm import EVM, CfgEnv, BlockEnv, TxEnv
# Example setup: a simple contract and an account
# Contract that returns 0 for a specific function call
CONTRACT_CODE = bytes.fromhex("6080604052348015600f57600080fd5b506004361060285760003560e01c806306fdde0314602d575b600080fd5b603a603c565b005b60005481565b")
CONTRACT_ADDRESS = bytes.fromhex("1234567890123456789012345678901234567890")
CALLER_ADDRESS = bytes.fromhex("abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd")
# Function selector for the example contract (returns 0)
FUNCTION_SELECTOR = bytes.fromhex("06fdde03")
def run_evm_simulation():
# 1. Initialize environment configurations
cfg_env = CfgEnv(chain_id=1)
block_env = BlockEnv(
number=1, timestamp=1, gas_limit=1_000_000_000,
miner=bytes.fromhex("0000000000000000000000000000000000000000"), basefee=1
)
tx_env = TxEnv(
caller=CALLER_ADDRESS, gas_limit=1_000_000_000, gas_price=1, value=0,
data=FUNCTION_SELECTOR, transact_to=CONTRACT_ADDRESS
)
# 2. Create an EVM instance
evm = EVM(
cfg=cfg_env,
block=block_env,
tx=tx_env # Initial transaction environment
)
# 3. Insert initial state (e.g., contract code and account balances)
evm.insert_account_info(
CONTRACT_ADDRESS,
code=CONTRACT_CODE,
balance=0,
nonce=0
)
# Give caller some balance for transactions
evm.insert_account_info(
CALLER_ADDRESS,
balance=1_000_000_000_000_000_000, # 1 ETH
nonce=0
)
# 4. Perform a contract call
call_result = evm.call_raw() # Uses tx_env set during EVM init
print(f"--- Contract Call Simulation ---")
print(f"Status: {call_result.status}")
print(f"Gas Used: {call_result.gas_used}")
print(f"Exit Reason: {call_result.exit_reason}")
print(f"Output: {call_result.result.hex()}")
# 5. Perform a simple value transfer transaction
recipient_address = bytes.fromhex("feeefeeefeeefeeefeeefeeefeeefeeefeeefeee")
transfer_amount = 1000 # wei
# Update tx_env for the transaction
tx_env.data = b'' # No data for simple transfer
tx_env.transact_to = recipient_address
tx_env.value = transfer_amount
# Perform the transaction
transact_result = evm.transact_raw() # Uses updated tx_env
print(f"\n--- Value Transfer Simulation ---")
print(f"Status: {transact_result.status}")
print(f"Gas Used: {transact_result.gas_used}")
print(f"Exit Reason: {transact_result.exit_reason}")
print(f"Output: {transact_result.result.hex()}")
if __name__ == "__main__":
run_evm_simulation()
Debug
Known issues
gotchapyrevm builds on a Rust core (revm). If pre-built wheels are not available for your specific Python version and operating system/architecture, you might need a Rust toolchain installed for `pip install` to compile from source. This is common on less mainstream platforms or with newer Python versions immediately after release.fixEnsure Rust and Cargo are installed (e.g., `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`). Prefer installing pre-built wheels when possible.
affects: All versions
gotchaThe EVM instance in `pyrevm` holds an in-memory state. Any changes (like balance transfers or contract state modifications) are local to that EVM instance. If you create a new `EVM` object, it starts with an empty state unless explicitly populated. State changes from one `EVM` object do not automatically persist to another.fixManage EVM instances carefully. For persistent state across multiple operations or snapshots, ensure you are either using the same `EVM` object or explicitly transferring/copying state as needed (e.g., via `evm.context.evm.clone()`).
affects: All versions
breakingAPI changes in the underlying `revm` Rust library can lead to breaking changes in `pyrevm`'s Python API. While efforts are made to maintain compatibility, major version bumps of `revm` often cascade, affecting method signatures, class structures, or enum variants in `pyrevm`.fixAlways check the `pyrevm` and `revm` release notes when upgrading to a new major or minor version. Adapt your code to the updated API, paying close attention to `CfgEnv`, `BlockEnv`, `TxEnv`, and `EVM` constructor arguments and method calls.
affects: Major version bumps (e.x., 0.x.y to 0.x+1.y)
Errors
Common errors & fixes
No module named 'pyrevm'
The pyrevm library is not installed or not available in the current Python environment.
fixRun `pip install pyrevm` in your terminal to install the library.
PyRevmError: EVM ran out of gas
The transaction or call simulation exceeded the provided gas limit, or the block's gas limit.
fixIncrease the `gas_limit` in your `TxEnv` and `BlockEnv` objects. For example, set `gas_limit=1_000_000_000` for a high limit during development, or analyze the required gas for your specific operation.
OSError: [Errno 99] Cannot assign requested address: Couldn't connect to remote EVM.
While less common for pyrevm (which is usually local), if you are attempting to integrate with a remote EVM or a service that pyrevm might internally try to connect to, this indicates a network connectivity issue or an invalid address/port.
fixVerify that any target addresses or network configurations in your setup are correct and reachable. Ensure no firewalls are blocking connections if attempting to reach an external service. For local pyrevm, this error is generally not applicable unless misconfigured.
PyRevmError: Invalid bytecode/contract code or input data
The bytecode provided to `insert_account_info` or the `data` field in `TxEnv` is malformed, not valid EVM bytecode, or does not match the expected function signature.
fixDouble-check the source of your contract bytecode and ensure it is correctly compiled and passed as raw bytes. Verify that function selectors and arguments in `tx_env.data` are correctly formatted for the contract you are interacting with.
Upgrade
Version history
0.3.7latest on PyPI · released Jan 28, 2026
Audit
Dependencies
No dependency data recorded yet.