kaitai_struct_formats: a library of binary formats written once, parsed anywhere

One .ksy file, a parser in any target language

This repository is a library of ready-made binary file format descriptions written in the Kaitai Struct language, with the `.ksy` extension. The idea it builds on is that the layout of a binary format should be described once, in a declarative form, and then compiled into a parser for whichever language you actually write in.

The documentation lists three ways the library is useful. The first is exploring a format's internals, by loading a `.ksy` file and a target binary in the Web IDE or in the visualizer and seeing what is inside. The second is using the formats as a production ready parsing library, compiled with the Kaitai Struct compiler into source code in any supported target programming language. The third is using them as a starting point for learning how Kaitai Struct is applied to real formats.

That middle use is the one that matters for adoption decisions. The point of a shared format description is not that it is a script you run once, it is that the same description produces a typed parser in your language, with the structure of the file expressed as data rather than as hand written offset arithmetic.

The primary language of the repository is recorded as Kaitai Struct, and the homepage is formats.kaitai.io. There are no GitHub releases, and the repository is not archived, with the last push on 2026-10-17.

The category directories are a map of what is covered

The top level listing is the fastest way to understand the scope, because the directories are organised by domain rather than alphabetically by project name.

There is `3d/` for three dimensional formats, `cad/` for computer aided design, `common/` for the shared building blocks, `database/` for database files, `executable/` for executable formats, `filesystem/` for filesystem images, `firmware/` for firmware, `font/` for fonts, `game/` for game data, `geospatial/` for geospatial formats, `hardware/` for hardware definitions, `image/` for images, `log/` for log formats, `machine_code/` for machine code, `macos/` for macOS specific formats, `media/` for media containers, `network/` for network protocols and captures, `scientific/` for scientific data, `security/` for security related containers, `serialization/` for serialisation formats and `windows/` for Windows specific formats. There is also an `archive/` directory, an `_build/` directory, and the usual repository files.

The `common/` and `serialization/` directories carry a special weight, because a format that is a member of a family usually references shared building blocks. A codec description that needs to read a container will often pull in a type defined elsewhere, which is why the library is organised as a set of reusable parts rather than a set of standalone scripts.

For a reader trying to work out whether this library covers their problem, the category list is the answer. If you are reading a camera firmware, the answer is probably in `firmware/`. If you are reversing a container format, it is in `media/` or `archive/`. The `network/` category is worth singling out because network formats are where hand written parsing goes wrong most often, since a protocol is a state machine and a length field can mean different things depending on where you are in it.

The format gallery is the better front door

The documentation points you at the Kaitai Struct format gallery at formats.kaitai.io before you browse the repository itself, and that is good advice for a repository with this many entries.

The gallery is an HTML rendition of the whole repository, with block diagrams, the code compiled for all possible target languages, usage examples and instructions. For someone deciding whether a format is covered, a diagram of the structure and a snippet of generated code in your language of choice is a much faster filter than a directory listing.

The alternative front door is the Web IDE at ide.kaitai.io, and the documentation notes that the library of formats comes pre-loaded with it. That is the tool for the first use case, exploring what is inside a file. You point it at a `.ksy` and a binary, and it shows you the structure. The same description that produces the diagram produces the parser, so what you learn in the IDE is what you get in code.

Both routes exist because the repository answers two different questions. The gallery answers which formats exist and how they are shaped. The IDE answers what a specific file contains. Between them, a new user can go from a file on disk to a working parser without reading the compiler's documentation first.

The documentation also points at CONTRIBUTING.md for people who want to add a format, and at the separate Kaitai Struct compiler repository for the build step that turns a `.ksy` into source.

Each format carries its own licence tag

The licensing section is unusual and deserves attention. The repository contains work of many individuals, and each `.ksy` is licensed separately. The permission for any given format is in its `meta/license` tag and in the comments inside every `.ksy` file.

The reason for the per file arrangement is stated directly: the Kaitai team claims no copyright over other people's contributions. Somebody who wrote a description of their own file format, or a format they reverse engineered, keeps their own terms on it, and the repository is a place to share rather than a single licensed corpus.

That has consequences for anyone building on this. A parser compiled from a `.ksy` inherits the terms attached to that file, not the terms of the repository, and there is no single licence you can read once and rely on. If you are shipping a product that includes a compiled parser, you have to check the tag on the specific format you used, and formats differ.

The top level listing also includes a `.gitmodules` file, which is a hint that some of the content is pulled in as submodules rather than kept in the tree directly, and an `_build/` directory that is part of the build. Both are reasons to check the actual repository state rather than assume the listing tells the whole story.

The licence field for the repository itself is recorded as unknown, which is consistent with the per file arrangement rather than an oversight.

Where a shared description is the wrong tool

Three limits are worth naming, and they are inherent to the approach rather than gaps in the library.

The first is that a `.ksy` file encodes somebody's model of a format, and that model can be wrong or incomplete. If the description mis-parses a length field, the generated parser mis-parses the file in exactly the same way, and it will do so confidently. The description is only as good as the reverse engineering behind it, and the library gives you no way to tell a well researched format from a hastily written one. Reading the format's documentation alongside the description is not optional.

The second is coverage. A format library is by definition behind the state of the art, and for formats that move quickly, a description written for one version of a file will not fit the next. The library also cannot describe a format nobody has reverse engineered yet, and for proprietary or undocumented formats there is nothing to compile at all.

The third is that a generated parser is generated code, and it looks like it. The value proposition of the approach is that you get a structured, typed view of a file rather than a pile of offset arithmetic, and the cost is that a large body of generated code sits in your build. If your need is one field out of one file, a few lines of struct unpacking will beat a compiled parser.

The alternative to name is a hand written parser for your specific use, or a dedicated library for that format if one exists. The difference in approach is that a hand written parser encodes what you need and nothing else, and you own every line of it, while a compiled Kaitai parser encodes the whole format as described by someone else and is regenerated when the description changes. For a one off extraction, the hand written route is less work. For a tool that reads a format repeatedly, or that must read it correctly across many variants, the shared description wins.

Editorial conclusion

Use kaitai_struct_formats when you need to read a binary format that already has a .ksy description and you want a parser in your own language rather than a one-off script. Do not reach for it when the format is undocumented, since a .ksy file encodes someone else's understanding of the layout and inherits its errors, and check the per format licence before shipping a parser built from it. Verify first which of the category directories actually contains the format you need, and whether the meta/license tag in that .ksy file permits your use, since each file is licensed separately and the Kaitai team claims no copyright over other people's contributions.

Frequently asked questions

Official sources

1. Issues
2. kaitai-io/kaitai_struct_formats on GitHub
3. Project website
4. README