{"id":9657,"library":"dissect-cstruct","title":"Dissect Cstruct","description":"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.","status":"active","version":"4.7","language":"python","source_language":"en","source_url":"https://github.com/fox-it/dissect.cstruct","tags":["c-struct","parsing","binary-parsing","reverse-engineering","data-structures"],"install":[{"cmd":"pip install dissect-cstruct","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The cstruct module is part of the 'dissect' namespace.","wrong":"import cstruct","symbol":"cstruct","correct":"from dissect.cstruct import cstruct"}],"quickstart":{"code":"from dissect.cstruct import cstruct\nimport struct\n\n# Initialize a cstruct context\nctx = cstruct()\n\n# Define a C-like structure using a multiline string\nctx.typedef(\n    \"\"\"\n    struct Header {\n        uint32_t magic;\n        uint16_t version;\n        char name[10];\n    };\n    \"\"\"\n)\n\n# Example binary data conforming to the structure\n# magic = 0xDEADBEEF (little endian)\n# version = 0x0100 (little endian)\n# name = \"TestHeader\" (10 chars)\n# Use struct.pack to ensure correct byte ordering for the example\nexample_data = struct.pack(\"<I H 10s\", 0xDEADBEEF, 0x0100, b\"TestHeader\")\n\n# Parse the data using the defined structure\nparsed_header = ctx.Header(example_data)\n\n# Access fields of the parsed structure\nprint(f\"Magic: {hex(parsed_header.magic)}\")\nprint(f\"Version: {parsed_header.version}\")\nprint(f\"Name: {parsed_header.name.decode('ascii')}\")\n\n# Assertions to verify correct parsing\nassert parsed_header.magic == 0xDEADBEEF\nassert parsed_header.version == 0x0100\nassert parsed_header.name == b\"TestHeader\"\n\nprint(\"Structure parsed successfully!\")","lang":"python","description":"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`."},"warnings":[{"fix":"Update import statements to `from dissect.cstruct.types import Instance` where applicable.","message":"The `Instance` class was renamed from `dissect.cstruct.Instance` to `dissect.cstruct.types.Instance`.","severity":"breaking","affected_versions":"4.0.0 and later"},{"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.","message":"The `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.","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Ensure your project is running on Python 3.10 or newer.","message":"`dissect-cstruct` dropped support for Python 3.7 and 3.8.","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Always provide binary data. If you have a string representation, encode it first: `my_string.encode('utf-8')` (or another appropriate encoding).","message":"The `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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'4.7':51 'access':44 'activ':55 'allow':25 'binari':22,67 'binary-pars':66 'byte':41 'c':18,35,63 'c-like':17,34 'c-struct':62 'cadenc':61 'class':32 'cstruct':2,5 'current':48 'data':23,73 'data-structur':72 'defin':28 'design':14 'dissect':1,4,12 'dissect-cstruct':3 'engin':71 'librari':9 'like':19,36 'maintain':56 'object':46 'pars':16,40,65,68 'project':13 'python':8,31,45 'regular':59 'releas':60 'revers':70 'reverse-engin':69 'stream':42 'struct':64 'structur':20,29,74 'syntax':37 'use':30 'user':26 'version':49","created_at":"2026-04-17T01:20:02.576263+00:00","updated_at":"2026-04-17T01:20:02.576263+00:00","problems":[{"fix":"Use the correct import path: `from dissect.cstruct import cstruct`.","cause":"Attempting to import `cstruct` directly instead of from its location within the `dissect` package.","error":"ModuleNotFoundError: No module named 'cstruct'"},{"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')`).","cause":"Passing a Python string to a `cstruct` type constructor (e.g., `ctx.MyStruct('some string')`) which expects bytes for parsing.","error":"TypeError: 'str' object cannot be interpreted as a byte-like object"},{"fix":"Update your import statement for `Instance` from `from dissect.cstruct import Instance` to `from dissect.cstruct.types import Instance`.","cause":"This often occurs when migrating from `dissect-cstruct` versions older than 4.0.0, where the `Instance` class was moved.","error":"AttributeError: type object 'Instance' has no attribute 'X'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.7","cli_name":"","cli_version":null,"type":"library","homepage":"https://dissect.tools","github":"https://github.com/fox-it/dissect.cstruct","docs":"https://docs.dissect.tools/en/latest/projects/dissect.cstruct","changelog":"https://github.com/fox-it/dissect.cstruct/blob/main/CHANGELOG.md","pypi":"https://pypi.org/project/dissect-cstruct/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}