{"id":3222,"library":"py-evm","title":"py-evm (Python Ethereum Virtual Machine)","description":"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.**","status":"abandoned","version":"0.12.1b1","language":"python","source_language":"en","source_url":"https://github.com/ethereum/py-evm","tags":["ethereum","evm","blockchain","virtual machine","cryptocurrency","archived"],"install":[{"cmd":"pip install py-evm","lang":"bash","label":"Install Py-EVM"}],"dependencies":[{"reason":"Provides essential utilities for Ethereum development, such as unit conversions and hex encoding, commonly used when interacting with Py-EVM's APIs.","package":"eth-utils","optional":false}],"imports":[{"symbol":"MainnetChain","correct":"from eth.chains.mainnet import MainnetChain"},{"symbol":"AtomicDB","correct":"from eth.db.atomic import AtomicDB"},{"symbol":"GAS_LIMIT","correct":"from eth.constants import GAS_LIMIT"},{"symbol":"to_wei","correct":"from eth_utils import to_wei"},{"symbol":"encode_hex","correct":"from eth_utils import encode_hex"},{"symbol":"Address","correct":"from eth_typing import Address"}],"quickstart":{"code":"import os\n\nfrom eth import constants\nfrom eth.chains.mainnet import MainnetChain\nfrom eth.db.atomic import AtomicDB\nfrom eth_utils import to_wei, encode_hex\nfrom eth_typing import Address\n\ndef run_evm_example():\n    # Setup a mock address and initial balance\n    MOCK_ADDRESS = Address(b'\\x00' * 19 + b'\\x01')  # An arbitrary address\n    PREFUND_AMOUNT = to_wei(100, 'ether')\n\n    # Initialize a new chain with an atomic database\n    # AtomicDB is an in-memory database suitable for tests and examples\n    chain = MainnetChain.from_genesis(\n        AtomicDB(),\n        genesis_state={\n            MOCK_ADDRESS: {\n                'balance': PREFUND_AMOUNT,\n                'nonce': 0,\n                'code': b'',\n                'storage': {}\n            }\n        },\n        genesis_header_params={\n            'gas_limit': constants.GAS_LIMIT,\n            'difficulty': 1  # Simplified difficulty for non-PoW chain\n        }\n    )\n\n    # Get the current VM from the chain\n    vm = chain.get_vm()\n\n    print(f\"Chain created successfully. Current block number: {vm.get_block().header.block_number}\")\n    print(f\"Balance of {encode_hex(MOCK_ADDRESS)}: {vm.get_balance(MOCK_ADDRESS)} Wei\")\n\n    # Example: Accessing a constant\n    print(f\"Default transaction gas limit: {constants.GAS_LIMIT}\")\n\nif __name__ == \"__main__\":\n    run_evm_example()","lang":"python","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":"All versions from 0.12.1b1 onwards (as of May 2025)"},{"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.","message":"Py-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.","severity":"breaking","affected_versions":">0.12.1b1 (implicitly, as no newer versions will be released)"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=0.8.0-beta.1"},{"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.","message":"In 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.","severity":"breaking","affected_versions":">=0.3.0-alpha.13"},{"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.","message":"Py-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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'2025':49 'aim':34 'archiv':55,80 'blockchain':76 'cryptocurr':79 'design':21 'develop':65 'ethereum':5,17,42,70,74 'evm':3,10,20,52,75 'execut':43 'experiment':28 'flexibl':24 'fork':71 'implement':14,39 'last':68 'layer':44 'machin':7,19,78 'may':48 'perform':30 'plan':66 'pragu':73 'py':2,9,51 'py-evm':1,8,50 'python':4,13 'read':60 'read-on':59 'readabl':23 'refer':38 'research':26 'specif':45 'support':69 'test':32 'virtual':6,18,77","created_at":"2026-04-11T09:26:14.974433+00:00","updated_at":"2026-04-16T18:16:47.080189+00:00","problems":[{"fix":"python3 -m pip install --upgrade pip && python3 -m venv venv && source venv/bin/activate && pip install py-evm","cause":"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.","error":"ModuleNotFoundError: No module named 'eth'"},{"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.","cause":"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.","error":"ValidationError: mix hash mismatch"},{"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.","cause":"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).","error":"AttributeError: 'LegacyTransaction' object has no attribute 'max_fee_per_gas'"},{"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.","cause":"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.","error":"eth_abi.exceptions.InsufficientDataBytes: Tried to read X bytes. Only got Y bytes"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.12.1b1","cli_name":"","cli_version":null,"type":"library","homepage":"https://py-evm.readthedocs.io","github":"https://github.com/ethereum/py-evm","docs":null,"changelog":null,"pypi":"https://pypi.org/project/py-evm/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}