Keystore and accounts

Manage encrypted key files on disk and interact with Ethereum accounts via the geth CLI.

The keystore is Geth’s built-in mechanism for storing Ethereum private keys on disk as encrypted JSON files. Each account corresponds to a single key file whose private key is protected by a password using the Web3 Secret Storage specification (scrypt KDF by default).

Key file format

Key files are named using the convention:

UTC--<created_at UTC ISO8601>--<address hex>

For example:

UTC--2024-01-15T10-30-00.000000000Z--d9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3

Each file contains a JSON object conforming to the Web3 Secret Storage specification. The private key is AES-128-CTR encrypted and the encryption key is derived from the password using scrypt.

{
  "address": "d9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3",
  "crypto": {
    "cipher": "aes-128-ctr",
    "cipherparams": { "iv": "..." },
    "ciphertext": "...",
    "kdf": "scrypt",
    "kdfparams": {
      "dklen": 32,
      "n": 262144,
      "p": 1,
      "r": 8,
      "salt": "..."
    },
    "mac": "..."
  },
  "id": "...",
  "version": 3
}

Default keystore location

Platform	Default path
Linux	~/.ethereum/keystore
macOS	~/Library/Ethereum/keystore
Windows	%APPDATA%\Ethereum\keystore

You can override the location with --keystore <path> or --datadir <path> when starting geth.

Key files are portable. You can safely copy the entire keystore directory or individual key files between Ethereum nodes without any conversion.

Managing accounts with the geth CLI

1. Create a new account

   geth account new
   

   Geth prompts for a password, generates a new secp256k1 key pair, and writes the encrypted key file to the keystore directory. The public address is printed on success.

   For scripted use, supply the password from a file:

   geth account new --password /path/to/password.txt
   

   The --password flag is intended for testing only. Storing a password in a plain text file on disk is a security risk in production environments.

2. List existing accounts

   geth account list
   

   Prints a summary of every account found in the keystore:

   Account #0: {d9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3} keystore:///home/user/.ethereum/keystore/UTC--2024-01-15...
   Account #1: {086278a6c067775f71d6b2bb1856db6e28c30418} keystore:///home/user/.ethereum/keystore/UTC--2024-02-06...
   
3. Import a raw private key

   To import an unencrypted private key stored in a hex file:

   geth account import <keyfile>
   

   The key file must contain the unencrypted private key in hexadecimal format. Geth encrypts it with a new password and saves it to the keystore.

   geth account import ./my-raw-key.hex
   

   Never share or expose the raw key file. Delete it securely after importing.

4. Update an account (change password or migrate format)

   geth account update <address>
   

   Re-encrypts the key file with a new password and upgrades it to the current key file format. Use this to change the account password interactively.

Backing up and restoring accounts

Key files are self-contained. To back up an account, copy its key file from the keystore directory. To restore, place the file back in the keystore directory of any Geth instance.

Always back up your key files and remember the associated passwords. Without both the key file and the password, access to the account funds is permanently lost.

The —unlock flag (deprecated)

Older versions of Geth supported an --unlock flag that decrypted and held private keys in memory for the duration of a running node. This flag is deprecated and has no effect in current versions of Geth. Do not rely on it, and do not build tooling that expects accounts to be unlocked via the node process.

For programmatic signing, use Clef instead.

HD wallet derivation

Geth supports BIP-44 hierarchical deterministic (HD) wallets for hardware wallet integration. The standard Ethereum derivation path is:

Path	Description
m/44'/60'/0'/0	Root path (legacy Ledger)
m/44'/60'/0'/0/0	First account (standard base path)
m/44'/60'/0'/0/1	Second account, etc.

The coin type 60' is the SLIP-44 identifier assigned to Ethereum.

Hardware wallet support

Geth includes native USB drivers for:

• Ledger hardware wallets
• Trezor hardware wallets (HID and WebUSB)

When a hardware wallet is plugged in, Geth detects it automatically and exposes its accounts through the same accounts.Wallet interface as keystore accounts. No additional configuration is required.

For production key management, consider using Clef together with a hardware wallet. Clef runs as an isolated signing process and never exposes private keys to the Geth process itself.