Install & Compatibility
Where this runs
tested against v? · pip install
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.910 runs
build_error
glibcpy 3.10–3.910 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HDWallet
✓ from hdwallet import HDWallet
generate_mnemonic
✓ from hdwallet.utils import generate_mnemonic
✗ from hdwallet import generate_mnemonic
Mnemonic utility functions are located in `hdwallet.utils`.
BIP44Derivation
✓ from hdwallet.derivations import BIP44Derivation
✗ from hdwallet import BIP44Derivation
Derivation path constants are typically imported from `hdwallet.derivations`.
This quickstart demonstrates how to generate a new 12-word BIP-39 mnemonic, derive an Ethereum address using a standard BIP-44 path, and retrieve its associated private and public keys. It highlights the use of `generate_mnemonic`, `is_mnemonic_valid`, `HDWallet`, `from_mnemonic`, and `from_path`.
from hdwallet import HDWallet
from hdwallet.symbols import ETH as SYMBOL
from hdwallet.derivations import BIP44Derivation
from hdwallet.utils import generate_mnemonic, is_mnemonic_valid
# 1. Generate a new mnemonic phrase (12 words)
mnemonic = generate_mnemonic(language="english", strength=128)
# 2. Optionally, validate the mnemonic
if not is_mnemonic_valid(mnemonic, language="english"):
raise ValueError("Invalid mnemonic phrase")
# 3. Create an HDWallet instance
hdwallet = HDWallet(symbol=SYMBOL)
# 4. From mnemonic, get the root key
hdwallet.from_mnemonic(mnemonic=mnemonic, language="english", passphrase=None)
# 5. Derive a child key using a BIP44 path for Ethereum
# Example: m/44'/60'/0'/0/0
hdwallet.from_path(path=BIP44Derivation.m / BIP44Derivation.coin_types.ETH / BIP44Derivation.PURPOSE.root / BIP44Derivation.ACCOUNT.root / BIP44Derivation.CHANGE.root / BIP44Derivation.ADDRESS.root)
# 6. Get wallet details
print(f"Mnemonic: {hdwallet.mnemonic()}")
print(f"Base HD path: {hdwallet.base_hd_path()}")
print(f"Address: {hdwallet.address()}")
print(f"Private Key: {hdwallet.private_key()}")
print(f"Public Key: {hdwallet.public_key()}")
hdwallet --version
Errors
Common errors & fixes
AttributeError: 'HDWallet' object has no attribute 'ecc'
Attempting to access the `ecc` attribute directly after the v3.5.1 refactor.
fixThe attribute was renamed to `eccs`. Update your code to use `hdwallet_instance.eccs` if you need to access it, though direct access to internal attributes is generally discouraged.
ImportError: cannot import name 'generate_mnemonic' from 'hdwallet'
Trying to import utility functions directly from the top-level `hdwallet` package.
fixUtility functions like `generate_mnemonic` are located in `hdwallet.utils`. Correct the import to `from hdwallet.utils import generate_mnemonic`.
ValueError: Invalid WIF private key: checksum mismatch
Attempting to import or use a WIF (Wallet Import Format) private key that was either generated incorrectly by an older version of `hdwallet` or is simply malformed according to the updated WIF standards in v3.1.0/v3.2.0.
fixEnsure the WIF string is correctly formatted according to current standards. If it was generated by an older `hdwallet` version, verify if the new library can still process it, or re-generate/re-export from a reliable source.
Upgrade
Version history
3.6.1latest on PyPI · released Aug 4, 2025
Audit
Dependencies
mnemonicrequiredUsed for BIP-39 mnemonic phrase generation and validation.
base58requiredProvides Base58 encoding/decoding for addresses and keys.
ecdsarequiredRequired for elliptic curve digital signature algorithm operations, crucial for Bitcoin-like cryptocurrencies.
ed25519-hd-keyrequiredSupports HD key derivation for Ed25519 curve-based cryptocurrencies.
bech32mrequiredImplements Bech32m encoding for segwit addresses.
py-hashesrequiredProvides various cryptographic hash functions.
pydanticrequiredUsed for data validation and settings management.