{"id":8458,"library":"py-bip39-bindings","title":"Python BIP39 Bindings","description":"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.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/JAMdotTech/py-bip39","tags":["cryptography","bip39","mnemonic","wallet","rust-bindings","seed-phrase"],"install":[{"cmd":"pip install py-bip39-bindings","lang":"bash","label":"Install from PyPI"}],"dependencies":[],"imports":[{"note":"The installed package 'py-bip39-bindings' exposes its functionality under the 'bip39' module name.","wrong":"from py_bip39_bindings import bip39_generate","symbol":"bip39_generate","correct":"from bip39 import bip39_generate"},{"note":"The top-level module is named 'bip39'.","symbol":"bip39_validate","correct":"from bip39 import bip39_validate"},{"note":"The top-level module is named 'bip39'.","symbol":"bip39_to_mini_secret","correct":"from bip39 import bip39_to_mini_secret"}],"quickstart":{"code":"import binascii\nfrom bip39 import bip39_generate, bip39_validate, bip39_to_mini_secret\n\n# 1. Generate a new 12-word mnemonic in English (default)\nmnemonic_en = bip39_generate(12)\nprint(f\"Generated English mnemonic: {mnemonic_en}\")\n\n# 2. Validate the mnemonic\nis_valid_en = bip39_validate(mnemonic_en)\nprint(f\"Is English mnemonic valid? {is_valid_en}\")\n\n# 3. Generate a 24-word mnemonic in French\nmnemonic_fr = bip39_generate(24, 'fr')\nprint(f\"Generated French mnemonic: {mnemonic_fr}\")\n\n# 4. Validate the French mnemonic\nis_valid_fr = bip39_validate(mnemonic_fr, 'fr')\nprint(f\"Is French mnemonic valid? {is_valid_fr}\")\n\n# 5. Convert a mnemonic to a mini-secret (seed)\npassphrase = \"mysecretpassphrase\"\nseed_array = bip39_to_mini_secret(mnemonic_en, passphrase)\nseed_hex = binascii.hexlify(bytearray(seed_array)).decode(\"ascii\")\nprint(f\"Seed for English mnemonic (hex): {seed_hex}\")\n\n# Example of an invalid mnemonic\ninvalid_mnemonic = \"zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zebra\"\ntry:\n    bip39_validate(invalid_mnemonic)\nexcept ValueError as e:\n    print(f\"Validation failed for invalid mnemonic: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always use `from bip39 import ...` for imports.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you have `rustup` and `maturin` installed if you encounter compilation errors during installation. For most users, pre-built wheels should be sufficient.","message":"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.","severity":"gotcha","affected_versions":"All versions when compiling from source"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.2.0, 0.3.0 and potentially future versions with PyO3 upgrades."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"The correct import statement is `from bip39 import ...`.","cause":"Attempting to import the library using its PyPI package name (`py-bip39-bindings`) instead of its internal module name.","error":"ModuleNotFoundError: No module named 'py_bip39_bindings'"},{"fix":"Install the Rust toolchain by following instructions at rustup.rs, and then `pip install maturin` before retrying `pip install py-bip39-bindings`.","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.","error":"error: can't find Rust toolchain"},{"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.","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).","error":"ValueError: Invalid mnemonic phrase"}]}