{"id":1950,"library":"bitstring","title":"bitstring","description":"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.","status":"active","version":"4.4.0","language":"en","source_language":"en","source_url":"https://github.com/scott-griffiths/bitstring","tags":["binary data","bit manipulation","data parsing","networking","embedded systems"],"install":[{"cmd":"pip install bitstring","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for efficient boolean array handling, particularly by the 'Array' class. Pinned to '>=3.0.0'.","package":"bitarray","optional":false}],"imports":[{"note":"Immutable container of bits. Replaces the deprecated ConstBitArray.","symbol":"Bits","correct":"from bitstring import Bits"},{"note":"Mutable container of bits. Replaces the deprecated BitString.","symbol":"BitArray","correct":"from bitstring import BitArray"},{"note":"Adds a bit position and reading/parsing methods to BitArray, allowing stream-like operations.","symbol":"BitStream","correct":"from bitstring import BitStream"},{"note":"Function for creating bitstrings from formatted values.","symbol":"pack","correct":"from bitstring import pack"},{"note":"Container for fixed-length bitstrings, no longer in beta.","symbol":"Array","correct":"from bitstring import Array"},{"note":"The `ConstBitArray` alias was removed in version 4.0. Use `Bits` instead.","wrong":"from bitstring import ConstBitArray","symbol":"ConstBitArray","correct":"from bitstring import Bits"},{"note":"The `BitString` alias was removed in version 4.0. Use `BitArray` or `BitStream` instead.","wrong":"from bitstring import BitString","symbol":"BitString","correct":"from bitstring import BitArray"}],"quickstart":{"code":"from bitstring import BitArray, BitStream, pack\n\n# Create a BitArray from a hexadecimal string\na = BitArray('0xff01')\nprint(f\"BitArray 'a': {a.bin} (length: {a.len} bits)\")\n\n# Create a BitArray from multiple formats\nc = BitArray('0xff, 0b101, 0o65, uint:6=22')\nprint(f\"BitArray 'c': {c.hex} (length: {c.len} bits)\")\n\n# Pack values into a bitstring\nd = pack('intle:16, hex=a, 0b1', 100, a='0x34f')\nprint(f\"Packed bitstring 'd': {d.bin} (length: {d.len} bits)\")\n\n# Read sequentially from a BitStream\nb = BitStream('0x160120f')\nprint(f\"Initial BitStream 'b': {b.hex}\")\nread_hex = b.read(12).hex\nprint(f\"Read 12 bits as hex: {read_hex}, remaining: {b.hex}\")\nb.pos = 0 # Reset position\nread_uint = b.read('uint:12')\nprint(f\"Read 12 bits as uint: {read_uint}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Adjust code that relies on the previous behavior of `cut()` to handle potentially shorter final bitstrings.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Overwrites extending beyond the end of a bitstring in version 4.0 will now extend the bitstring rather than raising an exception.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always use quotes for string representations: `BitArray('0xff01')`, `BitArray('0b110')`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update direct access to `bitstring.lsb0` and `bitstring.bytealigned` to use the `bitstring.options` object.","message":"The `bitstring.lsb0` and `bitstring.bytealigned` module-level variables for changing options are deprecated. Use `bitstring.options.lsb0` and `bitstring.options.bytealigned` instead.","severity":"deprecated","affected_versions":">=4.4.0 (deprecated in 4.4.0, likely removed in 5.x)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}