cbitstruct

What it is and what it does

cbitstruct is a C-based reimplementation of the bitstruct library, designed to parse and serialize binary data (bit fields, packed structs, protocol messages) much faster than the pure-Python version. It provides the same API—pack, unpack, pack_into, unpack_from, and compiled format objects—so you can often swap it in as a drop-in replacement by changing the import statement.

The tradeoff is that cbitstruct has real limitations: fields are capped at 64 bits (except padding), it only runs on CPython, error messages are less helpful, and it may not work on big-endian systems. The description notes that exceptions differ from bitstruct and some limitations are unlikely to be lifted. It's best suited for performance-critical code paths where you're already familiar with bitstruct and need the speed boost.

Use it for:

• Parsing binary network protocols or packet formats where speed matters and fields fit within 64 bits.
• Serializing structured data into compact binary form for storage or transmission in latency-sensitive applications.
• Unpacking embedded device telemetry or sensor data streams with high throughput requirements.
• Building compiled format objects for repeated pack/unpack cycles in tight loops.
• Migrating performance-critical bitstruct code to C acceleration without rewriting the logic.

Worth the install?

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

A C-accelerated implementation of the bitstruct library that packs and unpacks binary data into Python objects with significantly higher performance than the pure-Python original.

Yes, if you are already using bitstruct and have identified bit packing/unpacking as a bottleneck in a CPython application on x86_64 Linux. The performance gains are substantial, and the API compatibility makes migration straightforward. No, if you need portability to other architectures, big-endian systems, or non-CPython implementations, or if you require clear error messages and full bitstruct feature parity. The copyleft license (MPL-2.0) also requires careful review if you plan to distribute derived works.

Install

cbitstruct on PyPI

pip install cbitstruct

uv add cbitstruct

poetry add cbitstruct

Installing cbitstruct

Before you install

Medium install friction due to compiled C extension wheels; prebuilt binaries are available for Python 3.8–3.14 on x86_64 Linux, but the package is aging (last release 186 days ago) with modest maintenance activity.

License in practice

Licensed under MPL-2.0 (copyleft); derivative works and modifications must be distributed under the same license, which may restrict commercial or proprietary use without disclosure.

Quickstart

pip install cbitstruct

import cbitstruct

# Pack integers into bits
packed = cbitstruct.pack('u8', 1)

# Unpack bits back to integers
unpacked = cbitstruct.unpack('u8', packed)

Requires CPython 3.8 or later; C extension wheels are available only for x86_64 Linux (manylinux2014 and later); other platforms or architectures require compilation from source.

Verify before relying

• Whether the performance gains reported in the test suite (ranging from 8× to 139× faster) hold for real-world workloads outside the benchmark.
• Whether the 64-bit field limit and potential big-endian architecture issues affect your use case.
• Current maintenance trajectory and whether limitations listed as 'Maybe' or 'Probably not' are likely to be addressed.

Package facts

Evidence: cbitstruct-1.2.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; cbitstruct-1.2.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; cbitstruct-1.2.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; cbitstruct-1.2.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; cbitstruct-1.2.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; cbitstruct-1.2.0-cp38-cp38-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; cbitstruct-1.2.0-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Keywords: bit, pack, unpack, struct, bitfield, bit parsing, bit unpack, bit pack, C

Tags

More Software Development packages