Install & Compatibility
Where this runs
tested against v4.4.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.95 runs
installs and imports cleanly · install 0.0s · import 0.082s · 21.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.4s · import 0.072s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Bits
✓ from bitstring import Bits
Immutable container of bits. Replaces the deprecated ConstBitArray.
BitArray
✓ from bitstring import BitArray
Mutable container of bits. Replaces the deprecated BitString.
BitStream
✓ from bitstring import BitStream
Adds a bit position and reading/parsing methods to BitArray, allowing stream-like operations.
pack
✓ from bitstring import pack
Function for creating bitstrings from formatted values.
Array
✓ from bitstring import Array
Container for fixed-length bitstrings, no longer in beta.
ConstBitArray
✓ from bitstring import Bits
✗ from bitstring import ConstBitArray
The `ConstBitArray` alias was removed in version 4.0. Use `Bits` instead.
BitString
✓ from bitstring import BitArray
✗ from bitstring import BitString
The `BitString` alias was removed in version 4.0. Use `BitArray` or `BitStream` instead.
This quickstart demonstrates creating BitArray objects from various string formats (hexadecimal, binary, octal, formatted integers), packing multiple values into a bitstring, and reading data sequentially from a BitStream.
from bitstring import BitArray, BitStream, pack
# Create a BitArray from a hexadecimal string
a = BitArray('0xff01')
print(f"BitArray 'a': {a.bin} (length: {a.len} bits)")
# Create a BitArray from multiple formats
c = BitArray('0xff, 0b101, 0o65, uint:6=22')
print(f"BitArray 'c': {c.hex} (length: {c.len} bits)")
# Pack values into a bitstring
d = pack('intle:16, hex=a, 0b1', 100, a='0x34f')
print(f"Packed bitstring 'd': {d.bin} (length: {d.len} bits)")
# Read sequentially from a BitStream
b = BitStream('0x160120f')
print(f"Initial BitStream 'b': {b.hex}")
read_hex = b.read(12).hex
print(f"Read 12 bits as hex: {read_hex}, remaining: {b.hex}")
b.pos = 0 # Reset position
read_uint = b.read('uint:12')
print(f"Read 12 bits as uint: {read_uint}")
Debug
Known issues
breakingVersion 4.0 introduced several backward incompatible changes, including dropping support for Python 2.7 and older Python 3 versions (now requires Python 3.7+), removing `ConstBitArray` and `BitString` aliases, and changing the default behavior of `uint` interpretation.fixMigrate to Python 3.7+ (current requirement is >=3.8). Replace `ConstBitArray` with `Bits` and `BitString` with `BitArray` or `BitStream`. Review code using `uint` interpretation as it now returns a bitstring object by default instead of an integer.
affects: >=4.0.0
breakingThe `cut()` method in version 4.0 now yields the final bits even if they are shorter than the requested cut size. Previously, it might have raised an exception or omitted partial cuts.fixAdjust code that relies on the previous behavior of `cut()` to handle potentially shorter final bitstrings.
affects: >=4.0.0
breakingOverwrites extending beyond the end of a bitstring in version 4.0 will now extend the bitstring rather than raising an exception.fixReview code that performs overwrites to ensure this new behavior is intended. If strict length checking is required, add explicit length validation before overwriting.
affects: >=4.0.0
gotchaWhen initializing `Bits` or `BitArray` from integers, omitting quotes around hexadecimal, octal, or binary string representations will result in creating a bitstring of that *integer value* in zero bits, not a bitstring parsed from the string. For example, `BitArray(0xff01)` creates 65281 zero bits.fixAlways use quotes for string representations: `BitArray('0xff01')`, `BitArray('0b110')`. affects: All versions
deprecatedThe `bitstring.lsb0` and `bitstring.bytealigned` module-level variables for changing options are deprecated. Use `bitstring.options.lsb0` and `bitstring.options.bytealigned` instead.fixUpdate direct access to `bitstring.lsb0` and `bitstring.bytealigned` to use the `bitstring.options` object.
affects: >=4.4.0 (deprecated in 4.4.0, likely removed in 5.x)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'bitstring'
The 'bitstring' library is not installed in the Python environment being used.
fixInstall the library using pip: `pip install bitstring`
ValueError: Cannot convert to hex unambiguously - not multiple of 4 bits.
The bitstring's length is not a multiple of the required number of bits for the requested interpretation (e.g., 4 bits for hexadecimal, 3 for octal, 8 for bytes), leading to an ambiguous conversion.
fixEnsure the bitstring has a length that is a multiple of the required bits for the desired interpretation, or use a method like `.tobytes()` which can pad if necessary. For example, to convert to hex, ensure `len(bitstring) % 4 == 0`.
TypeError: unsupported operand type(s) for +=: 'BitArray' and 'int'
In bitstring versions 4.0 and later, direct integer arguments are no longer automatically promoted to bitstring objects to prevent common errors; an integer is interpreted as a length (creating a bitstring of that many zero bits) rather than a value.
fixExplicitly convert integers to `Bits` objects or use string literals (e.g., '0xff') when operations expect a bitstring, instead of plain integers. For example, `a += Bits(255)` or `a += '0xff'`.
ImportError: cannot import name 'BitString' from 'bitstring'
The class name `BitString` was deprecated and later removed or renamed in newer versions of the library (Python 3.7+) in favor of `BitStream` for mutable streams or `Bits` for immutable bit containers.
fixUse `from bitstring import BitStream` or `from bitstring import Bits` instead of `BitString`.
Upgrade
Version history
4.4.0latest on PyPI · released Mar 10, 2026
Audit
Dependencies
bitarrayrequiredUsed for efficient boolean array handling, particularly by the 'Array' class. Pinned to '>=3.0.0'.