---
id: kaitaistruct
version: "0.11"
license: MIT
license_treatment: permissive
maintenance: active
---

# kaitaistruct — Kaitai Struct declarative parser generator for binary data: runtime library for Python

License: permissive · Maintenance: active · Downloads: 8.5M/mo

## What it is and what it does

Kaitai Struct is a declarative approach to binary data parsing. Instead of writing custom code to read and unpack binary structures, you describe the format in a YAML-based .ksy file, compile it with the Kaitai Struct compiler, and use this runtime library to instantiate and navigate the parsed data. The library implements the Kaitai Struct API for Python, providing stream-based access to binary data with automatic field extraction and type handling.

It is language-agnostic—the same .ksy description can be compiled to many target languages—but this package handles only the Python runtime side. You provide the compiled parser class, and the library handles the low-level stream reading. It supports Python 2.7 and Python 3.4 through 3.13, with a single runtime dependency (enum34 for older Python versions).

Use it for:

- Parse custom binary file formats (e.g., image headers, audio metadata) by defining the structure once in .ksy and reusing across languages.
- Decode network packet formats by describing the protocol structure declaratively and letting the runtime extract fields automatically.
- Reverse-engineer or document binary file formats by writing a .ksy description that serves as both specification and working parser.
- Build cross-language tools where the same binary format description compiles to multiple languages, reducing duplication.
- Unpack structured binary data from embedded systems or legacy protocols without manual bit-shifting and byte-order handling.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Kaitai Struct provides a Python runtime library for parsing binary data structures described in a declarative YAML-based format, enabling you to read and unpack binary file formats and network packets without writing custom parsing code.

Yes, if you are already using Kaitai Struct to describe binary formats. The runtime is lightweight, permissively licensed, and actively maintained. Install it only after you have a compiled .ksy parser class ready; the library alone does not parse anything without that upstream compilation step. Not relevant if you are hand-writing binary parsers or using a different declarative format.

## Install

pip install kaitaistruct
uv add kaitaistruct
poetry add kaitaistruct

## Installing kaitaistruct

Before you install: Low install friction with a single lightweight dependency (enum34). The package is actively maintained with recent commits, though it has been 340 days since the last release. Supports a wide range of Python versions from 2.7 through 3.13.

License in practice: MIT license is permissive, allowing free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

pip install kaitaistruct

from kaitaistruct import KaitaiStream

# Use with a compiled .ksy parser class
with open('file.bin', 'rb') as f:
    stream = KaitaiStream(f)
    data = YourCompiledParser(stream)

You must first compile a .ksy format description file into a Python parser class using the Kaitai Struct compiler; this library provides only the runtime API, not the compiler itself.

Verify before relying:

- Whether the package works with PyPy as claimed in classifiers, or if there are known limitations.
- Current maintenance cadence and likelihood of future releases given the 340-day gap since last release.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 8.5M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

binary data parser, declarative binary format, kaitai struct runtime, binary file format parser, network packet parsing, structured data unpacking, ksy format parser, binary-parsing, declarative-format, cross-language

[View on SkillFed](https://skillfed.io/packages/kaitaistruct) · [View on PyPI](https://pypi.org/project/kaitaistruct/)