Install & Compatibility
Where this runs
tested against v0.13.0b1 · 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
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 3.821s · 63.1MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 6.9s · import 3.656s · 66MB
65MB installed
● package 65MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
EthereumTester
✓ from eth_tester import EthereumTester
MockBackend
✓ from eth_tester import MockBackend
PyEVMBackend
✓ from eth_tester.backends.pyevm import PyEVMBackend
✗ from eth_tester import PyEVMBackend
PyEVMBackend is in a sub-module and requires the 'py-evm' extra to be installed.
GanacheBackend
✓ from eth_tester_ganache import GanacheBackend
✗ from eth_tester.backends.ganache import GanacheBackend
GanacheBackend is provided by the separate 'eth-tester-ganache' library.
This quickstart demonstrates how to initialize `EthereumTester` with the built-in `MockBackend`, retrieve accounts, mine blocks, check balances, and send a basic transaction. For full EVM functionality (e.g., real value transfers, contract deployment), a backend like `PyEVMBackend` is required.
from eth_tester import EthereumTester, MockBackend
from eth_utils import encode_hex, decode_hex
# 1. Initialize the EthereumTester with a MockBackend
# The MockBackend is a simple in-memory backend provided by eth-tester.
# It simulates basic blockchain interactions for testing purposes.
# For a full EVM, install with 'pip install eth-tester[py-evm]' and use PyEVMBackend.
tester = EthereumTester(backend=MockBackend())
print("EthereumTester initialized with MockBackend.")
# 2. Get available accounts
accounts = tester.get_accounts()
print(f"Available accounts: {[encode_hex(acc) for acc in accounts]}")
# 3. Mine a block
# Many operations, especially transactions, only take effect after a block is mined.
tester.mine_block()
print(f"Block mined. Current block number: {tester.get_block_by_number('latest')['number']}")
# 4. Get an account's balance
# In MockBackend, accounts start with a default balance.
account_0_address = accounts[0]
balance = tester.get_balance(account_0_address)
print(f"Balance of {encode_hex(account_0_address)}: {balance} wei")
# 5. Send a simple 'transaction' (e.g., a call) which is processed after mining.
# Note: MockBackend does not simulate value transfer or EVM state changes without a full EVM backend.
# This example primarily demonstrates the API for sending a transaction.
transaction_hash = tester.send_transaction({
'from': account_0_address,
'to': accounts[1], # Sending to another account (conceptual in MockBackend)
'gas_price': 0,
'gas': 21000,
'value': 0,
'data': b''
})
print(f"Transaction sent (hash: {encode_hex(transaction_hash)})")
# Mine another block for the transaction to be included
tester.mine_block()
print(f"Block mined. Current block number: {tester.get_block_by_number('latest')['number']}")
Debug
Known issues
breakingVersion 0.13.0b1 is a beta release. API stability is not guaranteed, and breaking changes may occur in subsequent beta or stable releases before 1.0.fixAlways pin `eth-tester` to a specific version (e.g., `eth-tester==0.13.0b1`) in your `requirements.txt` to prevent unexpected breaking changes during upgrades.
affects: 0.13.0b1 and potentially later 0.x.x beta versions
gotcha`eth-tester` itself is an abstraction layer; it requires a specific backend (like `PyEVMBackend` or `GanacheBackend`) to simulate a full EVM. Without a proper backend, functionality is limited (e.g., MockBackend doesn't execute EVM opcodes).fixInstall `eth-tester` with the desired backend extra (e.g., `pip install eth-tester[py-evm]`) and explicitly instantiate that backend (`PyEVMBackend()`) when creating `EthereumTester`.
affects: All versions
gotchaTransactions and many state changes within `eth-tester` (especially with `PyEVMBackend`) only take effect after a block has been mined. Forgetting to call `tester.mine_block()` can lead to unexpected state.fixEnsure `tester.mine_block()` is called after sending transactions or making changes that require block inclusion. For convenience in tests, consider using `tester.auto_mine_transactions = True`.
affects: All versions
gotchaWhile `eth-tester` provides an API, its most common and powerful use case is as the underlying provider for `web3.py`'s `Web3.EthereumTesterProvider`. Attempting to use `web3.py` methods directly on an `EthereumTester` instance will fail.fixWhen integrating with `web3.py`, initialize it as `w3 = Web3(Web3.EthereumTesterProvider(tester))` and then use `w3` for all `web3.py` interactions. Do not mix `tester` and `w3` APIs directly.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'eth_tester.backends.pyevm'
The `PyEVMBackend` was imported, but the `py-evm` dependency (and its corresponding extra) was not installed.
fixInstall `eth-tester` with the `py-evm` extra: `pip install eth-tester[py-evm]`.
AttributeError: 'EthereumTester' object has no attribute 'eth'
Attempting to use `web3.py`'s `w3.eth` object methods (like `w3.eth.send_transaction`) directly on an `EthereumTester` instance.
fixWhen using `web3.py` with `eth-tester`, create a `web3` instance using the `EthereumTesterProvider`: `from web3 import Web3; w3 = Web3(Web3.EthereumTesterProvider(tester))` then use `w3.eth...`.
eth_tester.exceptions.TransactionFailed: Transaction failed: 'out of gas'
A transaction submitted to the `eth-tester` backend (especially `PyEVMBackend`) ran out of gas, often due to an incorrect gas limit, an invalid operation, or a contract revert.
fixReview the transaction parameters (gas limit, data) and the contract logic. Increase the `gas` amount in the transaction, or inspect the transaction trace to find the failing opcode (requires a debugging backend).
ValueError: block number out of bounds
Attempting to query a block number that has not yet been mined in the tester.
fixEnsure you have mined enough blocks with `tester.mine_block()` to reach the desired block number before attempting to query it.
Upgrade
Version history
0.13.0b1latest on PyPI · released Apr 23, 2025
Audit
Dependencies
py-evmoptionalProvides the PyEVM backend, which is commonly used for local EVM simulation. `eth-tester` requires a backend to function beyond basic mocking.
eth-utilsrequiredUtility functions for Ethereum, often used in conjunction with eth-tester for data encoding/decoding.