bitstring

4.4.0 · active · verified Thu Apr 09

bitstring is a Python library designed for the simple and efficient creation, analysis, and modification of bit-level binary data. It has been actively maintained since 2006 and is currently at version 4.4.0, with a regular release cadence for maintenance and new features.

Warnings

breaking Version 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.
Fix: Migrate 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.
breaking The `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.
Fix: Adjust code that relies on the previous behavior of `cut()` to handle potentially shorter final bitstrings.
breaking Overwrites extending beyond the end of a bitstring in version 4.0 will now extend the bitstring rather than raising an exception.
Fix: Review code that performs overwrites to ensure this new behavior is intended. If strict length checking is required, add explicit length validation before overwriting.
gotcha When 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.
Fix: Always use quotes for string representations: `BitArray('0xff01')`, `BitArray('0b110')`.
deprecated The `bitstring.lsb0` and `bitstring.bytealigned` module-level variables for changing options are deprecated. Use `bitstring.options.lsb0` and `bitstring.options.bytealigned` instead.
Fix: Update direct access to `bitstring.lsb0` and `bitstring.bytealigned` to use the `bitstring.options` object.

Install

pip install bitstring Install stable version

Imports

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
```
The `ConstBitArray` alias was removed in version 4.0. Use `Bits` instead.
BitString
```
from bitstring import BitArray
```
The `BitString` alias was removed in version 4.0. Use `BitArray` or `BitStream` instead.

Quickstart

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

view raw JSON →