ZathuraDbg: an emulation based debugger for learning assembly

An emulator drives the debugger

ZathuraDbg is a GUI open source assembly emulator-based debugger, described as being mainly for reverse engineering and for learning assembly.

The mechanism is what distinguishes it from a native debugger. Instead of attaching to a running process and asking the operating system for register state, an emulator based debugger runs the code inside an emulated CPU that the tool controls completely. That is why the project is built on three well known engines: Unicorn for the emulation itself, Capstone for disassembly, and the Keystone Engine for assembling.

Those three choices are the practical argument for the tool. A native debugger for x86_64 is easy to find and a native debugger for Thumbv7m is much harder to come by. An emulator based debugger gets its instruction set support from the emulator library, so covering several architectures is a configuration question rather than a porting project. The project says it is under development and aims to support all major architectures.

The current list of supported architectures, given in the readme FAQ, is Intel x86_64, ARM 32 bit, Thumbv7m and AArch64. That is a useful spread for embedded work, since Thumbv7m and AArch64 are what you will meet on Cortex-M and ARM64 hardware, and x86_64 covers the case where you are reversing something that runs on your own machine.

The project tells you it is in beta

The readme does not oversell. It states that ZathuraDbg is still in beta, so you should expect major changes in the framework used or the UI.

That warning is more specific than the usual beta disclaimer, and it is worth taking literally in two separate ways. A change of framework means the dependency stack could be replaced, and a change of the UI means anything you build on top of the tool, a workflow, a script, a set of keybindings, may not survive an update.

The release history explains the shape of the project. Version 0.5.0-beta on 2025-04-22 was tagged with the note that the proper replacement of Unicorn with Icicle is complete, which is a large internal change to an emulator based debugger, since the emulation engine is the foundation. Version 1.0 followed on 2025-05-21 as the ZathuraDbg 1.0 stable release, and version 1.1 came on 2026-06-21. The last push was on 2026-06-21 as well.

So the project has a stable release line and a relatively recent one, and the beta warning is about the shape of the thing rather than about brokenness. That is a reasonable way to run a tool that is still finding its architecture, and it is also the reason to keep your usage of it simple.

Installing on Linux and Windows

On Linux the install path is an AppImage from the releases page. The steps are short:

2. Execute `chmod +x ZathuraDbg-*AppImage`
3. Run the program with `./ZathuraDbg-*AppImage`

The first step is to download the AppImage from the releases page, and the two commands above make it executable and start it. There is one system requirement to be aware of: you need glibc 2.38 or later installed.

That glibc requirement is the sort of detail that catches people out on a distribution with an older base, since an AppImage bundles the application but not the C library it links against. On a machine with an older glibc the binary will refuse to start, and the fix is a newer userland rather than a different build, since no alternative Linux artefact is offered.

On Windows the route is simpler: download and run the installer from the releases page. The credits name NSG650 for the Windows build, so the Windows installer is contributed work rather than something produced by the maintainer.

For anyone who wants to build it themselves, the readme points to COMPILE.md for the instructions, and the repository also has a WASM.md at the root, which suggests a web assembly target is at least being considered or documented.

What the FAQ admits is not finished

The FAQ at the end of the readme is the most useful part of the documentation, because it answers the three questions that decide whether the tool fits your work.

On debugging binaries, the answer is that ZathuraDbg can load ELF binaries into the local emulator experimentally, and that full process-level binary debugging, dynamic loader emulation and OS API coverage are still under development. That is a precise statement of the boundary. Loading an ELF file and running its instructions in the emulator is different from running a program as the operating system would run it, with a loader, a heap and a kernel underneath.

On syscalls and OS level APIs, the answer is that common syscalls are planned to be implemented in the future. So a program that calls into the operating system will hit a wall, and everything above the syscall boundary is a different project.

On architectures, the answer is the list of Intel x86_64, ARM 32 bit, Thumbv7m and AArch64.

Taken together, the tool is at its best on self-contained code, firmware, shellcode, algorithms and the kind of snippet you find in a disassembly, which is exactly what an assembly course and a lot of reverse engineering work is made of.

Adding an architecture means reading ARCHITECTURE.md

The contributing section is where the design becomes visible.

To implement a new architecture to work with ZathuraDbg, the readme says to read ARCHITECTURE.md, and for general contributions to read CONTRIBUTING.md. Questions can go to the maintainers or into the issue tracker, and there is a Discord server linked from the badges.

The existence of a dedicated architecture document, and the release note about replacing Unicorn with Icicle, together describe the extension model. An architecture is not just a decoder: it is the emulator configuration, the register set, the memory map, the disassembler mode and the way the UI presents them. A document that walks through that list is what makes a third-party architecture contribution realistic rather than theoretical.

The credits are also informative about the stack. mrexodia is credited for help with Unicorn related issues, WerWolv for help with ImGui, which tells you the user interface is built on Dear ImGui, and NSG650 for the Windows build.

For getting started there is a video tutorial linked from the readme, which is the sensible first step for a project whose value depends on you understanding how to drive the emulator through the interface.

Repository layout, licence and version file

The repository is small and easy to read at the top level. There is `src` for the source, `vendor` for the vendored dependencies, `assets` for the interface resources, and `packaging` for the installers, which on Windows comes from a contributed build. Alongside those are the documentation files already mentioned, `ARCHITECTURE.md`, `COMPILE.md`, `CONTRIBUTING.md` and `WASM.md`, plus a `VERSION` file.

A `VERSION` file at the root is a small sign of a project that builds its version string from a single source, which is what you want when the same number has to appear in the installer, the about box and the release tag.

The licence is GPL-3.0, with the licence file at the root of the repository. For a debugging tool that people run on their own machines, the copyleft terms matter mostly if you redistribute a modified build, but they also mean that if you want to fold ZathuraDbg into a larger commercial product you have a decision to make.

The project website is zathura.dev, the repository is ZathuraDbg/ZathuraDbg on GitHub, and the default branch is `master`.

Editorial conclusion

ZathuraDbg suits a learner or reverse engineer who wants to single step assembly in a graphical debugger across several architectures, rather than in a terminal debugger tied to one platform. It is a poor fit if you need to debug a real running process, because process-level debugging, dynamic loader emulation and OS API coverage are all still under development, and a poor fit if you need a stable interface, since the project warns that the framework and the UI may change. Before you rely on it, read the FAQ answers in the repository about binary loading and syscalls, and check that the release you download matches the architectures you actually need.

Frequently asked questions

Official sources

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