Registry / serialization / dissect-cstruct

dissect-cstruct

JSON →
library4.7pypypi✓ verified 91d ago

dissect-cstruct is a Python library from the Dissect project designed for parsing C-like structures from binary data. It allows users to define structures using Python classes or C-like syntax and then parse byte streams into accessible Python objects. The current version is 4.7, and it is actively maintained with a regular release cadence.

pip install dissect-cstruct
INSTALL
IMPORT
SIG · DISSECT-CSTRUCT
D
dissect-cstruct
serializationpythonv4.7
Install
1.6s avg
Import
96ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v4.7 · 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
installs and imports cleanly · install 0.0s · import 0.096s · 18.2MB
glibc
py 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.095s · 19MB
16MB installed
● package 16MB
Code
Verified usage

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

cstruct
✓ from dissect.cstruct import cstruct
✗ import cstruct
The cstruct module is part of the 'dissect' namespace.

This example demonstrates how to define a C-like structure using `typedef`, create a byte string, and then parse it into an accessible Python object using `dissect-cstruct`.

from dissect.cstruct import cstruct import struct # Initialize a cstruct context ctx = cstruct() # Define a C-like structure using a multiline string ctx.typedef( """ struct Header { uint32_t magic; uint16_t version; char name[10]; }; """ ) # Example binary data conforming to the structure # magic = 0xDEADBEEF (little endian) # version = 0x0100 (little endian) # name = "TestHeader" (10 chars) # Use struct.pack to ensure correct byte ordering for the example example_data = struct.pack("<I H 10s", 0xDEADBEEF, 0x0100, b"TestHeader") # Parse the data using the defined structure parsed_header = ctx.Header(example_data) # Access fields of the parsed structure print(f"Magic: {hex(parsed_header.magic)}") print(f"Version: {parsed_header.version}") print(f"Name: {parsed_header.name.decode('ascii')}") # Assertions to verify correct parsing assert parsed_header.magic == 0xDEADBEEF assert parsed_header.version == 0x0100 assert parsed_header.name == b"TestHeader" print("Structure parsed successfully!")
Debug
Known issues
breakingThe `Instance` class was renamed from `dissect.cstruct.Instance` to `dissect.cstruct.types.Instance`.
fix
Update import statements to `from dissect.cstruct.types import Instance` where applicable.
affects: 4.0.0 and later
breakingThe `Structure` and `Array` classes (e.g., used for type hints) now inherit from `typing.Generic` and are parameterized. They can no longer be used as bare types in a `cstruct` definition without proper parameterization.
fix
Review advanced type definitions and type hints. For `cstruct` definitions, ensure you are using the correct `cstruct.Type` or `cstruct.Context` parameterization if you were directly subclassing or referencing these generic types.
affects: 4.0.0 and later
breaking`dissect-cstruct` dropped support for Python 3.7 and 3.8.
fix
Ensure your project is running on Python 3.10 or newer.
affects: 4.0.0 and later
gotchaThe `cstruct` parsing functions (e.g., `ctx.MyStruct(data)`) expect a bytes-like object (e.g., `bytes` or `bytearray`) for input. Passing a `str` will result in a `TypeError`.
fix
Always provide binary data. If you have a string representation, encode it first: `my_string.encode('utf-8')` (or another appropriate encoding).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cstruct'
Attempting to import `cstruct` directly instead of from its location within the `dissect` package.
fix
Use the correct import path: `from dissect.cstruct import cstruct`.
TypeError: 'str' object cannot be interpreted as a byte-like object
Passing a Python string to a `cstruct` type constructor (e.g., `ctx.MyStruct('some string')`) which expects bytes for parsing.
fix
Ensure the input data is a `bytes` object. For example, use a byte literal (`b'some string'`) or encode a string (`'some string'.encode('ascii')`).
AttributeError: type object 'Instance' has no attribute 'X'
This often occurs when migrating from `dissect-cstruct` versions older than 4.0.0, where the `Instance` class was moved.
fix
Update your import statement for `Instance` from `from dissect.cstruct import Instance` to `from dissect.cstruct.types import Instance`.
Upgrade
Version history
4.7latest on PyPI · released Nov 20, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
20 hits · last 30 days
node
20
Resources
dissect-cstruct — pip install dissect-cstruct · libregistry