cbitstruct

library1.2.0pypypi✓ verified 86d ago

cbitstruct is a Python library providing a faster C implementation of `bitstruct`. It offers API compatibility with `bitstruct`, allowing for efficient packing and unpacking of bitfields from and to Python data types. The current version is 1.2.0, and releases primarily focus on Python version support and bug fixes, with a focus on stability and performance.

serialization

pip install cbitstruct

github ↗package ↗

INSTALL

IMPORT

SIG · CBITSTRUCT

cbitstruct

serializationpythonv1.2.0

Install

1.7s avg

Import

—

Disk

16MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.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

musl

py 3.10–3.910 runs

build_error

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.7s · import 0.000s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pack

✓ from cbitstruct import pack

unpack

✓ from cbitstruct import unpack

byteswap

✓ from cbitstruct import byteswap

This quickstart demonstrates packing and unpacking bitfields using `cbitstruct`. It's designed to be API compatible with the original `bitstruct` library, allowing for a drop-in replacement for performance-critical applications.

from cbitstruct import pack, unpack # Pack 8 single-bit unsigned integers into a byte data = pack('u1u1u1u1u1u1u1u1', 1, 0, 1, 0, 1, 0, 1, 0) print(f"Packed data: {data!r}") # Expected: b'\xaa' # Unpack the data back into a tuple of integers unpacked_data = unpack('u1u1u1u1u1u1u1u1', data) print(f"Unpacked data: {unpacked_data}") # Expected: (1, 0, 1, 0, 1, 0, 1, 0) # Example with different format string value = pack('u4u4', 0xA, 0x5) print(f"Packed nibbles: {value!r}") # Expected: b'\xa5'

Debug

Known issues

gotchaIncorrect usage of format strings or input values can lead to segmentation faults due to `cbitstruct` being a C extension. This was particularly prevalent in early versions (1.0.0 - 1.0.3).

fix

Always double-check your format strings against `bitstruct` documentation and ensure input values match the specified bitfield sizes. Update to the latest version, as many such issues have been fixed.

affects: <=1.0.3

gotchaWhile `cbitstruct` aims for full API compatibility with `bitstruct`, subtle differences in edge cases or error handling might exist. Always test thoroughly when replacing `bitstruct` with `cbitstruct` in critical paths.

fix

Consult the `cbitstruct` GitHub repository for any known deviations. Run existing `bitstruct` test suites against `cbitstruct` if possible.

affects: All versions

Errors

Common errors & fixes

Segmentation fault (core dumped)

`cbitstruct` received invalid input data or a malformed format string, leading to memory access violations in the underlying C code.

fix

Carefully review the format string and ensure the input values (for `pack`) or binary data (for `unpack`) strictly adhere to the expected format. Common mistakes include providing too few/many arguments for `pack` or providing data shorter than the format string demands for `unpack`. Update to the latest `cbitstruct` version as many such issues have been patched.

ModuleNotFoundError: No module named 'cbitstruct'

The `cbitstruct` package is not installed in the active Python environment or is not accessible on the Python path.

fix

Ensure `cbitstruct` is installed using `pip install cbitstruct`. If you are using a virtual environment, activate it before installing. Verify the installation by running `python -c "import cbitstruct"`.

TypeError: 'str' object cannot be interpreted as an integer

Attempting to pass a string where an integer (representing a bitfield value) is expected, likely when calling `pack`.

fix

Ensure all individual values passed to `pack` (after the format string) are integers, even if they represent binary data. For example, `pack('u8', 0b10101010)` or `pack('u8', 170)`, not `pack('u8', '0b10101010')`.

Upgrade

Version history

1.2.0latest on PyPI · released Feb 9, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/qchateau/cbitstruct ↗

packagehttps://pypi.org/project/cbitstruct/ ↗