Install & Compatibility
Where this runs
tested against v8.23.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.1MB
glibcpy 3.10–3.95 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 bitstruct import pack, unpack, calcsize
compile
✓ import bitstruct
compiled_format = bitstruct.compile('u8')
C-backed implementation
✓ import bitstruct.c as bitstruct
✗ import bitstruct
The pure Python implementation is used by default. To use the faster C implementation (with limitations), you must explicitly import 'bitstruct.c as bitstruct'.
External C-backed implementation
✓ import cbitstruct as bitstruct
✗ import bitstruct
To use the standalone, faster C implementation (if 'cbitstruct' is installed and with its own limitations), you must explicitly import 'cbitstruct as bitstruct'.
This quickstart demonstrates how to pack Python integers into a compact byte string using a format string, unpack them back, and calculate the size of the packed data. It also shows how to use a pre-compiled format string for repeated operations.
from bitstruct import pack, unpack, calcsize
# Define a format string: u1 (1-bit unsigned), u3 (3-bit unsigned), u4 (4-bit unsigned), s16 (16-bit signed)
fmt = 'u1u3u4s16'
# Pack values into a byte string
packed_data = pack(fmt, 1, 2, 3, -4)
print(f"Packed data: {packed_data}")
# Expected: b'\xa3\xff\xfc'
# Unpack values from the byte string
unpacked_values = unpack(fmt, packed_data)
print(f"Unpacked values: {unpacked_values}")
# Expected: (1, 2, 3, -4)
# Calculate the total number of bits required for the format
size_in_bits = calcsize(fmt)
print(f"Size in bits: {size_in_bits}")
# Expected: 24 (bits)
# Using a compiled format for efficiency
import bitstruct
cf = bitstruct.compile(fmt)
compiled_packed = cf.pack(1, 2, 3, -4)
compiled_unpacked = cf.unpack(compiled_packed)
print(f"Compiled format packed: {compiled_packed}")
print(f"Compiled format unpacked: {compiled_unpacked}")
Debug
Known issues
gotchaThe C-backed implementations (`bitstruct.c` and `cbitstruct`) have limitations compared to the pure Python version. Integers and booleans are limited to 64 bits, and 'text' and 'raw' types must be multiples of 8 bits. `bitstruct.c` also lacks support for bit endianness, byte order, and `byteswap()` is restricted to 1, 2, 4, or 8 byte swaps.fixBe aware of these constraints when using `import bitstruct.c as bitstruct` or `import cbitstruct as bitstruct`. If your data doesn't fit these limitations, use the default pure Python implementation by simply `import bitstruct`.
affects: All versions with C implementations (e.g., >=8.17.0)
gotchaThe `dict` API (e.g., `pack_dict`, `unpack_dict`) can be marginally slower than the traditional tuple-based API. The overhead of dictionary lookups and hashing can significantly increase packing/unpacking duration for performance-critical applications.fixFor maximum performance, especially with many operations, prefer the `pack()` and `unpack()` functions with direct argument passing rather than the dictionary-based functions.
affects: All versions supporting the dict API
gotchaThe pure Python implementation is used by default even if `bitstruct.c` is available. To leverage the faster C implementation, you *must* explicitly import it, typically as `import bitstruct.c as bitstruct` or `import cbitstruct as bitstruct` (if `cbitstruct` is installed).fixIf you intend to use the faster C-backed code, ensure your import statement reflects this, e.g., `import bitstruct.c as bitstruct`.
affects: All versions with C implementations (e.g., >=8.17.0)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'bitstruct'
The 'bitstruct' library is not installed in your Python environment.
ERROR: Failed building wheel for bitstruct
This error typically occurs during installation if required C compilers or development headers are missing, or if there's an incompatibility with the Python version or environment (e.g., MSYS2).
fixEnsure you have C development tools installed (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, or Visual C++ Build Tools on Windows). You might also need `sudo apt-get install python3-dev` (or equivalent) for Python headers. For MSYS2, specific environment setup for compilation is often required. If issues persist, consider installing `cbitstruct` which is a separate C implementation.
bitstruct.Error: 'sX' requires Y <= integer <= Z (got W)
You are attempting to pack a signed integer value (W) that falls outside the representable range (Y to Z) for the specified bit length (X).
fixAdjust the input integer value to be within the valid range for the format string, or choose a format with a larger bit length that can accommodate your value.
bitstruct.Error: 'uX' requires 0 <= integer <= Y (got Z)
You are attempting to pack an unsigned integer value (Z) that falls outside the representable range (0 to Y) for the specified bit length (X).
fixAdjust the input integer value to be non-negative and within the valid range for the format string, or choose a format with a larger bit length that can accommodate your value.
ImportError: cannot import name 'c' from 'bitstruct'
You are trying to import 'c' as a direct submodule or function from 'bitstruct', but `bitstruct.c` (the C implementation) is meant to be imported and aliased as `bitstruct` itself to override the pure Python version, not imported as a submodule for individual functions.
fixTo use the C implementation, use `import bitstruct.c as bitstruct`. After this, you would call functions like `bitstruct.pack()` or `bitstruct.unpack()`. If you need the pure Python implementation, simply use `import bitstruct`.
Upgrade
Version history
8.23.0latest on PyPI · released Aug 21, 2026
Audit
Dependencies
cbitstructoptionalOptional faster C implementation, providing the same API with increased performance but specific limitations.