Hachoir: browsing a binary file the way you browse a directory

A file as a tree of fields, down to one bit

Hachoir is a Python library to view and edit a binary stream field by field, and the project puts the idea plainly: it allows you to browse any binary stream just like you browse directories and files. A file is split into a tree of fields where the smallest field is just one bit, and the field types include integers, strings, bits, padding types and floats. That granularity is the whole design. A binary format usually has a container level with a header, then length-prefixed or offset tables, then records with a repeated structure, and a hex dump gives you none of that. Hachoir reconstructs the structure as a tree of typed fields with offsets and sizes, and you can walk it interactively. The name is the joke that explains the design: Hachoir is the French word for a meat grinder, a mincer used by butchers to divide meat into long tubes, and Hachoir is used by computer butchers to divide binary files into fields.

The command line tools are the entry point for most people

Five console tools are built on the parsers, and between them they cover the tasks people actually reach for a binary tool to do. hachoir-grep finds a text pattern in a binary file. hachoir-metadata gets metadata from binary files. hachoir-strip modifies a file to remove metadata, which is the one you want before uploading a file that still carries a camera serial number or a software version. hachoir-urwid displays the content of a binary file in text mode, using a text user interface rather than a scroll of hex. And the package also registers a subfile tool that pulls a subfile out of a larger one, plus a wxWidgets graphical front end as a GUI script. The set of entry points is declared explicitly in the packaging, and the two kinds of script are separated: console scripts for the five text tools and a GUI script for the wx one.

What the packaging says about the audience and the scope

The package classifiers are a compact statement of what the project is for. The development status is Production/Stable, the environments listed are Console with Curses support and Plugins, and the intended audiences are Developers and Education. The licence classifier is the GNU General Public License. The topic list is long and revealing: Multimedia, Information Analysis, Disassemblers, Interpreters, Libraries for Python Modules, Filesystems, Text Processing and Utilities. Put together, that is a library for people who want to look inside binary data, mostly for analysis rather than for editing, and a fair number of those people are learning rather than shipping. The project is written for Python 3.7 or newer, and the documentation is hosted on readthedocs with the source, bugs and install instructions together in one place.

Installing it, and what the tooling around it looks like

The project points to its own installation instructions page for the details, and the package is on PyPI. The development side is well equipped for a library of this size: there is a GitHub Actions build workflow, a tox.ini for running the test suite across environments, a runtests.py script, a benchmark.sh for measuring performance, and a tools/ directory. The release process is written out as comments at the top of the packaging file, which is unusually candid about the mechanics. Preparing a release means checking that the version matches in the package init and the documentation config, editing the release date in the changelog, running the tests in parallel with tox, then pushing and watching the Actions status. Releasing means tagging, building an sdist and a wheel, and uploading with twine. Afterwards the version is bumped to the next one in the same two places, which tells you the version number lives in exactly two files.

Ruff configuration as a picture of the code

The project uses ruff for linting, and the configuration is worth a look because the ignore list is effectively a statement of the code's known rough edges. It disables the warning about mutable data structures for argument defaults, and the one about lru_cache use leading to memory leaks, which matters for a library that caches parsed metadata. It disables the rule about function definitions not binding the loop variable, and the blind exception catch, and the two timezone warnings about naive datetimes, and the bare except. It also disables the import sorting rule, several pylint refactor rules including a redundant return, the rule about explicitly returning None, the mutable class attribute default, the unused noqa directive, the try-except-pass pattern, two simplification rules about nested ifs and a condition check, the recommendation to use a context manager when opening files, and the percent-format modernisation rule. A tool that reads metadata from untrusted files has to catch broadly, and the configuration shows that being done deliberately rather than by accident.

The maintenance signal, and what to make of it

There is a tension in the project page that you will notice immediately. The documentation carries a No Maintenance Intended badge from unmaintained.tech, which is a deliberate statement that the author is not taking on maintenance obligations. At the same time, the last push to the repository was on 2026-10-14, only a week before the current date, so the code is being worked on. The reconciliation is that the code is being kept working and current without a long-term support commitment. For a user, that means the library does what it says today and that a given version will keep working, but there is no promise that a future format request will be met, no guarantee that a compatibility break will be handled with a deprecation cycle, and no security response process. That is a perfectly reasonable arrangement for a tool like this, and it is a different arrangement from a supported dependency.

Where Hachoir is the wrong tool

Two limits are worth being clear about. The first is that Hachoir is a browser, not an authority. The tree of fields it shows you is the result of a parser written by someone reasoning about a format, and formats are full of regions where two implementations disagree. When you are writing a program that must interoperate with another implementation, a format-specific parser with a specification in front of you is the right tool, and a general field browser is the wrong one. The second is scope. Hachoir parses many formats, but it does not parse all of them, and the field boundaries it reports for a format with optional or version-dependent structure can be a best guess. Its strengths are the opposite case, where you have a file you do not recognise and want to know what is in it, or where you want to remove metadata without writing code.

Editorial conclusion

Hachoir fits an analyst who has a binary file and no idea what is inside it, since the tree-of-fields model lets you descend from a whole file to a single bit without writing a parser, and it fits a developer who needs to strip metadata from files before sharing them, since hachoir-strip exists for exactly that. It does not fit a project that needs a maintained, structured parser for a specific format, because the project page carries a No Maintenance Intended badge even though the last push to the repository was on 2026-10-14, so the code is alive but nobody has committed to supporting it. Before you build on it, read the parsers directory rather than assuming a format is covered, check the GPL v2 licence terms for your use, and remember that the tool is a browser, so the field boundaries it shows you are the tool's opinion about the format rather than a guarantee of the format's own structure.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. Project website
4. README
5. vstinner/hachoir on GitHub