{"id":5325,"library":"mnemonic","title":"Mnemonic","description":"The `mnemonic` library is a Python implementation of Bitcoin Improvement Proposal (BIP-0039). It provides functionality to generate mnemonic phrases (seed phrases), convert them into binary seeds for deterministic wallets, and validate existing mnemonic phrases. The current version is 0.21, released in January 2024, and it requires Python 3.8.1 or newer. The library primarily follows a stable release cadence as needed for updates to BIP-0039 or Python compatibility.","status":"active","version":"0.21","language":"en","source_language":"en","source_url":"https://github.com/trezor/python-mnemonic","tags":["cryptography","bitcoin","bip39","wallet","mnemonic","security"],"install":[{"cmd":"pip install mnemonic","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"Mnemonic","correct":"from mnemonic import Mnemonic"}],"quickstart":{"code":"from mnemonic import Mnemonic\nimport os\n\n# Initialize Mnemonic with a language\n# 'english' is a common choice and default since v0.21\nmnemo = Mnemonic(\"english\")\n\n# Generate a 24-word mnemonic phrase (256 bits of strength)\n# Strength can be 128, 160, 192, 224, or 256 bits, dictating phrase length.\nwords = mnemo.generate(strength=256)\nprint(f\"Generated mnemonic: {words}\")\n\n# Validate a mnemonic phrase\nis_valid = Mnemonic.check(words)\nprint(f\"Is mnemonic valid? {is_valid}\")\n\n# Convert the mnemonic to a seed (with an optional passphrase)\n# For real applications, use a strong, unique passphrase.\npassphrase = os.environ.get('MNEMONIC_PASSPHRASE', '') \nseed = mnemo.to_seed(words, passphrase=passphrase)\nprint(f\"Generated seed (hex): {seed.hex()}\")\n\n# Alternatively, generate a mnemonic from cryptographic entropy\nentropy_bytes = os.urandom(32) # 32 bytes = 256 bits of entropy\nwords_from_entropy = mnemo.to_mnemonic(entropy_bytes)\nprint(f\"Generated from raw entropy: {words_from_entropy}\")","lang":"python","description":"This quickstart demonstrates how to initialize the `Mnemonic` class, generate a cryptographically secure mnemonic phrase, validate it, and convert it into a deterministic seed, which is crucial for hierarchical deterministic (HD) wallets."},"warnings":[{"fix":"Upgrade to Python 3.8.1+ and `mnemonic` 0.20+.","message":"Support for Python 2.7 and 3.4 was dropped in version 0.20. Users on older Python versions must either upgrade their Python environment or use an older version of the `mnemonic` library (e.g., 0.19).","severity":"breaking","affected_versions":"<0.20"},{"fix":"Always explicitly specify the language (e.g., `Mnemonic(\"english\")`) to ensure consistent behavior across versions.","message":"As of version 0.21, 'english' is now the default language if no language is explicitly provided during `Mnemonic` initialization. Prior versions might have behaved differently or raised an error, potentially breaking applications that relied on implicit default language behavior.","severity":"breaking","affected_versions":">=0.21"},{"fix":"Implement robust passphrase management, advising users to provide strong, unique passphrases, or understand the security implications of an empty passphrase.","message":"When using `mnemo.to_seed(words, passphrase='')`, an empty passphrase is often used in examples. For real-world cryptographic applications, it is crucial to use a strong and unique passphrase to enhance the security of the generated seed. An empty passphrase significantly reduces the security against brute-force attacks on the seed.","severity":"gotcha","affected_versions":"All"},{"fix":"Always specify `strength` with a cryptographically sufficient value like 256 (for 24 words) when generating new mnemonics.","message":"The `generate()` method requires a `strength` parameter (in bits). It is advised to use 128, 256, 512, or 1024 bits for cryptographically secure mnemonics, as these correspond to standard word counts (12, 24 words for 128, 256 bits respectively). Using insufficient strength will result in a less secure mnemonic.","severity":"gotcha","affected_versions":"All"},{"fix":"For custom wordlists, use the new functionality in v0.21+. For standard wordlists, rely on the `Mnemonic(language)` constructor.","message":"Version 0.21 introduced the option to provide custom wordlists. Prior to this, the library relied solely on built-in wordlist files. Directly accessing or manipulating internal wordlist files from older versions could be fragile and break if the library's internal structure changes.","severity":"gotcha","affected_versions":"<0.21"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}