Install & Compatibility
Where this runs
tested against v0.12.1b1 · 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.95 runs
installs and imports cleanly · install 0.0s · import 4.578s · 55.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.3s · import 4.328s · 58MB
56MB installed
● package 56MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MainnetChain
✓ from eth.chains.mainnet import MainnetChain
AtomicDB
✓ from eth.db.atomic import AtomicDB
GAS_LIMIT
✓ from eth.constants import GAS_LIMIT
to_wei
✓ from eth_utils import to_wei
encode_hex
✓ from eth_utils import encode_hex
Address
✓ from eth_typing import Address
This quickstart demonstrates how to initialize a basic Ethereum chain and Virtual Machine (VM) using Py-EVM. It sets up an in-memory database, pre-funds a mock address, and then retrieves the current block number and the balance of the pre-funded address. This provides a minimal runnable example of interacting with Py-EVM's core components for simulating EVM behavior.
import os
from eth import constants
from eth.chains.mainnet import MainnetChain
from eth.db.atomic import AtomicDB
from eth_utils import to_wei, encode_hex
from eth_typing import Address
def run_evm_example():
# Setup a mock address and initial balance
MOCK_ADDRESS = Address(b'\x00' * 19 + b'\x01') # An arbitrary address
PREFUND_AMOUNT = to_wei(100, 'ether')
# Initialize a new chain with an atomic database
# AtomicDB is an in-memory database suitable for tests and examples
chain = MainnetChain.from_genesis(
AtomicDB(),
genesis_state={
MOCK_ADDRESS: {
'balance': PREFUND_AMOUNT,
'nonce': 0,
'code': b'',
'storage': {}
}
},
genesis_header_params={
'gas_limit': constants.GAS_LIMIT,
'difficulty': 1 # Simplified difficulty for non-PoW chain
}
)
# Get the current VM from the chain
vm = chain.get_vm()
print(f"Chain created successfully. Current block number: {vm.get_block().header.block_number}")
print(f"Balance of {encode_hex(MOCK_ADDRESS)}: {vm.get_balance(MOCK_ADDRESS)} Wei")
# Example: Accessing a constant
print(f"Default transaction gas limit: {constants.GAS_LIMIT}")
if __name__ == "__main__":
run_evm_example()
Debug
Known issues
breakingThe Py-EVM project has been officially archived and is now read-only. No further development, feature additions, or bug fixes are planned by the maintainers. Users should be aware that the library is no longer actively maintained.fixConsider migrating to actively maintained EVM implementations if ongoing support and new feature compatibility are required. This library is best suited for historical research or specific, isolated use cases related to the Prague fork or earlier.
affects: All versions from 0.12.1b1 onwards (as of May 2025)
breakingPy-EVM's last officially supported Ethereum hard fork is Prague. It does not include support for subsequent hard forks, meaning it cannot accurately simulate or interact with the EVM behavior introduced in newer Ethereum versions.fixFor EVM simulations or interactions with post-Prague Ethereum networks, use an alternative, actively maintained EVM implementation. Py-EVM is limited to the protocol rules up to and including the Prague fork.
affects: >0.12.1b1 (implicitly, as no newer versions will be released)
breakingVersion 0.8.0-beta.1 removed external dependencies for Proof-of-Work (like `pyethash`, `pysha3`, and `pycryptodome`) and internalized a less performant `ethash` implementation. This change deprioritized PoW consensus logic within Py-EVM.fixIf high-performance Proof-of-Work computations or specific `pyethash`/`pysha3`/`pycryptodome` integrations were part of your workflow, this version (and later) will exhibit slower performance for PoW or require manual re-integration of those libraries/functionalities if needed.
affects: >=0.8.0-beta.1
breakingIn version 0.3.0-alpha.13, the consensus mechanism abstraction was significantly refactored. `validate_seal` and `validate_header` methods were changed from classmethods to instance methods, and new `ConsensusAPI` and `ConsensusContextAPI` were introduced.fixCode that directly interacted with or overrode the `validate_seal` or `validate_header` methods, or that implemented custom consensus logic before this version, will require updates to conform to the new `ConsensusAPI` and `ConsensusContextAPI` interfaces.
affects: >=0.3.0-alpha.13
gotchaPy-EVM is a low-level EVM implementation focused on the execution layer. It does not inherently handle the consensus layer (e.g., Proof of Stake networking, block propagation, or peer-to-peer communication) or direct interaction with live Ethereum networks. It is primarily for local simulation and testing of EVM logic.fixFor interacting with live Ethereum networks (Mainnet, testnets), sending transactions, or deploying contracts, a higher-level library like `web3.py` is typically used, which often leverages an EVM client (not `py-evm`) for execution.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'eth'
The `py-evm` library or one of its core dependencies (like `eth-typing`, `eth-keys`, `eth-utils`) is not correctly installed or accessible in the Python environment, often due to an outdated pip or an unactivated virtual environment.
fixpython3 -m pip install --upgrade pip && python3 -m venv venv && source venv/bin/activate && pip install py-evm
ValidationError: mix hash mismatch
This error occurs during block validation, typically when the computed mix hash (part of the Proof-of-Work seal) does not match the expected mix hash recorded in the block header, indicating an invalid block or incorrect mining parameters.
fixEnsure the block data is valid and consistent with the Ethereum protocol rules for the specific fork being processed. For custom mining scenarios, verify that the proof-of-work calculation (nonce and mix_hash) is correctly implemented and aligned with the chain's difficulty.
AttributeError: 'LegacyTransaction' object has no attribute 'max_fee_per_gas'
This error arises when attempting to access transaction attributes specific to newer Ethereum Improvement Proposals (EIPs), such as EIP-1559's `max_fee_per_gas` or `access_list`, on a transaction object that is of an older, incompatible type (e.g., a legacy transaction).
fixBefore accessing transaction attributes, check the transaction's type (e.g., using `transaction.type_id`) and conditionally access properties relevant to that specific transaction type. Alternatively, use common properties available across all transaction types.
eth_abi.exceptions.InsufficientDataBytes: Tried to read X bytes. Only got Y bytes
This issue typically occurs when interacting with smart contracts, indicating a mismatch between the expected ABI output and the actual data returned by a contract call or event, often due to an incorrect or outdated ABI being used, or insufficient gas causing a transaction to revert without the expected return data.
fixVerify that the Application Binary Interface (ABI) used to interact with the smart contract is accurate and up-to-date with the deployed contract's code. Also, ensure that contract calls or deployments are provided with sufficient gas to execute successfully and return the expected data.
Upgrade
Version history
0.12.1b1latest on PyPI · released May 14, 2025
Audit
Dependencies
eth-utilsrequiredProvides essential utilities for Ethereum development, such as unit conversions and hex encoding, commonly used when interacting with Py-EVM's APIs.