Install & Compatibility
Where this runs
tested against v0.10.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.764s · 49.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.5s · import 4.500s · 51MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
load_keyfile
✓ from eth_keyfile import load_keyfile
✗ from ethereum_keyfile import load_keyfile
The package was renamed from `ethereum-keyfile` to `eth-keyfile` in 2017. Old package is deprecated.
create_keyfile_json
✓ from eth_keyfile import create_keyfile_json
decode_keyfile_json
✓ from eth_keyfile import decode_keyfile_json
extract_key_from_keyfile
✓ from eth_keyfile import extract_key_from_keyfile
This quickstart demonstrates how to generate a new Ethereum private key, create an encrypted keyfile JSON object using that key and a password, and then decrypt the private key back from the keyfile. It also shows an example of creating a Keyfile V4, highlighting the `version` parameter. The private key and password are handled as bytestrings.
import os
import json
from eth_keyfile import create_keyfile_json, decode_keyfile_json
# 1. Generate a new private key (32 bytes)
private_key = os.urandom(32)
password = b"my_secure_password"
# 2. Create a keyfile JSON object (default is V3)
keyfile_json = create_keyfile_json(private_key, password)
# You would typically save this to a file:
# with open('my_keystore.json', 'w') as f:
# json.dump(keyfile_json, f)
print(f"Generated Keyfile (first 50 chars): {json.dumps(keyfile_json)[:50]}...")
# 3. Decode the private key from the keyfile JSON
decoded_private_key = decode_keyfile_json(keyfile_json, password)
assert private_key == decoded_private_key
print(f"Successfully decoded private key: {decoded_private_key.hex()}")
# Example with Keyfile V4 (requires different private key range)
# Note: private_key for v4 must be less than MAX_V4_PRIVATE_KEY
# For simplicity, using a valid v3 key here, but in a real scenario,
# ensure it's valid for bls12-381 curve if using v4.
try:
keyfile_json_v4 = create_keyfile_json(
private_key,
password,
version=4,
description="My V4 Key",
path="m/123/456"
)
print(f"\nGenerated V4 Keyfile (first 50 chars): {json.dumps(keyfile_json_v4)[:50]}...")
decoded_private_key_v4 = decode_keyfile_json(keyfile_json_v4, password)
assert private_key == decoded_private_key_v4
print(f"Successfully decoded V4 private key: {decoded_private_key_v4.hex()}")
except Exception as e:
print(f"\nCould not create V4 keyfile with this private key (expected for some randomly generated keys): {e}")
Debug
Known issues
breakingThe library was renamed from `ethereum-keyfile` to `eth-keyfile` in November 2017. The old package `ethereum-keyfile` is no longer maintained and will not receive updates.fixUpdate your `pip install` command and all import statements from `ethereum_keyfile` to `eth_keyfile`.
affects: <0.4.0 (for old package)
gotchaThe `private_key` parameter for `create_keyfile_json` and related functions expects a 32-byte `bytes` object, not a `0x`-prefixed hexadecimal string. Common conversion is needed if your private key is in hex format.fixConvert hex strings to bytes using `bytes.fromhex('your_hex_string')` after removing any '0x' prefix. Ensure the resulting bytes object is exactly 32 bytes long. affects: All versions
gotchaKeyfile Version 4 (`version=4`) uses BLS12-381 cryptography and has a more restricted valid range for private keys compared to Version 3 (which uses secp256k1). Randomly generated private keys might not fall within the valid range for V4, leading to errors.fixWhen creating V4 keyfiles, either ensure the private key is explicitly generated to be valid for BLS12-381, or be prepared to handle `EthKeyfileValueError` if a randomly generated key is out of range.
affects: All versions supporting V4 (0.8.0+)
gotchaPasswords for `create_keyfile_json` and `decode_keyfile_json` should generally be provided as `bytes` objects. Passing plain `str` might lead to unexpected encoding issues or `TypeError` in some environments or Python versions.fixAlways encode your password string to bytes, e.g., `password.encode('utf-8')` before passing it to `eth-keyfile` functions. affects: All versions
gotchaThe security of your Ethereum assets heavily depends on both the strength of the password chosen for the keyfile and the secure storage of the keyfile itself. Losing the password or exposing the keyfile (even encrypted) to unauthorized access can lead to loss of funds.fixUse strong, unique passwords. Back up keyfiles to multiple secure, offline locations. Never store passwords in plaintext alongside keyfiles. Consider hardware security modules (HSMs) for high-value keys.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'eth_keyfile'
The `eth-keyfile` library is not installed in your Python environment or the environment where your script is being run.
fixRun `pip install eth-keyfile` in your terminal to install the library.
ModuleNotFoundError: No module named 'Crypto' (or ImportError: cannot import name 'scrypt')
This error typically occurs because `eth-keyfile` depends on `pycryptodome`, and it expects the top-level package to be importable as `Crypto` (with a capital 'C'), which can sometimes be misconfigured or conflict with an older `pycrypto` installation.
fixEnsure `pycryptodome` is installed (`pip install pycryptodome`). If the error persists, check your `site-packages` directory for `pycryptodome` and verify that the main cryptographic module folder is named `Crypto` (with a capital 'C'), renaming it from `crypto` (lowercase) if necessary.
Incorrect Password (during decryption) / Could not decrypt key with given passphrase
The password provided to `eth-keyfile.decode_keyfile_json()` or `eth_keyfile.extract_key_from_keyfile()` is incorrect or does not match the password used to encrypt the keyfile.
fixVerify that you are supplying the exact correct password as a bytestring (e.g., `b'your_password'`) to the decryption function. Remember that keyfile passwords are case-sensitive.
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
The keyfile you are trying to load is not a valid JSON document; it might be corrupted, incomplete, or contain non-JSON data.
fixInspect the keyfile to ensure it's a well-formed JSON string. You can use an online JSON validator or try opening it in a text editor to check for any unexpected characters, truncation, or structural issues. The file should start with `{` and end with `}`. Upgrade
Version history
0.10.0latest on PyPI · released Aug 21, 2026
Audit
Dependencies
eth-utilsrequiredUtility functions for Ethereum development, including hex encoding/decoding and type checking.
eth-keysrequiredCryptographic primitives for Ethereum keys.
pycryptodomerequiredProvides the underlying cryptographic algorithms (AES, Scrypt, PBKDF2) for key derivation and encryption.
py_eccrequiredElliptic curve cryptography for BLS12-381 used in Keyfile V4.