Install & Compatibility
Where this runs
tested against v7.16.0 · 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.910 runs
installs and imports cleanly · install 0.0s · import 5.697s · 84.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 10.8s · import 5.320s · 89MB
88MB installed
● package 88MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Web3
✓ from web3 import Web3
AsyncWeb3
✓ from web3 import AsyncWeb3
HTTPProvider
✓ from web3 import HTTPProvider
IPCProvider
✓ from web3 import IPCProvider
WebSocketProvider
✓ from web3 import WebSocketProvider
✗ from web3 import WebsocketProviderV2 (v6)
WebsocketProviderV2 was renamed to WebSocketProvider in v7. The old WebsocketProvider (v5) was renamed to LegacyWebSocketProvider and deprecated in v7.
This quickstart demonstrates how to connect to an Ethereum node using `HTTPProvider` and retrieve the latest block number. For asynchronous operations, use `AsyncWeb3` and an asynchronous provider like `AsyncHTTPProvider` or `WebSocketProvider`.
import os
from web3 import Web3, HTTPProvider
# Replace with your actual RPC URL, e.g., from Infura, Alchemy, or a local node.
# It's best practice to use environment variables for sensitive info.
INFURA_URL = os.environ.get('WEB3_PROVIDER_URL', 'http://127.0.0.1:8545')
# Initialize Web3 with an HTTPProvider
try:
w3 = Web3(HTTPProvider(INFURA_URL))
if w3.is_connected():
print(f"Successfully connected to Ethereum node at {INFURA_URL}")
# Get the latest block number
latest_block = w3.eth.block_number
print(f"Latest block number: {latest_block}")
else:
print(f"Failed to connect to Ethereum node at {INFURA_URL}")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingStrict bytes checking is enabled by default in v6. This means ABI arguments expecting a specific bytes length (e.g., bytes4) will only accept 0x-prefixed hex strings or bytes types of that exact length. Ambiguous values will be invalidated.fixEnsure all byte-like inputs match the ABI's specified length exactly, or explicitly disable strict bytes checking via `w3.strict_bytes_type_checking = False` if necessary.
affects: >=6.0.0
breakingMost API methods and properties were converted from `camelCase` to `snake_case` in v6 to align with Pythonic conventions. Exceptions include contract methods/events (which follow ABI) and JSON-RPC parameters/returns (which follow RPC spec).fixUpdate method and property calls to use `snake_case`. For example, `w3.eth.getBlock('latest')` becomes `w3.eth.get_block('latest')`. affects: >=6.0.0
breakingIn v6, the `Web3` class was split into `Web3` (for synchronous operations) and `AsyncWeb3` (for asynchronous operations). Providers must match the instance type (e.g., `AsyncWeb3` requires `AsyncHTTPProvider` or `WebSocketProvider`).fixInstantiate `Web3` for synchronous code and `AsyncWeb3` for asynchronous code. Ensure providers are compatible with the chosen `Web3` instance.
affects: >=6.0.0
breakingThe middleware model changed to a class-based system in v7, replacing the older functional middleware. Middleware logic is now separated into `request_processor` and `response_processor` functions.fixRewrite custom middleware to conform to the new class-based structure, separating request and response processing. Consult the official migration guide for examples.
affects: >=7.0.0
breakingThe `EthPM` module, deprecated in v6 due to lack of use and functionality issues, was completely removed in v7.fixRemove all reliance on the `web3.ethpm` module. If EthPM-like functionality is still needed, explore alternative solutions or re-implement necessary parts.
affects: >=7.0.0
gotchaPython 3.7 support was dropped in v7. The library now requires Python 3.8 or newer.fixUpgrade your Python environment to version 3.8 or later.
affects: >=7.0.0
deprecatedThe `geth.miner` namespace and its methods were deprecated in v6 and completely removed in v7, reflecting Geth's transition away from mining (Proof-of-Work) to Proof-of-Stake.fixRemove any calls to `w3.geth.miner` methods. These functionalities are no longer relevant in modern Ethereum.
affects: >=6.0.0 (deprecated), >=7.0.0 (removed)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'web3'
The 'web3' library is not installed in your current Python environment.
web3.exceptions.TimeExhausted: Provider is not responding to ping
The web3.py library failed to receive a response from the configured Ethereum RPC provider within the timeout period.
fixVerify the RPC URL, check network connectivity, ensure the Ethereum node is running and accessible, and potentially increase the timeout setting.
web3.exceptions.InvalidAddress: checksum address is invalid
The provided Ethereum address string is not a valid checksummed address, or is otherwise malformed.
fixEnsure the address is a valid 42-character hexadecimal string, starts with '0x', and use `Web3.to_checksum_address()` for verification.
ValueError: {'code': -32000, 'message': 'execution reverted'}
A smart contract transaction or call reverted due to a `require()` or `revert()` statement within the contract's logic, often because of invalid input or unmet conditions.
fixReview the smart contract's code for the failing transaction, check input parameters, ensure sufficient gas and value are provided, and simulate the transaction for detailed error messages.
AttributeError: 'ContractFunctions' object has no attribute 'myFunctionName'
The specified contract function name does not exist in the contract's ABI, or there is a typo in the function name when trying to call it.
fixVerify the exact spelling and case of the function name against the smart contract's ABI (e.g., `contract.functions.my_function_name()`).
Upgrade
Version history
7.16.0latest on PyPI · released May 1, 2026
Audit
Dependencies
eth-testeroptionalRequired for the EthereumTesterProvider, useful for local testing without a live node.