Python Bitcoin Library

0.12.2 · active · verified Thu Apr 16

python-bitcoinlib is a comprehensive Python library designed to interact with the Bitcoin protocol. It provides utilities for handling cryptographic operations, addresses, scripts, transactions, and more. The current stable version is 0.12.2, with releases occurring sporadically based on needed updates and bug fixes.

Common errors

```
ModuleNotFoundError: No module named 'python_bitcoinlib'
```
cause You are attempting to import the library using its PyPI package name (`python_bitcoinlib`) instead of its actual top-level module name.

fix Use `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'
```
cause 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.

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

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

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

Warnings

breaking Older 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.
Fix: Upgrade `python-bitcoinlib` to version 0.11.1 or newer. These versions include a pure-Python RIPEMD-160 implementation, resolving compatibility issues.
gotcha Mixing 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.
Fix: Always 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.
gotcha Private keys grant full control over Bitcoin funds. Improper handling, such as hardcoding, insecure storage, or logging, can lead to irreversible loss of assets.
Fix: Implement 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.
gotcha Older Bitcoin transaction formats (pre-SegWit) are susceptible to transaction malleability, which can alter the transaction ID (TXID) before confirmation, impacting dependants.
Fix: For 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.

Install

pip install python-bitcoinlib Install latest version

Imports

bitcoin
wrong:
```
import python_bitcoinlib
```
correct:
```
import bitcoin
```
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`.

Quickstart

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

view raw JSON →