Install & Compatibility
Where this runs
tested against v6.0.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.95 runs
installs and imports cleanly · install 0.0s · import 0.616s · 39.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.8s · import 0.578s · 42MB
39MB installed
● package 39MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
to_checksum_address
✓ from eth_utils import to_checksum_address
to_bytes
✓ from eth_utils import to_bytes
is_address
✓ from eth_utils import is_address
hexstr_if_str
✓ from eth_utils.curried import hexstr_if_str
Functions from the `curried` submodule are partially applied versions.
abi_to_signature
✓ from eth_utils.abi import abi_to_signature
✗ from eth_utils import abi_to_signature
While many functions are directly importable from `eth_utils`, it's clearer and more explicit to import ABI-related functions from `eth_utils.abi`.
This quickstart demonstrates common utility functions like `to_checksum_address` for EIP-55 compliant addresses, `is_address` for validation, and `to_bytes` and `decode_hex` for handling various string and byte conversions, emphasizing the need for explicit type specification in conversions.
from eth_utils import to_checksum_address, is_address, to_bytes, decode_hex
# Example 1: Checksumming an Ethereum address
address_raw = '0xd3cda913deb6f67967b99d67acdfa1712c293601'
checksum_address = to_checksum_address(address_raw)
print(f"Raw address: {address_raw}")
print(f"Checksummed address: {checksum_address}")
# Example 2: Validating an address
is_valid = is_address(checksum_address)
print(f"Is '{checksum_address}' a valid address? {is_valid}")
# Example 3: Converting string to bytes, explicitly specifying type
hex_string = '0x123456'
bytes_data = to_bytes(hexstr=hex_string)
print(f"Hex string '{hex_string}' to bytes: {bytes_data}")
# Example 4: Decoding a hexadecimal string to bytes
decoded_bytes = decode_hex('0xabcdef')
print(f"Decoded '0xabcdef' to bytes: {decoded_bytes}")
Debug
Known issues
breakingThe `ethereum-utils` PyPI package was renamed to `eth-utils` in November 2017. Projects still depending on `ethereum-utils` will not receive updates and should migrate to `eth-utils`.fixUpdate `requirements.txt` or `pyproject.toml` to use `eth-utils` instead of `ethereum-utils`.
affects: <1.0.0 (of `ethereum-utils`)
breakingWith the release of `eth-utils` v6.0.0, support for Python 3.8 and 3.9 has been dropped. Ensure your project is running on Python 3.10 or newer.fixUpgrade your Python environment to version 3.10 or later.
affects: >=6.0.0
gotchaWhen using conversion utilities like `to_bytes` or `to_hex` with string inputs, you must explicitly specify whether the string is `text` (e.g., UTF-8 encoded) or a `hexstr` (hex-encoded bytestring). The library cannot reliably auto-detect this, leading to incorrect conversions if not specified.fixAlways use keyword arguments `text='your_string'` or `hexstr='0x...'`. For example, `to_bytes(text='hello')` or `to_bytes(hexstr='0x1234')`.
affects: All versions
gotchaThe `apply_formatter_to_array` function in `eth-utils` returns a generator, which must be consumed (e.g., by converting to a `list`) to access all formatted elements. This differs from some other libraries (e.g., `web3.py`'s historical `apply_formatter_to_array`) which might return a concrete list or array directly.fixAlways explicitly convert the result to a list or iterate over the generator if you need to access all elements: `list(apply_formatter_to_array(formatter, value))`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'eth_utils'
The `eth-utils` library is not installed in your Python environment or the Python interpreter cannot find it.
fixInstall the library using pip: `pip install eth-utils`
DeprecationWarning: This library has been renamed to `eth-utils`. The `ethereum-utils` package will no longer recieve updates.
You are trying to import from an old, deprecated package named `ethereum-utils` which has been renamed to `eth-utils`.
fixUninstall the old package and install the new one: `pip uninstall ethereum-utils` then `pip install eth-utils`. Update your imports from `from ethereum_utils import ...` to `from eth_utils import ...`.
ValueError: Invalid address: <address_string>
A provided Ethereum address string is not in a valid format (e.g., incorrect length, non-hex characters, invalid checksum for mixed-case addresses).
fixEnsure the address is a valid 20-byte hexadecimal string, optionally prefixed with '0x', and if mixed-case, that it passes EIP-55 checksum validation. Use `eth_utils.is_address()` to validate addresses or `eth_utils.to_checksum_address()` to convert them.
ValueError: Given value is not an acceptable HexBytes representation.
A function that expects a hexadecimal string (often a byte string prefixed with '0x') received an input that could not be parsed as a valid hexadecimal representation.
fixEnsure the input string is a valid hexadecimal string, usually an even number of hex characters, and often prefixed with '0x'. For example, use `eth_utils.encode_hex()` to convert bytes to hex or `eth_utils.decode_hex()` to convert hex to bytes, ensuring the input matches the expected format.
Upgrade
Version history
6.0.0latest on PyPI · released Mar 25, 2026
Audit
Dependencies
No dependency data recorded yet.