Registry / auth-security / eth-keyfile

eth-keyfile

JSON →
library0.10.0pypypi✓ verified 26d ago

eth-keyfile is a Python library for securely handling the encrypted keyfiles used to store Ethereum private keys. It provides functionality to create, load, and decrypt these keyfiles, which conform to the Web3 secret storage standards. The library is currently at version 0.9.1 and maintains a stable release cadence, with ongoing support for modern Python versions (>=3.8, <4). It was previously known as `ethereum-keyfile` and was renamed and moved to the Ethereum foundation GitHub in November 2017.

pip install eth-keyfile
INSTALL
IMPORT
SIG · ETH-KEYFILE
E
eth-keyfile
auth-securitypythonv0.10.0
Install
4.5s avg
Import
4632ms
Disk
50MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 4.764s · 49.3MB
glibc
py 3.103.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.
fix
Update 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.
fix
Convert 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.
fix
When 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.
fix
Always 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.
fix
Use 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.
fix
Run `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.
fix
Ensure `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.
fix
Verify 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.
fix
Inspect 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.
Agent activity
19 hits · last 30 days
node
14
OpenAI (training)
1
Resources
eth-keyfile — pip install eth-keyfile · libregistry