Registry / database / py-evm

py-evm

JSON →
library0.12.1b1pypypi✓ verified 26d ago

Py-EVM is a Python implementation of the Ethereum Virtual Machine (EVM) designed for readability, flexibility for research and experimentation, and performance in testing. It aims to be a reference implementation for the Ethereum execution layer specifications. **As of May 2025, Py-EVM has been archived and is now read-only, with no further development planned. The last supported Ethereum fork is Prague.**

pip install py-evm
INSTALL
IMPORT
SIG · PY-EVM
P
py-evm
databasepythonv0.12.1b1
Install
5.3s avg
Import
4453ms
Disk
56MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 4.578s · 55.5MB
glibc
py 3.103.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.
fix
Consider 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.
fix
For 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.
fix
If 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.
fix
Code 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.
fix
For 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.
fix
python3 -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.
fix
Ensure 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).
fix
Before 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.
fix
Verify 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.
Agent activity
12 hits · last 30 days
node
10
Resources
py-evm — pip install py-evm · libregistry