{"id":2021,"library":"eth-keyfile","title":"Ethereum Keyfile Handler","description":"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.","status":"active","version":"0.9.1","language":"en","source_language":"en","source_url":"https://github.com/ethereum/eth-keyfile","tags":["ethereum","keyfile","cryptography","private-key","wallet","web3"],"install":[{"cmd":"pip install eth-keyfile","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Utility functions for Ethereum development, including hex encoding/decoding and type checking.","package":"eth-utils","optional":false},{"reason":"Cryptographic primitives for Ethereum keys.","package":"eth-keys","optional":false},{"reason":"Provides the underlying cryptographic algorithms (AES, Scrypt, PBKDF2) for key derivation and encryption.","package":"pycryptodome","optional":false},{"reason":"Elliptic curve cryptography for BLS12-381 used in Keyfile V4.","package":"py_ecc","optional":false}],"imports":[{"note":"The package was renamed from `ethereum-keyfile` to `eth-keyfile` in 2017. Old package is deprecated.","wrong":"from ethereum_keyfile import load_keyfile","symbol":"load_keyfile","correct":"from eth_keyfile import load_keyfile"},{"symbol":"create_keyfile_json","correct":"from eth_keyfile import create_keyfile_json"},{"symbol":"decode_keyfile_json","correct":"from eth_keyfile import decode_keyfile_json"},{"symbol":"extract_key_from_keyfile","correct":"from eth_keyfile import extract_key_from_keyfile"}],"quickstart":{"code":"import os\nimport json\nfrom eth_keyfile import create_keyfile_json, decode_keyfile_json\n\n# 1. Generate a new private key (32 bytes)\nprivate_key = os.urandom(32)\npassword = b\"my_secure_password\"\n\n# 2. Create a keyfile JSON object (default is V3)\nkeyfile_json = create_keyfile_json(private_key, password)\n\n# You would typically save this to a file:\n# with open('my_keystore.json', 'w') as f:\n#    json.dump(keyfile_json, f)\n\nprint(f\"Generated Keyfile (first 50 chars): {json.dumps(keyfile_json)[:50]}...\")\n\n# 3. Decode the private key from the keyfile JSON\ndecoded_private_key = decode_keyfile_json(keyfile_json, password)\n\nassert private_key == decoded_private_key\nprint(f\"Successfully decoded private key: {decoded_private_key.hex()}\")\n\n# Example with Keyfile V4 (requires different private key range)\n# Note: private_key for v4 must be less than MAX_V4_PRIVATE_KEY\n# For simplicity, using a valid v3 key here, but in a real scenario, \n# ensure it's valid for bls12-381 curve if using v4.\ntry:\n    keyfile_json_v4 = create_keyfile_json(\n        private_key, \n        password, \n        version=4, \n        description=\"My V4 Key\", \n        path=\"m/123/456\"\n    )\n    print(f\"\\nGenerated V4 Keyfile (first 50 chars): {json.dumps(keyfile_json_v4)[:50]}...\")\n    decoded_private_key_v4 = decode_keyfile_json(keyfile_json_v4, password)\n    assert private_key == decoded_private_key_v4\n    print(f\"Successfully decoded V4 private key: {decoded_private_key_v4.hex()}\")\nexcept Exception as e:\n    print(f\"\\nCould not create V4 keyfile with this private key (expected for some randomly generated keys): {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Update your `pip install` command and all import statements from `ethereum_keyfile` to `eth_keyfile`.","message":"The 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.","severity":"breaking","affected_versions":"<0.4.0 (for old package)"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Keyfile 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.","severity":"gotcha","affected_versions":"All versions supporting V4 (0.8.0+)"},{"fix":"Always encode your password string to bytes, e.g., `password.encode('utf-8')` before passing it to `eth-keyfile` functions.","message":"Passwords 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}