Python BIP39 Bindings

0.3.0 · active · verified Thu Apr 16

py-bip39-bindings provides fast and safe Python bindings for the `tiny-bip39` Rust crate. It enables the generation, validation, and conversion of BIP39 mnemonic phrases to mini-secrets (seeds) with multi-language support. The library is currently at version 0.3.0 and maintains an active release cadence, frequently updating to support newer Python versions and underlying PyO3 bindings.

Common errors

```
ModuleNotFoundError: No module named 'py_bip39_bindings'
```
cause Attempting to import the library using its PyPI package name (`py-bip39-bindings`) instead of its internal module name.

fix The correct import statement is `from bip39 import ...`.
```
error: can't find Rust toolchain
```
cause 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.

fix Install 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
```
cause 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).

fix Ensure 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.

Warnings

gotcha The 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`.
Fix: Always use `from bip39 import ...` for imports.
gotcha This 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.
Fix: Ensure you have `rustup` and `maturin` installed if you encounter compilation errors during installation. For most users, pre-built wheels should be sufficient.
breaking Recent 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.
Fix: If 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.

Install

pip install py-bip39-bindings Install from PyPI

Imports

bip39_generate
wrong:
```
from py_bip39_bindings import bip39_generate
```
correct:
```
from bip39 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'.

Quickstart

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}")

view raw JSON →