Install & Compatibility
Where this runs
tested against v0.14.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 4.402s · 56.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.3s · import 4.214s · 59MB
57MB installed
● package 57MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Account
✓ from eth_account import Account
messages
✓ from eth_account.messages import encode_defunct, encode_structured_data,
encode_typed_data, SignableMessage
This quickstart demonstrates how to create a new Ethereum account (generating a private key locally) and then sign a plain text message using that account. It also shows how to recover the signer's address from the signed message to verify the signature. [1, 3]
from eth_account import Account
from eth_account.messages import encode_defunct
import os
# 1. Create a new account (generates a private key)
private_key_bytes = Account.create()._private_key
account = Account.from_key(private_key_bytes)
print(f"New Account Address: {account.address}")
# 2. Sign a message
msg_text = "Hello, Ethereum!"
message = encode_defunct(text=msg_text.encode('utf-8'))
signed_message = account.sign_message(message)
print(f"Signed Message Hash: {signed_message.messageHash.hex()}")
print(f"Signature: {signed_message.signature.hex()}")
# 3. Verify the signature
recovered_address = Account.recover_message(message, signature=signed_message.signature)
print(f"Recovered Address: {recovered_address}")
assert recovered_address == account.address
print("Signature verification successful!")
Debug
Known issues
breakingSupport for Python 3.8 and 3.9 was dropped in version 0.14.0-beta.1. Users on these Python versions should remain on `eth-account <0.14.0` or upgrade their Python interpreter. [19]fixUpgrade Python to 3.10+ or pin `eth-account` to `<0.14.0`.
affects: >=0.14.0-beta.1
breakingWhen integrating with `web3.py`, note that `web3.eth.accounts.create` in `web3.py` v1.x had an `entropy` parameter which was removed in v4.x. `eth-account` relies on `ethereum-cryptography/secp256k1` for private key generation directly. [14]fixDo not rely on the `entropy` parameter. Use `Account.create()` from `eth-account` directly for new key generation.
affects: web3.py >=4.x
gotchaThe method `Account.unsafe_sign_hash()` is primarily for backwards compatibility. For all new implementations, it is strongly recommended to use `encode_defunct()` or `encode_structured_data()` for message signing. [1]fixUse `eth_account.messages.encode_defunct()` for simple text messages or `eth_account.messages.encode_structured_data()` / `encode_typed_data()` for EIP-712 structured data.
affects: All versions
gotchaSecurely managing private keys and seed phrases is critical. Loss or compromise of these credentials will result in irreversible loss of funds. `eth-account` provides the tools, but responsibility for secure storage lies with the developer/user. [5, 21]fixImplement robust security practices for storing private keys (e.g., environment variables, secure key management systems) and never expose them in plaintext code or public repositories.
affects: All versions
gotchaIncorrect handling of transaction nonces (e.g., skipping nonces or sending transactions with too low a gas price) can lead to stuck or failed transactions on the Ethereum network. [22]fixEnsure proper nonce management, typically handled by `web3.py`'s transaction builders, but be aware of its importance in custom transaction logic.
affects: All versions (when interacting with a blockchain)
gotcha`eth-account` pins `eth-keyfile` to `<0.9.0` (and `>=0.7.0`) due to breaking changes to typing introduced in `eth-keyfile >=0.9.0`. This can lead to dependency conflicts if another library requires a newer `eth-keyfile` version. [19]fixWhen resolving dependency conflicts, prioritize `eth-account`'s specified range for `eth-keyfile`. If a newer `eth-keyfile` is strictly needed by another library, ensure it's compatible or consider isolated environments.
affects: >=0.13.4
gotchaWhen using `eth_account.messages.encode_defunct()`, ensure that if providing `text`, it is a string. If you already have bytes, pass them to the `primitive` parameter instead to avoid `AttributeError: 'bytes' object has no attribute 'encode'`.fixPass string messages to the `text` parameter, and byte messages to the `primitive` parameter of `encode_defunct()`.
affects: All versions
gotchaWhen using `eth_account.messages.encode_defunct()`, passing an already-encoded `bytes` object to the `text` parameter (e.g., `text=my_string.encode('utf-8')`) will result in an `AttributeError` because the function expects a string for `text`. If you already have bytes, pass them as the `primitive` argument directly.fixPass string messages directly to the `text` parameter of `eth_account.messages.encode_defunct()` (e.g., `text=my_string`). If you already have bytes, pass them as the first positional `primitive` argument (e.g., `encode_defunct(my_bytes)`).
affects: All versions
Errors
Common errors & fixes
AttributeError: 'Eth' object has no attribute 'account'
This error occurs when attempting to access eth-account functionalities via `w3.eth.account` as if it were a direct attribute of the `Eth` object in web3.py, or when web3.py is not properly initialized with a provider.
fixEnsure `web3.py` is initialized with a provider, and directly import `Account` from `eth_account` to use its methods. For example: `from eth_account import Account; acct = Account.create()`.
AttributeError: type object 'Account' has no attribute 'from_key'
The `from_key()` method on the `Account` object has been deprecated in newer versions of `eth-account`.
fixUse `Account.from_private_key()` instead to load an account from a private key. For example: `from eth_account import Account; private_key = '0x...'; acct = Account.from_private_key(private_key)`.
ModuleNotFoundError: No module named 'Crypto'
This error indicates that the `pycryptodome` library, which provides the `Crypto` module needed by `eth-account` (via `eth-keyfile`), is either not installed, or there's a conflict with an older `pycrypto` installation.
fixInstall `pycryptodome` using pip: `pip install pycryptodome`. If issues persist, ensure no conflicting `pycrypto` packages are installed and that `pycryptodome` is correctly cased (e.g., `from Crypto.Random import get_random_bytes`).
ValueError: Private key must be 32 bytes
This error arises when a private key provided to `eth-account` methods is not in the correct format or length. An Ethereum private key must be a 32-byte (64 hexadecimal characters) string or bytes object.
fixEnsure the private key is a 64-character hexadecimal string, optionally prefixed with '0x', or a 32-byte `bytes` object. Convert it to the expected type if necessary, e.g., `private_key = '0x...'` or `private_key_bytes = bytes.fromhex('...')`. AttributeError: 'bytes' object has no attribute 'encode'
This error typically occurs in Python 3 when `encode()` is called on an object that is already a `bytes` type, or when a method expects a `str` but receives `bytes`.
fixCheck the type of the variable. If it's already `bytes`, remove the `.encode()` call. If a `str` is expected and you have `bytes`, use `.decode('utf-8')` (or the appropriate encoding) to convert it to a string. Conversely, if `bytes` is expected and you have a `str`, use `.encode('utf-8')` to convert it. Upgrade
Version history
0.14.0latest on PyPI · released Aug 23, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.8 or newer, but not Python 4.
eth-utilsrequiredCore utility functions; latest versions required for compatibility.
eth-keyfilerequiredUsed for keystore management; specific version range required to avoid breaking changes to typing.