Install & Compatibility
Where this runs
tested against v0.3.0 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
bip39_generate
✓ from bip39 import bip39_generate
✗ from py_bip39_bindings import bip39_generate
The installed package 'py-bip39-bindings' exposes its functionality under the 'bip39' module name.
bip39_validate
✓ from bip39 import bip39_validate
The top-level module is named 'bip39'.
bip39_to_mini_secret
✓ from bip39 import bip39_to_mini_secret
The top-level module is named 'bip39'.
This quickstart demonstrates how to generate BIP39 mnemonic phrases with varying word counts and languages, validate them, and convert them into a 512-bit seed (mini-secret) using an optional passphrase. It also includes an example of handling invalid mnemonics.
import binascii
from bip39 import bip39_generate, bip39_validate, bip39_to_mini_secret
# 1. Generate a new 12-word mnemonic in English (default)
mnemonic_en = bip39_generate(12)
print(f"Generated English mnemonic: {mnemonic_en}")
# 2. Validate the mnemonic
is_valid_en = bip39_validate(mnemonic_en)
print(f"Is English mnemonic valid? {is_valid_en}")
# 3. Generate a 24-word mnemonic in French
mnemonic_fr = bip39_generate(24, 'fr')
print(f"Generated French mnemonic: {mnemonic_fr}")
# 4. Validate the French mnemonic
is_valid_fr = bip39_validate(mnemonic_fr, 'fr')
print(f"Is French mnemonic valid? {is_valid_fr}")
# 5. Convert a mnemonic to a mini-secret (seed)
passphrase = "mysecretpassphrase"
seed_array = bip39_to_mini_secret(mnemonic_en, passphrase)
seed_hex = binascii.hexlify(bytearray(seed_array)).decode("ascii")
print(f"Seed for English mnemonic (hex): {seed_hex}")
# Example of an invalid mnemonic
invalid_mnemonic = "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zebra"
try:
bip39_validate(invalid_mnemonic)
except ValueError as e:
print(f"Validation failed for invalid mnemonic: {e}")
Debug
Known issues
gotchaThe installed package name is `py-bip39-bindings`, but the Python module to import is `bip39`. Directly importing `py_bip39_bindings` will result in a `ModuleNotFoundError`.fixAlways use `from bip39 import ...` for imports.
affects: All versions
gotchaThis library is a set of Rust bindings. If pre-built wheels are not available for your specific platform and Python version, `pip install` will attempt to compile from source. This requires the Rust toolchain (Rustup, Cargo) and Maturin to be installed on your system.fixEnsure you have `rustup` and `maturin` installed if you encounter compilation errors during installation. For most users, pre-built wheels should be sufficient.
affects: All versions when compiling from source
breakingRecent major updates in the underlying `PyO3` Rust library (e.g., from v0.20.3 to v0.26.0 in v0.2.0 and v0.3.0 releases) may introduce subtle ABI incompatibilities or compilation issues if you are building from source or relying on specific build environments. While usually transparent for wheel users, these can affect custom builds or environments where Python and Rust versions are tightly managed.fixIf encountering unexpected errors after upgrading, ensure your Rust toolchain and `maturin` are up-to-date. If using pre-built wheels, a clean reinstall in a new virtual environment might resolve rare compatibility issues.
affects: 0.2.0, 0.3.0 and potentially future versions with PyO3 upgrades.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'py_bip39_bindings'
Attempting to import the library using its PyPI package name (`py-bip39-bindings`) instead of its internal module name.
fixThe correct import statement is `from bip39 import ...`.
error: can't find Rust toolchain
The `pip install` command failed because pre-built wheels were not available for your system, and your environment lacks the necessary Rust compiler (`rustup`, `cargo`) and `maturin` build tool to compile the Rust bindings.
fixInstall the Rust toolchain by following instructions at rustup.rs, and then `pip install maturin` before retrying `pip install py-bip39-bindings`.
ValueError: Invalid mnemonic phrase
The provided mnemonic string does not conform to the BIP39 specification (e.g., incorrect word count, words not in the wordlist for the specified language, invalid checksum).
fixEnsure the mnemonic is correctly spelled, contains the correct number of words (12, 15, 18, 21, or 24), and that the `lang` parameter matches the language of the mnemonic's wordlist if not English.
Upgrade
Version history
0.3.0latest on PyPI · released Sep 3, 2025
Audit
Dependencies
No dependency data recorded yet.