bitstruct

What it is and what it does

Bitstruct converts between Python values and bit-level binary structures, extending the interface of Python's built-in struct module to work on individual bits instead of bytes. It provides functions to pack values into compact binary representations and unpack them back, with support for unsigned integers, signed integers, floats, booleans, raw bytes, and text strings at arbitrary bit boundaries.

Format strings specify bit widths and types (e.g., 'u1u3u4s16' for a 1-bit unsigned, 3-bit unsigned, 4-bit unsigned, and 16-bit signed integer), and compiled format objects allow reuse of the same specification across multiple operations. It supports bit-offset packing into existing buffers, dictionary-based packing/unpacking, and byte-order control. The library includes both a pure Python implementation and optional C accelerations for faster pack/unpack operations on CPython 3.

Use it for:

• Parse binary network protocols or file formats with non-byte-aligned fields (e.g., bit flags, variable-width integers)
• Serialize structured data into compact binary representations for embedded systems or bandwidth-constrained communication
• Extract and manipulate individual bit fields from hardware register dumps or low-level binary data
• Implement bit-level codecs for compression or encoding schemes that operate below byte boundaries
• Test and validate binary protocol implementations by packing/unpacking known test vectors

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Packs and unpacks Python values into bit-level binary structures, similar to the struct module but operating on individual bits rather than bytes.

Yes, if you need to work with bit-level binary data. Bitstruct is stable (Production/Stable status), actively maintained, has no dependencies, and provides a clear interface for a specialized but real problem. The optional C acceleration and wide platform support make it practical for both development and performance-critical code. No security vulnerabilities reported.

Install

bitstruct on PyPI

pip install bitstruct

uv add bitstruct

poetry add bitstruct

Installing bitstruct

Before you install

Medium install friction due to compiled C extensions for multiple platforms (wheels provided for CPython 3.10–3.11 across Linux, macOS, Windows, and ARM architectures). Active maintenance with recent releases; no runtime dependencies.

License in practice

MIT license permits unrestricted use, modification, and distribution in both open and closed-source projects with minimal attribution requirements.

Quickstart

pip install bitstruct

from bitstruct import pack, unpack
packed = pack('u1u3u4s16', 1, 2, 3, -4)
print(packed)  # b'\xa3\xff\xfc'
unpacked = unpack('u1u3u4s16', packed)
print(unpacked)  # (1, 2, 3, -4)

Requires Python 3.9 or later. C implementation available only on CPython 3 and must be explicitly imported; pure Python fallback is default.

Verify before relying

• Whether the C implementation is automatically selected or requires explicit import on supported platforms
• Performance characteristics and speedup magnitude of C vs. pure Python implementation for typical workloads
• Compatibility with Python 3.12+ beyond the stated 3.9+ requirement

Package facts

Evidence: bitstruct-8.22.1-cp310-cp310-macosx_10_9_x86_64.whl; bitstruct-8.22.1-cp310-cp310-macosx_11_0_arm64.whl; bitstruct-8.22.1-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; bitstruct-8.22.1-cp310-cp310-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl; bitstruct-8.22.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; bitstruct-8.22.1-cp310-cp310-musllinux_1_2_aarch64.whl; bitstruct-8.22.1-cp310-cp310-musllinux_1_2_armv7l.whl; bitstruct-8.22.1-cp310-cp310-musllinux_1_2_x86_64.whl; bitstruct-8.22.1-cp310-cp310-win32.whl; bitstruct-8.22.1-cp310-cp310-win_amd64.whl; bitstruct-8.22.1-cp310-cp310-win_arm64.whl; bitstruct-8.22.1-cp311-cp311-macosx_10_9_x86_64.whl; bitstruct-8.22.1-cp311-cp311-macosx_11_0_arm64.whl; bitstruct-8.22.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; bitstruct-8.22.1-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl; bitstruct-8.22.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; bitstruct-8.22.1-cp311-cp311-musllinux_1_2_aarch64.whl; bitstruct-8.22.1-cp311-cp311-musllinux_1_2_armv7l.whl; bitstruct-8.22.1-cp311-cp311-musllinux_1_2_x86_64.whl; bitstruct-8.22.1-cp311-cp311-win32.whl

Keywords: bit field, bit parsing, bit unpack, bit pack

Tags

More Software Development packages