Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ethereum/go-ethereum/llms.txt

Use this file to discover all available pages before exploring further.

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

PlatformDefault 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:
PathDescription
m/44'/60'/0'/0Root path (legacy Ledger)
m/44'/60'/0'/0/0First account (standard base path)
m/44'/60'/0'/0/1Second 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us