Install & Compatibility
Where this runs
tested against v0.12.2 · 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.010s · 18.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.8s · import 0.010s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
bitcoin
✓ import bitcoin
✗ import python_bitcoinlib
The PyPI package name is `python-bitcoinlib`, but the top-level import is `bitcoin`.
CTransaction
✓ from bitcoin.core import CTransaction
COIN
✓ from bitcoin.core import COIN
CBitcoinAddress
✓ from bitcoin.wallet import CBitcoinAddress
P2PKHAddress
✓ from bitcoin.wallet import P2PKHAddress
P2PKHAddress is a common concrete address type; there are others like P2SHAddress, P2WPKHAddress.
CBitcoinSecret
✓ from bitcoin.wallet import CBitcoinSecret
CScript
✓ from bitcoin.script import CScript
MAINNET
✓ from bitcoin.main import MAINNET
Constants for network parameters (e.g., MAINNET, TESTNET, REGTEST) are in `bitcoin.main`.
This quickstart demonstrates how to generate a new Bitcoin private key and derive its corresponding P2PKH address for the Mainnet. It showcases the basic cryptographic primitives used for wallet management. Remember to handle private keys with extreme care in production environments.
from bitcoin.wallet import CBitcoinSecret, P2PKHAddress
from bitcoin.main import MAINNET # Import specific networks
# 1. Generate a new random private key for the Bitcoin Mainnet
# In a real application, you must store this secret securely.
# For Testnet, replace MAINNET with TESTNET.
private_key = CBitcoinSecret.from_secret_bytes(CBitcoinSecret.generate_secret_bytes(), MAINNET)
# 2. Derive the corresponding public key
public_key = private_key.pub
# 3. Derive a Pay-to-Public-Key-Hash (P2PKH) address from the public key
address = P2PKHAddress.from_pubkey(public_key)
print(f"Generated Private Key (WIF format): {private_key.D.to_string()}")
print(f"Corresponding Bitcoin Address: {address}")
print(f"Network: {'Mainnet' if private_key.is_mainnet else 'Testnet' if private_key.is_testnet else 'Unknown'}")
Debug
Known issues
breakingOlder versions of python-bitcoinlib (prior to 0.11.1) relied on OpenSSL for RIPEMD-160 hashing. Newer OpenSSL versions have removed RIPEMD-160 support, leading to errors.fixUpgrade `python-bitcoinlib` to version 0.11.1 or newer. These versions include a pure-Python RIPEMD-160 implementation, resolving compatibility issues.
affects: <0.11.1
gotchaMixing up network parameters (e.g., `MAINNET`, `TESTNET`, `REGTEST`) can lead to addresses or transactions valid for the wrong network, potentially resulting in loss of funds or failed transactions.fixAlways explicitly pass the correct network parameter (e.g., `MAINNET`, `TESTNET`) when creating keys, addresses, or transactions. Double-check your chosen network context for all operations.
affects: All versions
gotchaPrivate keys grant full control over Bitcoin funds. Improper handling, such as hardcoding, insecure storage, or logging, can lead to irreversible loss of assets.fixImplement robust security practices for private key generation, storage, and usage. Never hardcode private keys. Utilize secure key management systems or hardware wallets for production environments.
affects: All versions
gotchaOlder Bitcoin transaction formats (pre-SegWit) are susceptible to transaction malleability, which can alter the transaction ID (TXID) before confirmation, impacting dependants.fixFor new transactions, prioritize SegWit formats (e.g., P2WPKH, P2SH-P2WPKH) to mitigate malleability. Be aware of this risk when dealing with unconfirmed legacy transactions or when building systems that rely on stable TXIDs.
affects: All versions (when interacting with legacy transaction types)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'python_bitcoinlib'
You are attempting to import the library using its PyPI package name (`python_bitcoinlib`) instead of its actual top-level module name.
fixUse `import bitcoin` or `from bitcoin import ...` to access the library's modules.
ValueError: RIPEMD160 hash not found or AttributeError: module 'OpenSSL.crypto' has no attribute 'RIPEMD160'
Your version of `python-bitcoinlib` (prior to 0.11.1) is trying to use OpenSSL's RIPEMD160 function, which has been removed in newer OpenSSL libraries.
fixUpgrade `python-bitcoinlib` to version 0.11.1 or newer (`pip install --upgrade python-bitcoinlib`). These versions include a pure-Python RIPEMD160 implementation, making it compatible with modern OpenSSL.
ValueError: Invalid checksum for base58 string
The Bitcoin address or WIF (Wallet Import Format) string you provided is malformed, contains a typo, or does not correspond to the expected network (e.g., trying to decode a Mainnet address as Testnet).
fixCarefully verify the input string for accuracy. Ensure the network context (e.g., `MAINNET`, `TESTNET`) matches the address or key you are trying to parse.
ConnectionRefusedError: [Errno 111] Connection refused
When using `bitcoin.rpc`, this indicates the Bitcoin Core node's RPC server is not running, is not accessible from your application, or its configuration prevents connection.
fixEnsure your Bitcoin Core node is running and configured to accept RPC connections (check `bitcoin.conf` for `rpcbind`, `rpcport`, `rpcuser`, `rpcpassword`). Verify firewall rules and network connectivity between your application and the node.
Upgrade
Version history
0.12.2latest on PyPI · released Jun 3, 2023
Audit
Dependencies
No dependency data recorded yet.