hermes-dec: disassembling and decompiling Hermes bytecode

What the tool does, and where the bytecode lives

hermes-dec is a reverse-engineering tool which can be used for disassembling and decompiling React Native files compiled into the Hermes VM bytecode, the HBC format. The primary language is Python, the licence is AGPL-3.0-or-later, the last push was on 2026-10-15, and the releases are 0.1.8, 0.1.7 and 0.1.6, with the release notes themselves informative since they read as fixes for memory overflow in certain cases, decoding for bytecode version 97 and above, and a bump of the release number for the Arch Linux upstream. The finding that a bundle is Hermes bytecode is one command, because the `file` utility recognises the format:

$ file assets/index.android.bundle
assets/index.android.bundle: Hermes JavaScript bytecode, version 84

The path in an Android application is `assets/index.android.bundle`, and the documentation is careful to note that on non-Hermes setups the same file usually contains minified or Webpacked JavaScript instead, which changes what you need.

Why Hermes is the default on Android only

The background section gives the history that makes this tool relevant. The Hermes VM for React Native was announced by Facebook on 12 July 2019, with the initial release being version 0.1.0 at bytecode version 59, and the GitHub tags 0.0.1 to 0.0.3 corresponding to a pre-public release. Hermes has been the default compilation target for React Native on Android only since React Native 0.70, released on 5 September 2022. Before that, and since React Native 0.60.2, it was an opt-in feature, and Hermes for iOS is supported since version 0.64 of React Native, released on 12 March 2021. The asymmetry is why an Android-first tool makes sense. On iOS the JavaScript is not compiled to Hermes by default, so the bundle you find there is more often readable JavaScript, and on older Android applications built before 2022 the same is true. The documentation also notes that React Native is used by a wide variety of significant mobile applications.

Installing it, and the four ways to do so

The application itself only relies on the Python 3.x standard library for now, which is a notable property for a tool that has to parse a binary format. There are four installation routes:

# With Snap (recommended with Ubuntu):
sudo snap install hermes-dec
# Note: the commands to use will then be:
# - hermes-dec.hbc-disassembler
# - hermes-dec.hbc-file-parser
# - hermes-dec.hbc-decompiler

# With AUR (recommended with Archlinux):
yay -S hermes-dec

# With uv (all distributions):
sudo snap install --classic astral-uv
uv tool install hermes-dec

# With pipx (all distributions):
pipx install hermes-dec

The Snap route renames the commands with a `hermes-dec.` prefix, which is a small thing to trip over. The uv route installs the classic Astral uv tool first and then the package as a uv tool, and pipx is the general-purpose equivalent. The pyproject file adds the detail that a pipx or uv install also brings three commands that the README does not list, `hermes-dec-regen-pydefs`, `hermes-dec-regen-pydefs-regexp` and `hermes-dec-regen-html`, which are the maintenance utilities for regenerating the opcode definitions.

The three utilities, and what each one gives you

The workflow is three steps with three separate commands, and each produces a different artifact. The file parser decodes most of the file headers, and the documentation warns that its output may not be stable over time, so it is a diagnostic tool rather than something to depend on:

hbc-file-parser assets/index.android.bundle

The disassembler emits Hermes assembly, and it takes an output path, or you leave out the second parameter to send the disassembled content to standard output:

hbc-disassembler assets/index.android.bundle /tmp/my_output_file.hasm

The decompiler produces pseudo-code, and the documentation is honest about the limits, saying it is not valid JavaScript yet as it does not retranscribe loop and conditional structures:

hbc-decompiler assets/index.android.bundle /tmp/my_output_file.js

That last caveat is the one to keep in mind when reading decompiled output. You are reading a control-flow graph flattened into statements, which is genuinely useful for understanding what a function does, and useless for pasting back into an interpreter or for reading as if it were the original source.

Getting the bundle out of the application

The extraction step is a file format detail that trips people up. An .APK file is a renamed .ZIP archive, so you extract it with any unzipping tool:

$ 7z x my_application.apk
$ cd my_application

Then you check the type of the bundle with `file`, and the output tells you which of the three utilities applies. If you did not install the tool system-wide, the source can be cloned instead:

$ git clone [email protected]:P1sec/hermes-dec.git
$ cd hermes-dec/

with the same utilities found at the root. The three executables are also visible in the pyproject file as console scripts, which is where the internal module layout shows through, with `hermes_dec.decompilation.hbc_decompiler:main`, `hermes_dec.disassembly.hbc_disassembler:main` and `hermes_dec.parsers.hbc_file_parser:main`, so the code is organised by stage rather than by command.

The opcode tables, and the Hermes documentation beside it

There is auto-generated documentation for the Hermes VM opcodes at the project's p1sec.github.io site, described as a useful tool to understand the generated assembly code. That page is the bridge between the tool and the VM it targets, because a disassembly is only meaningful if you can look up what each instruction does. The Hermes project itself is published as an open source project under the BSD licence and includes various design documents in Markdown, readable on GitHub and on the Facebook React documentation site. So the reference material this tool depends on is public and well documented, which is what makes a third-party decompiler possible at all. The README's background section links all of it, and the classification in the pyproject file reflects the audience, with the tool marked as intended for developers and for science and research, and filed under the disassembler and security topics.

Where it stops, and the licence to keep in mind

The scope is deliberately narrow. It reads Hermes bytecode, and it does not decompile the whole application, does not rebuild an installable package, and does not produce something you could ship as source. The pseudo-code output is not valid JavaScript, and the header parser is explicitly unstable. So the realistic use is investigative, answering a question about what an application does, rather than lifting a proprietary application into a form you can maintain, and the AGPL-3.0-or-later licence reflects that this is a research tool rather than a foundation for a commercial reimplementation. The dependency group is thin too, with clang 18.1.8 and pytest 9.0.3 for development, and the ruff configuration with a line length of 79 and single quotes as the style, so the project is small, readable and easy to contribute to.

Editorial conclusion

Adopt hermes-dec if you need to read the Hermes bytecode inside a React Native application and have no other way to do it, since the file parser, the disassembler and the decompiler cover the three levels of detail. Skip it if you only have a minified JavaScript bundle, because the documentation is explicit that a non-Hermes build contains ordinary JavaScript that a normal tool will read. Before you rely on the output, note that the decompiler produces pseudo-code that does not retranscribe loop and conditional structures, and that the file parser output may not be stable over time, so treat the disassembly as the reliable artifact and the decompilation as a reading aid.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. P1sec/hermes-dec on GitHub
4. README
5. Releases