mnemonic

library0.21pypypi✓ verified 22d ago

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.

auth-security serialization

pip install mnemonic

package ↗

INSTALL

IMPORT

SIG · MNEMONIC

mnemonic

auth-securitypythonv0.21

Install

1.5s avg

Import

19ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.21 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.022s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.016s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Mnemonic

✓ from mnemonic import Mnemonic

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.

from mnemonic import Mnemonic import os # Initialize Mnemonic with a language # 'english' is a common choice and default since v0.21 mnemo = Mnemonic("english") # Generate a 24-word mnemonic phrase (256 bits of strength) # Strength can be 128, 160, 192, 224, or 256 bits, dictating phrase length. words = mnemo.generate(strength=256) print(f"Generated mnemonic: {words}") # Validate a mnemonic phrase is_valid = Mnemonic.check(words) print(f"Is mnemonic valid? {is_valid}") # Convert the mnemonic to a seed (with an optional passphrase) # For real applications, use a strong, unique passphrase. passphrase = os.environ.get('MNEMONIC_PASSPHRASE', '') seed = mnemo.to_seed(words, passphrase=passphrase) print(f"Generated seed (hex): {seed.hex()}") # Alternatively, generate a mnemonic from cryptographic entropy entropy_bytes = os.urandom(32) # 32 bytes = 256 bits of entropy words_from_entropy = mnemo.to_mnemonic(entropy_bytes) print(f"Generated from raw entropy: {words_from_entropy}")

Debug

Known issues

breakingSupport 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).

fix

Upgrade to Python 3.8.1+ and `mnemonic` 0.20+.

affects: <0.20

breakingAs 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.

fix

Always explicitly specify the language (e.g., `Mnemonic("english")`) to ensure consistent behavior across versions.

affects: >=0.21

gotchaWhen 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.

fix

Implement robust passphrase management, advising users to provide strong, unique passphrases, or understand the security implications of an empty passphrase.

affects: All

gotchaThe `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.

fix

Always specify `strength` with a cryptographically sufficient value like 256 (for 24 words) when generating new mnemonics.

affects: All

gotchaVersion 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.

fix

For custom wordlists, use the new functionality in v0.21+. For standard wordlists, rely on the `Mnemonic(language)` constructor.

affects: <0.21

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'mnemonic'

The 'mnemonic' library has not been installed in your Python environment or the current environment is not correctly configured to find it.

fix

Run `pip install mnemonic` in your terminal to install the library.

ValueError: 'Invalid mnemonic'

The provided mnemonic phrase does not conform to the BIP-39 standard due to incorrect words (not in the wordlist), an incorrect number of words (must be 12, 15, 18, 21, or 24), wrong word order, or a failed checksum verification.

fix

Carefully check the mnemonic phrase for any typos, ensure all words are lowercase, verify the exact word count, and confirm that all words belong to the BIP-39 English wordlist (or the specified language wordlist).

ValueError: Data length should be one of the following: [16, 20, 24, 28, 32], but it is not X.

When generating a mnemonic from entropy, the input entropy byte string's length must correspond to a valid BIP-39 entropy strength (128, 160, 192, 224, or 256 bits), which translates to byte lengths of 16, 20, 24, 28, or 32 bytes respectively.

fix

Ensure the byte string passed as entropy has one of the supported lengths: 16, 20, 24, 28, or 32 bytes.

Upgrade

Version history

0.21latest on PyPI · released Jan 5, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

packagehttps://pypi.org/project/mnemonic/ ↗