kaitai_struct_compiler turns one .ksy file into a parser in twelve languages, and the licence stops at the compiler

One description of a format, many parsers

Kaitai Struct is a declarative language for describing binary data structures, whether they live in files or in memory: file formats and network packet formats are the examples the documentation gives. A format is written once, in a .ksy file, and the compiler turns it into source files in one of the supported programming languages. The generated modules contain a parser that reads the described structure from a file or a stream and exposes it through an API that is meant to be easy to read.

That is the entire pitch, and it is a pitch about maintenance rather than about parsing. Binary format work is usually a per language tax: someone writes a PNG chunk reader in C, another writes a container parser in Go, and a third writes a protocol decoder in Python, and the three implementations drift apart. The .ksy file is the single place where the format is described, and the compiler is what keeps the implementations in step.

The cost of that arrangement is that you now have a build step in your build. The specification is a source artefact, and changing the meaning of a field means editing the .ksy and recompiling, not editing a parser in twelve languages.

The project describes itself as the official reference compiler for Kaitai Struct, which places it in a slightly unusual position. The language has a specification, a user guide and a community of format descriptions, and this repository is the implementation that the project treats as canonical rather than as one of several competing tools.

Twelve target languages from one compiler

The description of the project lists the output languages in one line, which is the clearest statement of its scope: C++, C#, .NET, Go, Java, JavaScript, Lua, Nim, PHP, Perl, Python, Ruby and Rust.

Looking at that list tells you what the project is optimising for. The older targets, C++, C#, Java, Python, Ruby, PHP, Perl and Lua, are the ones a file format parser most often has to exist in. The newer ones, Go, Nim and Rust, matter for tools that read untrusted binary input at speed or in a sandboxed environment.

Generated code is not the same as idiomatic code in each language. The documentation describes the output as giving access to the parsed structure through a nice, easy to comprehend API, but the exact shape of that API, how the runtime library is packaged alongside it, and how much of the surrounding ecosystem each target supports are details you will only find by compiling a small example in the language you care about.

Two practical consequences follow. The first is that the generated parser is code you inherit and maintain, like any other dependency, and it needs to be regenerated when the .ksy changes. The second is that supporting a new language is a compiler change, not a per project decision, so the set of targets only grows when someone contributes the work.

For an organisation that already maintains parsers in several of these languages, the compiler is the thing that turns that maintenance into a one time cost per format.

A Scala codebase split into shared, JVM and JavaScript builds

The compiler is written in Scala, and the repository layout shows how a single codebase serves two very different targets.

The top level contains shared/, jvm/ and js/ directories alongside build.sbt and project/, which is the standard shape of a Scala cross build. The shared directory holds the parts of the compiler that do not depend on the host runtime, the jvm directory holds the JVM specific code, and the js directory holds the Scala.js side. The build definition is build.sbt, and there is a setup_env.sh script at the root for preparing an environment.

The js target is the interesting one. Because the compiler itself runs in a browser through Scala.js, the tool that reads a .ksy file can be used from a web page without a JVM. That is what makes an online Kaitai editor or an in-browser build pipeline possible, and it also means the compiler binary is distributed through npm alongside the JVM build.

Other files at the root give a sense of the release process. RELEASE_NOTES.md tracks changes between versions, and publish_deb_to_cloudsmith.sh indicates that a Debian package is published to a Cloudsmith repository, which is what makes the tool installable on Linux distributions without building from source.

The .idea/ directory at the root suggests the project is developed in IntelliJ IDEA, and the .editorconfig file points to shared formatting rules for contributors.

Getting the compiler: Maven Central, npm and the developer memo

The distribution channels are visible from the badges in the README, and they are the practical route to a working install.

The JVM build is published to Maven Central under the artifact coordinate io.kaitai/kaitai-struct-compiler_2.13, with the Scala 2.13 suffix in the artifact name. The JavaScript build is published to npm as kaitai-struct-compiler, with separate latest and next channels, so a project can pin to the stable channel or track the pre-release channel deliberately.

The project overview does not print the commands for pulling the compiler down and running it. Instead it points you to the downloads page at kaitai.io for installation, to the user guide at doc.kaitai.io for the .ksy language and general usage patterns, and to the developer memo at doc.kaitai.io for how to build the compiler, run the test suite and join the development. Those three documents are where the actual commands live, so read them before assuming a particular invocation.

Two other practical notes. Compiler issues are tracked in a separate repository, kaitai-io/kaitai_struct, which is the main project repository rather than this one. And the Debian package path means Linux users may not need either Maven or npm at all.

If you are evaluating this, the cheapest first step is to take a format you already know well, write the .ksy for it, compile it to a single target language, and read the generated parser before you generate a second one.

GPLv3 covers the compiler, not your formats and not the output

The licensing section is unusually careful, and it is worth reading before you use this in a commercial codebase.

The compiler itself is copyright the Kaitai Project from 2015 to 2026 and is distributed under the GNU General Public License version 3, with the standard warranty disclaimer. The licensing section is explicit that these clauses apply to the compiler only, and not to the .ksy input files you supply during a normal compilation, nor to the compiler's output files, which constitute the normal usage process and where you obviously keep copyright to both.

That is the key practical point. If you write a .ksy description of a file format and compile it, the generated parser is yours, and the licence of the tool that produced it does not travel with it.

The dependencies are also listed with their licences: scopt under MIT, fastparse under MIT and snakeyaml under Apache 2.0. Two parts of the codebase carry separate notices. Portions of the compiler are loosely based on pythonparse from FastParse by Li Haoyi, under an MIT style permission notice, and other portions are based on scala/xml/Utility.scala from Scala XML, under the BSD style licence with the EPFL and Lightbend copyrights. The Scala XML notice includes the usual clause about not using the names of the copyright holders to endorse derived products.

For a company, the practical reading is that the tool can be run on your machines to produce your own code without infecting your codebase with copyleft. That is a statement about the licence terms as documented here, not legal advice, and anyone deploying the compiler as a service should get their own review.

Release cadence and the reference compiler role

The published versions are 0.11 from 2025-09-07, 0.10 from 2022-07-08 and 0.9 from 2021-05-02. The repository is not archived, and the last push was on 2026-10-20.

The gap between 0.10 and 0.11 is close to three years, and the gap before that was over a year. That is a slow release cadence for a tool that a build pipeline depends on, and it is the practical cost of the model: a compiler change affects every generated parser in every language, so changes are batched and released carefully.

Two implications for an adopter. If you pin the compiler, you are pinning something that moves infrequently, which is good for reproducibility and bad for picking up fixes. If you follow the pre-release npm channel, you get changes earlier and take on the risk of a reference compiler changing output shape under you.

The version numbers themselves are worth noting. A compiler at 0.11 is pre 1.0 by the usual convention, and the language it implements is still evolving, so a .ksy file written for one version may need adjustment for another.

What keeps the project relevant despite the slow tags is its role. It is described as the official reference compiler, which means the specification, the user guide and the community format library are all built around what this code does. The formats described in .ksy files are the durable artefact, and they remain readable as long as the specification does not change. If you are picking a format to model, that is the part worth committing to, rather than a specific compiler build.

Editorial conclusion

Use kaitai_struct_compiler when you have to read the same binary format from several languages, or when you want a format specification that a colleague can review without reading your parser. Do not reach for it to parse a format you will only ever read once in one language, where a hand written parser will be smaller and faster to change. Before adopting, write one .ksy file for a format you already know well, compile it for one language, and compare the generated code against a hand written parser for the same input, then check the target language on the Kaitai website before committing to twelve outputs.

Frequently asked questions

Official sources

1. kaitai-io/kaitai_struct_compiler on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases