{"id":2414,"library":"bitstruct","title":"bitstruct","description":"This module performs conversions between Python values and C bit field structs represented as Python byte strings. It offers an interface similar to Python's built-in `struct` module but operates at the bit level. The current version is 8.22.1, and it maintains an active release cadence with recent updates.","status":"active","version":"8.22.1","language":"en","source_language":"en","source_url":"https://github.com/eerimoq/bitstruct","tags":["bit manipulation","binary","struct","pack","unpack","bitfield","embedded"],"install":[{"cmd":"pip install bitstruct","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Optional faster C implementation, providing the same API with increased performance but specific limitations.","package":"cbitstruct","optional":true}],"imports":[{"symbol":"pack","correct":"from bitstruct import pack, unpack, calcsize"},{"symbol":"compile","correct":"import bitstruct\ncompiled_format = bitstruct.compile('u8')"},{"note":"The pure Python implementation is used by default. To use the faster C implementation (with limitations), you must explicitly import 'bitstruct.c as bitstruct'.","wrong":"import bitstruct","symbol":"C-backed implementation","correct":"import bitstruct.c as bitstruct"},{"note":"To use the standalone, faster C implementation (if 'cbitstruct' is installed and with its own limitations), you must explicitly import 'cbitstruct as bitstruct'.","wrong":"import bitstruct","symbol":"External C-backed implementation","correct":"import cbitstruct as bitstruct"}],"quickstart":{"code":"from bitstruct import pack, unpack, calcsize\n\n# Define a format string: u1 (1-bit unsigned), u3 (3-bit unsigned), u4 (4-bit unsigned), s16 (16-bit signed)\nfmt = 'u1u3u4s16'\n\n# Pack values into a byte string\npacked_data = pack(fmt, 1, 2, 3, -4)\nprint(f\"Packed data: {packed_data}\")\n# Expected: b'\\xa3\\xff\\xfc'\n\n# Unpack values from the byte string\nunpacked_values = unpack(fmt, packed_data)\nprint(f\"Unpacked values: {unpacked_values}\")\n# Expected: (1, 2, 3, -4)\n\n# Calculate the total number of bits required for the format\nsize_in_bits = calcsize(fmt)\nprint(f\"Size in bits: {size_in_bits}\")\n# Expected: 24 (bits)\n\n# Using a compiled format for efficiency\nimport bitstruct\ncf = bitstruct.compile(fmt)\ncompiled_packed = cf.pack(1, 2, 3, -4)\ncompiled_unpacked = cf.unpack(compiled_packed)\nprint(f\"Compiled format packed: {compiled_packed}\")\nprint(f\"Compiled format unpacked: {compiled_unpacked}\")","lang":"python","description":"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."},"warnings":[{"fix":"Be 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`.","message":"The 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.","severity":"gotcha","affected_versions":"All versions with C implementations (e.g., >=8.17.0)"},{"fix":"For maximum performance, especially with many operations, prefer the `pack()` and `unpack()` functions with direct argument passing rather than the dictionary-based functions.","message":"The `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.","severity":"gotcha","affected_versions":"All versions supporting the dict API"},{"fix":"If you intend to use the faster C-backed code, ensure your import statement reflects this, e.g., `import bitstruct.c as bitstruct`.","message":"The 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).","severity":"gotcha","affected_versions":"All versions with C implementations (e.g., >=8.17.0)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}