BinDiff: comparing two disassemblies instead of two binaries

Matching functions rather than comparing bytes

BinDiff describes itself as an open source comparison tool for binary files, aimed at vulnerability researchers and engineers who need to find differences and similarities in disassembled code quickly. The unit of comparison is the function, matched across two disassemblies of two builds, which is a different problem from diffing the binaries themselves. Two compilers, two optimization levels or a small vendor patch produce byte streams with almost no useful correspondence, while the function graph of the two builds still lines up.

The listed use cases are specific about what that buys you. You can compare binary files across x86, MIPS, ARM, PowerPC and other architectures supported by the disassemblers you already use. You can identify identical and similar functions in different binaries. You can port function names, comments and local names from one disassembly to the other, which is how an analyst's naming work is carried forward instead of redone. And you can detect and highlight changes between two variants of the same function.

That third item is the one analysts tend to underestimate. The README frames it as a way to retain analysis results and enable knowledge transfer among binary analysts, and it is a genuinely different tool from the differ itself: symbol and comment portability is a database operation on a result file, not a graph computation.

Configuring and building the native engine

The native side is cmake and Ninja, and the configuration step from the README is short:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release

Building, testing and installing are three more commands, and the test step is worth keeping because the repository ships fixtures for exercising the core engine:

cmake --build build --config Release
(cd build; ctest --build-config Release --output-on-failure)
cmake --install build --config Release

Binaries land in build. The dependency list is longer than the commands, and it is where a build actually gets interesting. BinExport 12 is required, described as the companion plugin to BinDiff that also contains a lot of shared code. Boost 1.83.0 or higher, with a partial copy shipped inside BinExport and used automatically. CMake 3.14 or newer, Ninja for speedy builds, Git 1.8 or newer. On compilers, GCC 15 or a recent Clang on Linux and macOS, and Visual Studio 2022 with the Windows 11 SDK on Windows.

Several more dependencies are downloaded during the build rather than installed by hand: Abseil, GoogleTest, Protocol Buffers at 3.14, SQLite3, plus the Binary Ninja SDK and the IDA SDK. The IDA SDK being a build dependency is the detail that surprises people, and there is a switch for it, described below.

The yFiles licence is the real gate on the interface

Building the Java interface requires the commercial yFiles graph visualisation library, and the README does not soften this: it calls the library immensely powerful and not easily replaceable, and it is required for both graph display and graph layout. This is the single fact to check first when planning a source build, because a yFiles licence is a purchase decision, not a configuration step.

Assuming you hold a licence, the build uses Gradle 6.x and Java 11 LTS, and you point the build at your copy through an environment variable:

export YFILES_DIR=<path/to/yfiles_2.17>
cd java
gradle shadowJar

On Windows the README gives the equivalent as setting YFILES_DIR with a set command. The result is a self-contained bindiff-ui-all.jar in ui/build/libs under the java subdirectory, runnable with the standard java -jar command. Note the version in the path: the README says BinDiff still uses the older 2.x branch of yFiles, so a current yFiles licence does not automatically satisfy the build.

If you only want the differ and the matching engine, the IDA dependency can be dropped at configure time:

cmake -S . -B build/out -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DBINEXPORT_ENABLE_IDAPRO=OFF

That path is the sensible starting point for anyone evaluating the matching behaviour without committing to a Java interface build.

What the codemap directories each own

The README's codemap section is a compact map of the codebase, and the repository tree backs it up. cmake holds the cmake build files that declare external dependencies. fixtures is a collection of test files used to exercise the BinDiff core engine, which is how the matching algorithms are tested without needing real malware samples. ida holds the IDA Pro integration. java holds the visual diff user interface and its utility library. match holds the matching algorithms for the core engine. packaging holds the sources for the installation packages, and tools holds helper executables shipped with the product.

The repository root is where the engine itself lives, and the file names describe the pipeline. differ.cc and differ_test.cc are the top level comparison entry point. flow_graph.cc handles the per function graph, call_graph.cc the call relationships between functions, and change_classifier.cc the part that decides what kind of change a function represents, which is what turns a similarity score into a meaningful label. prime_signature.cc computes the matching signature used to find candidate pairs. Then there is the persistence layer, database_writer.cc, reader.cc, log_writer.cc, groundtruth_writer.cc and sqlite.cc, with config.cc, fixed_points.cc, instruction.cc and graph_util.h as supporting pieces, and bindiff_config.proto alongside it for configuration.

Having fixtures at the level of test data rather than UI-level tests is a reasonable sign about where this project's risk sits. A differ is only as trustworthy as its matching, and that is the part covered here.

BinExport decides your workflow more than BinDiff does

A practical point that the README makes in a single sentence: BinDiff relies on a separate disassembler, and out of the box it ships with support for IDA Pro, Binary Ninja and Ghidra. The disassemblers page lists the supported configurations. In practice that means your workflow is two steps, export a BinExport database from each binary with your disassembler of choice, then run BinDiff over the two databases.

That has a consequence for anyone coming from a single-binary tool. If your existing disassembler cannot produce a BinExport file, the differ cannot consume it, and the set of usable inputs is decided upstream of BinDiff entirely. It also means the version of your disassembler matters, which is what the release notes keep touching.

The two releases on record illustrate that. BinDiff 7, published in September 2023, added support for IDA Pro 7.6 SP1 while keeping 7.4 as the minimum, included the BinExport Ghidra extension in the package while still calling it beta and requiring manual export, included a Binary Ninja plugin also marked beta, started shipping function names inside .BinDiff result files to make post-processing easier, and reported exports from IDA Pro and Binary Ninja up to 30 percent faster than in BinDiff 6. Five days later came BinDiff 8, the open source snapshot, raising the IDA Pro minimum to 8.0 and supporting 8.3.

Alternatives, downstream users and where the manual stops

The README is direct about the neighbours in this problem space. Diaphora is named as an advanced program diffing tool implementing many of the same ideas, and TurboDiff as a now-defunct IDA Pro plugin. Naming a dead project alongside a live one is a useful signal about how the field consolidated.

On the downstream side there is VxSig, a tool to automatically generate AV byte signatures from sets of similar binaries, which is a concrete demonstration that the matching output of this kind of differ is useful as an input to something else. The intellectual lineage is also cited: the graph-based comparison work of Thomas Dullien and Rolf Rolles from SSTIC 2005, and Halvar Flake's structural comparison paper from DIMVA 2004. If you want the reasoning rather than the tool, those two papers are where it is.

Documentation is the weaker part, and the README admits it twice. More detailed build instructions will be added at a later date, including ready-made Dockerfiles and scripts for building installation packages, and only a subset of the existing manual is mirrored into the docs directory. The full manual lives on the zynamics site linked from the README, and that URL plus the repository homepage point at the same domain. If you want to avoid a source build altogether, the README's answer is the releases page, which carries prebuilt installation packages.

Contributions go through CONTRIBUTING.md, the licence is Apache, and the repository's last push was on 2026-09-18.

Editorial conclusion

BinDiff is the right tool when you have two builds of the same program and need to know what changed at the function level, which is the normal shape of vendor patch analysis and of tracking how a binary evolves across releases. It is the wrong tool for source-to-source comparison, where a diff of text beats any graph matching, and the open source build has a hard external dependency: yFiles, a commercial library you must license before the Java interface will build. Before committing to a build, check whether you can obtain a yFiles licence, and if you only need the matching engine, configure with -DBINEXPORT_ENABLE_IDAPRO=OFF and skip the interface. The subset of the manual in docs/README.md and the disassembler support page are the two documents that settle most setup questions before you start.

Frequently asked questions

Official sources

1. google/bindiff on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases