cstruct

library6.2pypypi✓ verified 85d ago

A Python library for defining and parsing C-style structs. Supports nested structs, arrays, strings, and variable-length fields. Version 6.2 works with Python 3.7+ and supports Python 3.14. Released under the MIT license, with active maintenance and periodic updates.

serialization data

pip install cstruct

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · CSTRUCT

cstruct

serializationpythonv6.2

Install

1.5s avg

Import

58ms

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 v6.2 · 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.95 runs

installs and imports cleanly · install 0.0s · import 0.054s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.062s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

CStruct

✓ from cstruct import CStruct

cstruct

✓ import cstruct

The module itself is also directly importable for low-level use.

Defines a simple Point struct, packs values, and unpacks from bytes.

from cstruct import CStruct # Define a struct matching the C definition: # struct Point { int x; int y; }; class Point(CStruct): __struct__ = [ ('x', 'int'), ('y', 'int'), ] # Create an instance and pack p = Point(x=10, y=20) data = p.pack() print(data.hex()) # Unpack from bytes p2 = Point(data) print(p2.x, p2.y)

Debug

Known issues

breakingIn v6.0, access to Python class attributes in struct definitions was added. Prior versions did not support this; code relying on dynamic attribute access may need updates.

fix

Ensure struct definitions use the __struct__ list format or check compatibility if using Python class attributes.

affects: <6.0

deprecatedThe use of setup.cfg is deprecated; v6.2 moved to pyproject.toml. If you were customizing build via setup.cfg, migrate to pyproject.toml.

fix

Update your build configuration to use pyproject.toml instead of setup.cfg.

affects: >=6.2

gotchaStrings in structs (e.g., 'char[10]') are packed as null-terminated byte strings. Mismatch in length or encoding can cause corruption.

fix

Define string fields with explicit length, e.g., ('name', 'char[32]'), and ensure raw bytes are encoded/decoded correctly.

affects: all

Errors

Common errors & fixes

TypeError: __struct__ must be a list of tuples

The __struct__ attribute is not properly defined as a list of (field_name, field_type) tuples.

fix

Define __struct__ as a list of tuples, e.g., __struct__ = [('x', 'int'), ('y', 'int')].

AttributeError: 'bytes' object has no attribute 'decode'

Attempting to call .decode() on a bytes object that is not a string field; or using a Python string where bytes are expected.

fix

Ensure string fields are unpacked as strings (they are automatically decoded) and binary fields are handled as bytes.

ValueError: unpack requires a buffer of 8 bytes

The buffer length does not match the expected struct size (e.g., packing two ints expects 8 bytes).

fix

Verify the buffer length matches the struct size (calculate using len(struct_instance)).

Upgrade

Version history

6.2latest on PyPI · released Jan 10, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttp://github.com/andreax79/python-cstruct ↗

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

docshttps://python-cstruct.readthedocs.io/en/latest/ ↗