# Dyninst: a research library for instrumenting a running binary

> Dyninst is the binary instrumentation library from the Paradyn project, a C++ and C system for parsing an executable, rewriting its code, and running the modified program under your control. What makes it readable is the honesty of its known issues list, which names the platforms and modes that do not work, and a manual per component that is built from LaTeX by the same CMake build that builds the library.

**dyninst/dyninst** — DyninstAPI: Tools for binary instrumentation, analysis, and modification.

- Repository: https://github.com/dyninst/dyninst
- Website: http://www.paradyn.org
- Stars: 840 · Forks: 180
- Language: C
- License: LGPL-2.1
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/dyninst-dyninst

## A library for parsing, rewriting and running binaries

Dyninst is described as tools for binary instrumentation, analysis and modification, and the project page is the Paradyn one, so this is a long-running academic project rather than a product.

The idea is to load an executable, work out what its code and data actually are, and then change the program while it runs. That means four capabilities, and the repository layout is organised around them.

The parsing side is a set of components: a parse API for reading the executable format, with a directory for the ELF format and another for DWARF debugging information, plus a symbol table API and a lighter symbol handling directory. The analysis side is the instruction API, which gives you the decoded form of instructions, and the dataflow API, which is where the framework's analysis machinery lives. The modification side is the patch API, and the process control API is how you start, stop and inspect the process you have instrumented. The stack walking directory provides the ability to walk the stack of the running program, and there is a separate directory for system call interception, a separate one for a C level interface, and one for the runtime support library that the instrumented process needs.

The two language interfaces are worth noting, because a project that offers a C API and a C++ API is making a statement about who uses it. The C++ API is the original one, and the C interface exists so that the library can be used from a language that is not C++.

The licence is LGPL-2.1, the code is C and C++, the default branch is master, and the last push was on 2026-10-22, so the repository is very much alive even though the release history has not moved in a while.

## The documentation is LaTeX manuals built by the same build

The documentation section is short, and the design decision in it is worth more than a paragraph of feature description.

Each component has a manual. The manuals are written in LaTeX and built to PDF by the CMake build, so the same command that compiles the library also compiles the documentation, and the documentation cannot drift away from the code it describes the way a separately maintained wiki does.

The released PDFs for version 13.0.0 are in the repository, and the README says they are a snapshot, so for anything newer you should build from source. That is an honest statement about what a release artefact is: a point-in-time copy of the manuals that matches a point-in-time copy of the code.

The directory for the documentation has its own readme that explains three things, the directory layout, how to build the manuals, and how to add one. The third item is the important one for a project in this shape, because a manual per component only works if adding a component means writing a manual, and the instructions for that have to be somewhere discoverable.

The readme also carries an OpenSSF scorecard badge, which is a sign of a project that takes its supply chain practices seriously even where the code itself is twenty years old in conception.

## Three ways to build it, and a wiki when they fail

The build section offers three routes, and they are aimed at different readers.

The shortest is Spack, and the command is a single line:

```bash
spack install dyninst
```

The second is the plain CMake route, which is what you want if you are integrating the library into something else. You configure with CMake, pointing at the install prefix:

```bash
cmake /path/to/dyninst/source -DCMAKE_INSTALL_PREFIX=/path/to/installation
```

Then you build and install in parallel:

```bash
make install -jN
```

The third route is containers, and the README explains the two purposes they serve. One is development of Dyninst itself, where a container lets you change the code and rebuild quickly without disturbing your host. The other is development of your own tools on top of Dyninst, where a container already has the library and its dependencies ready to go. The instructions for using and building the images locally are in the docker directory, and the note says links to the published images will be added when they are pushed to the package registries associated with the project.

The fallback is the wiki, which the README points to for detailed instructions, with a separate page for building problems and the issue tracker for everything else. That is a sensible structure for a project with this many platforms, because the build matrix is where the complexity lives and the wiki is where it can be documented without bloating the readme.

## The known issues list is the most useful page in the repository

Most libraries bury their limitations. Dyninst has a section called known issues that reads like an engineering notebook, and it should be the first thing you read.

Windows is where the gaps are. Windows 64-bit mode is not supported, and Windows rewriter mode is not supported either, so on Windows the library can observe a program but cannot rewrite it, and on 64-bit it does not work at all. The stack walker is described as fragile on Windows. There is also a note in the readme that known issues should have open issues associated with them, which is a policy about how the list stays honest.

On Linux the limitations are narrower and more specific. The rewriter mode for 32-bit statically linked binaries does not support binaries with .plt, .rel or .rela sections. Exceptions raised in relocated code will not be caught, which follows from the mechanism, since the code has been moved to somewhere the unwinder does not expect. And a callback at thread or process exit that stops the process will deadlock when a segmentation fault occurs on a thread other than the main thread, which is the kind of bug that only shows up under load in production.

The last one is the sharpest. Parsing a binary with no functions, typically a single object file, will crash at the point where the parsed code object is destroyed, so the failure happens at teardown rather than at parse time, which makes it a miserable bug to diagnose.

For a library whose job is to take over a program that was not written to be taken over, this list is exactly what an adopter needs, and having it in the readme rather than in a tracker is a sign of a project that has been maintained by people who had to support other people's crashes.

## ARMv8 is experimental, and the release history has stalled

Two things about the state of the project are worth knowing before you plan around it.

The first is that support for ARMv8, the 64-bit ARM architecture, is described as experimental and incomplete for dynamic instrumentation, with a link to a wiki page tracking the currently supported functionality. That page is the thing to read if your target is a modern ARM server or an Apple silicon machine, because the difference between experimental and complete is the difference between a research prototype and something you can depend on.

The second is the gap between the releases and the repository activity. The listed releases are v12.2.1 from November 2022, v12.3.0 from February 2023 and v13.0.0 from March 2024. The last push is only a day old, so the code is being worked on continuously while the version history has not moved for more than two years.

That combination, an active repository with a stalled release train, is a real consideration for an adopter. It usually means one of two things. Either the maintainers are working towards a release that has not landed yet, in which case the fixes you need may be in the branch but not in a tag, or the work is maintenance rather than feature development, in which case the current release is old but stable.

Either way, the practical instruction is the same, and the readme gives it about documentation: build from source for anything newer than the last published manuals. If you need a reproducible artefact, you are building a v13.0.0 with your own patches, and that is a decision to make explicitly rather than by accident.

## Conclusion

Adopt Dyninst if you need to observe or modify a running program at the machine code level, for analysis, testing or research, and you are prepared to work within a library whose supported platforms are spelled out rather than assumed. Do not adopt it if you need Windows support on 64-bit, or the rewriter mode there, because both are listed as unsupported. Before you commit, read the known issues list in full, check the ARMv8 status page if your target is 64-bit ARM, since that support is experimental and incomplete, and remember that the last tagged release is v13.0.0 from March 2024 even though the repository is being worked on now, so you are pinning a release that predates the current code.

## FAQ

### What is Dyninst used for?

It is a set of tools for binary instrumentation, analysis and modification, from the Paradyn project. The repository is organised around the parsing of executables, the analysis of their instructions and dataflow, the patching of code, process control, stack walking and system call interception, with both a C++ API and a C interface.

### How do I build Dyninst?

With Spack, using a single install command, or with CMake by configuring the source directory with an install prefix and then building and installing in parallel. The README also points at Docker containers for developing Dyninst itself or for building your own tools on top of it, and at the wiki for detailed instructions when those do not work.

### Which platforms does Dyninst not support?

Windows 64-bit mode and Windows rewriter mode are both listed as not yet supported, and the stack walker is described as fragile on Windows. On Linux, the rewriter mode for 32-bit statically linked binaries does not support binaries with .plt, .rel or .rela sections, and exceptions in relocated code are not caught.

### Is 64-bit ARM support ready in Dyninst?

Not for dynamic instrumentation, which the README describes as experimental and incomplete, with a wiki page tracking the currently supported functionality. That page is the reference to check before planning an ARM target.

### How is the Dyninst documentation produced?

Each component has a manual written in LaTeX and built to PDF by the CMake build, so the documentation is compiled alongside the library. The PDFs released for version 13.0.0 are a snapshot, and the README advises building from source for anything newer, with the documentation directory explaining the layout and how to add a manual.

## Sources

- [dyninst/dyninst on GitHub](https://github.com/dyninst/dyninst)
- [License: LGPL-2.1](https://github.com/dyninst/dyninst/blob/master/LICENSE)
- [Project website](http://www.paradyn.org)
- [README](https://github.com/dyninst/dyninst/blob/master/README.md)
- [Releases](https://github.com/dyninst/dyninst/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dyninst-dyninst