Install & Compatibility
Where this runs
tested against v1.2.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.012s · 17.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.007s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
bech32_encode
✓ from bech32 import bech32_encode
bech32_decode
✓ from bech32 import bech32_decode
convertbits
✓ from bech32 import convertbits
Essential for converting data between 8-bit bytes and 5-bit integers required by Bech32 encoding.
This quickstart demonstrates encoding and decoding a Bitcoin Segwit v0 P2WPKH address using `bech32_encode` and `bech32_decode`. It highlights the essential `convertbits` utility for converting data between 8-bit bytes and 5-bit groups, which is critical for correct Bech32 implementation. Remember to handle potential `None` returns from `bech32_decode` and `convertbits`.
from bech32 import bech32_encode, bech32_decode, convertbits
# Example 1: Encoding a Segwit v0 P2WPKH address data (20-byte hash)
hrp = "bc" # Human-Readable Part for Bitcoin mainnet
witness_version = 0 # Witness version 0
# Example 20-byte hash (in 8-bit groups)
data_8bit = [0x75, 0x1e, 0x76, 0xe8, 0x19, 0x91, 0x96, 0xd4, 0x54, 0x94,
0x1c, 0x45, 0xd1, 0xb3, 0xa3, 0x23, 0xf1, 0x43, 0x3b, 0xd6]
# Convert 8-bit data to 5-bit groups, prepending witness version
# convertbits returns None if conversion fails
data_5bit = convertbits(data_8bit, 8, 5)
if data_5bit is None:
print("Error converting data to 5-bit groups.")
exit()
# The final data for encoding includes the witness version (0-31) and the converted 5-bit data
encoded_data = [witness_version] + data_5bit
# Encode to Bech32
bech32_address = bech32_encode(hrp, encoded_data)
print(f"Encoded Bech32 address: {bech32_address}")
# Expected: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq
# Example 2: Decoding a Bech32 address
address_to_decode = "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq"
hrp_decoded, data_5bit_decoded = bech32_decode(address_to_decode)
if hrp_decoded is None or data_5bit_decoded is None:
print(f"Error decoding address: {address_to_decode}")
else:
print(f"Decoded HRP: {hrp_decoded}")
print(f"Decoded Data (5-bit groups): {data_5bit_decoded}")
# Extract witness version and program
wit_version = data_5bit_decoded[0]
wit_program_5bit = data_5bit_decoded[1:]
# Convert 5-bit program back to 8-bit bytes
wit_program_8bit = convertbits(wit_program_5bit, 5, 8, pad=False)
if wit_program_8bit is None:
print("Error converting 5-bit program to 8-bit bytes.")
else:
print(f"Witness Version: {wit_version}")
print(f"Witness Program (8-bit hex): {bytes(wit_program_8bit).hex()}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'bech32'
The 'bech32' library has not been installed or is not accessible in the current Python environment.
fixInstall the library using pip: `pip install bech32`
ValueError: Invalid bech32 string
The input string provided to a decoding function (like `bech32_decode`) is not a valid Bech32 format, often due to an incorrect checksum, invalid characters, or an improperly structured human-readable part (HRP). The `bech32_decode` function in the `bech32` library also returns `None` for invalid strings, which might then be handled by higher-level code that raises this `ValueError`.
fixEnsure the Bech32 string is correctly formatted, including a valid HRP, separator, data characters, and checksum. Double-check for typos, case sensitivity (Bech32 is lowercase), and adherence to the BIP-173 standard.
ValueError: Out of range
When preparing data for Bech32 encoding (e.g., using `convert_bits` or directly passing to `bech32_encode`), the input integers must represent 5-bit values, meaning they must be within the range of 0 to 31 inclusive. Passing values outside this range will cause this error.
fixEnsure that the list of integers passed for encoding consists only of values between 0 and 31. If you are converting from 8-bit bytes, use the `bech32.convertbits` function to properly convert to 5-bit groups before encoding.
Upgrade
Version history
1.2.0latest on PyPI · released Feb 17, 2020
Audit
Dependencies
No dependency data recorded yet.