# LibVMI: reading guest memory from outside the virtual machine

> LibVMI is a C library for virtual machine introspection that gives a program physical or virtual address access to a running guest, plus memory events on Xen. It is aimed at security tooling, forensics and research, with a Python binding and a Volatility address space plugin, and the KVM path still depends on a community KVM-VMI stack.

**libvmi/libvmi** — The official home of the LibVMI project is at https://github.com/libvmi/libvmi.

- Repository: https://github.com/libvmi/libvmi
- Stars: 778 · Forks: 260
- Language: C
- License: LGPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/libvmi-libvmi

## LibVMI gives a process a view of guest memory

The project describes itself simply: a virtual machine introspection library, which means it helps you access the memory of a running virtual machine. The primitives it offers are address based, physical or virtual, and symbol based, so a caller can read a region of guest memory either by raw address or by resolving a kernel symbol first.

That is a deliberately low level surface. LibVMI does not parse processes, it hands you bytes, and the layer above it is where meaning gets added. For that reason the documentation recommends the LibVMI Python bindings together with Volatility, a forensic memory analysis framework supporting Linux and Windows, and notes that the Python bindings include a Volatility address space plugin so that Volatility can be pointed at a live virtual machine rather than only at a dump.

The audience is therefore security and forensics tooling, plus researchers who want to instrument a guest. The file and snapshot access path also makes offline analysis of physical memory images possible, which the documentation calls out as helpful for debugging and forensic analysis.

## Memory events, and why they only work on Xen

Beyond reading memory, LibVMI supports memory events. You register a region of memory and get notified when it is executed, written to, or read. That is a watchpoint primitive for guest memory, and it is the feature that makes the library interesting for anti-debug and anti-tamper research, because you can observe the guest reacting rather than poll it.

There is a hard boundary: memory events require hypervisor support and are currently only available with Xen. The examples directory shows how much surface this covers, with separate programs for a breakpoint event, a cr3 event, a descriptor event, an IO event, an interrupt event, an MSR event, a single step event, a step event and a general memory event, plus breakpoint-emulate and breakpoint-recoil examples. The variety tells you this is the most explored part of the library.

For KVM there is no equivalent today, so a tool that depends on events has to run on Xen or has to change approach. That is the single most important constraint to understand before choosing this library.

## Building the library with CMake on Ubuntu

The build has a list of dependencies, and on Ubuntu they install with one command:

```bash
$ sudo apt-get install cmake flex bison libglib2.0-dev libvirt-dev libjson-c-dev libyajl-dev
```

The full list is CMake at 3.1 or newer, libtool as the generic library support script, yacc or bison optionally for reading the configuration file, lex or flex for the same purpose, glib at 2.22 or newer, libvirt at 0.8.7 or newer, and libjson-c. The optional lexer and parser tools matter if you plan to use LibVMI's own configuration file syntax rather than the Volatility IST files discussed later.

The build itself is the standard CMake dance, run in a separate build directory:

```bash
mkdir build
cd build
cmake ..
make
```

The documentation makes a useful point here: the example code works without installing LibVMI at all, so you can compile and experiment before committing to an install. The default installation prefix is /usr/local, and you can change it with a prefix argument. After a make install you may need to run ldconfig. For the full set of options, the documentation suggests the ccmake tool if it is available, and otherwise points you at the option() commands in CMakeLists.txt.

## Xen, KVM and the legacy memory access path

Xen support is described as working out of the box, with one caveat for people who install Xen from source: the Xen libraries built from source need to be in your LD_LIBRARY_PATH. The upside is that updating Xen does not force a LibVMI rebuild, because LibVMI detects the Xen version dynamically at runtime.

KVM is a different story. The KVM driver is built on the KVMi subsystem for KVM, which aims to bring an official VMI API to that hypervisor. The documentation is candid that the current state of these KVM patches is a work in progress, while arguing they are mature enough to be proposed by default instead of the previous access methods, which were the GDB stub and the tools/qemu-kvm-patch memaccess custom patches for QEMU. Using the KVM driver also requires setting up KVM-VMI beforehand, a community project hosting the API.

If you need the old KVM methods, they are behind a flag. The build directory is reused and the option is passed on the cmake command line:

```bash
cd build
cmake .. -DENABLE_KVM_LEGACY
```

On Mac OS X only file access is supported. XenServer dom0 is called out as challenging because there are no development headers and tools present; the recommended route is to compile in a separate CentOS installation using Xen development packages matching the XenServer version, then transfer the built library and tools to dom0 and run them natively.

## Volatility3 symbol tables replace the in-memory KDBG structure

A newer part of the project concerns how Windows and Linux guests are located in memory. LibVMI supports Volatility3's IST JSONs, and by using them it bypasses the in-memory KdDebuggerData (KDBG) structure that memory forensics tools normally rely on. That bypass is the point: it lets you introspect domains where the KDBG structure is corrupted, or encoded, as in the case of Windows 8 x64.

The trade-off is explicit. ISTs have to be created for each kernel version, so when the kernel is updated the JSON has to be regenerated. The documentation calls this less stable than the standard LibVMI configuration entries, and it is the reason to keep the IST generation step in your release checklist rather than treating it as a one-time setup.

One hard detail for Linux: supporting profiles generated by dwarf2json requires libjson-c version 0.15 or newer. The project also supports Rekall profiles, but the note is blunt, Rekall is no longer maintained and support for those profiles will be deprecated, so new work should target the Volatility3 IST path instead.

## The Python bindings, or writing against the C API directly

LibVMI is written in C, and the repository ships examples that show the shape of the API, including process list, module list, map addr, map symbol, cpuid, dmesg, read-disk, rwmem and dump-memory programs, and one example file named fool-patchguard. Those examples are compiled by the project and they double as the quickest way to understand the calling conventions before you write anything yourself.

If you would rather not write C, the recommendation from the project is the separate libvmi/python repository, which provides what it describes as an almost feature complete Python interface with a relatively small performance overhead. The overhead matters less than the wording, since almost feature complete implies there are gaps.

The higher-level option is Volatility, driven through the address space plugin that the Python bindings include. That combination turns LibVMI into a source of address translation for a tool that already knows how to walk process lists and kernel structures, which is the arrangement that most people building live-VM forensics end up with.

## Licence, release history and project signals

The repository is licensed under LGPL-3.0, and the licence is split across two files at the top level, COPYING and COPYING.LESSER. That split is what LGPL licensing looks like in practice, and the distinction between the two applies to how you link and redistribute, so read both files rather than assuming a single notice covers the tree.

The release history is where a buyer should slow down. The most recent tagged releases listed are v0.14.0 from 2020-12-29 and v0.12.0 from 2018-04-23, while the last push to the repository was on 2026-10-10 and the project is not archived. So development continues on master without version tags catching up, and the version number in a distribution is not a reliable guide to how current the code is.

The repository also carries a mix of build systems, with CMakeLists.txt and Makefile.am alongside configure.ac, a debian/ directory, a snapcraft.yaml, SECURITY.md and CI configuration, which tells you packaging exists for more than one distribution. The README itself is a quick start and points to the doc/ subdirectory and the online documentation for anything deeper.

## Conclusion

LibVMI fits a security engineer who needs programmatic access to guest memory on Xen, or who wants Volatility to analyse a live domain rather than a dump, and the C API is the right level if you are writing your own tooling. It is the wrong choice if you need memory events on KVM, since those are documented as Xen only, or if you need semantic process and module information without building the Python bindings and Volatility on top. Before you start, confirm that your host platform is in the supported set, Linux with file, Xen or KVM access, or Mac OS X with file access only, and read the COPYING and COPYING.LESSER files, because the LGPL-3.0 terms differ between the library and parts of it.

## FAQ

### How do I install and build LibVMI on Ubuntu?

Install the dependencies with sudo apt-get install cmake flex bison libglib2.0-dev libvirt-dev libjson-c-dev libyajl-dev, then run mkdir build, cd build, cmake .. and make. The default install prefix is /usr/local, and you may need to run ldconfig after make install.

### Does LibVMI support memory events on KVM?

Memory events require hypervisor support and are currently only available with Xen. On KVM the driver is based on the KVMi subsystem and requires the KVM-VMI project to be set up beforehand, and the legacy GDB stub and QEMU fast-memaccess methods are behind the -DENABLE_KVM_LEGACY CMake option.

### Can I use LibVMI with Volatility on a live virtual machine?

Yes. The LibVMI Python bindings include a Volatility address space plugin, which lets Volatility work against a live virtual machine instead of only a memory dump. The bindings live in the separate libvmi/python repository.

### What are Volatility3 IST JSON files used for in LibVMI?

They let LibVMI bypass the in-memory KdDebuggerData (KDBG) structure, which allows introspection of domains where that structure is corrupted or encoded, as with Windows 8 x64. An IST must be regenerated for each kernel version, and Linux profiles generated by dwarf2json require libjson-c 0.15 or newer.

### What licence does LibVMI use?

LGPL-3.0, with the terms split between the COPYING and COPYING.LESSER files at the root of the repository. Read both files, since how the library and the rest of the tree are covered differs between them.

## Sources

- [Issues](https://github.com/libvmi/libvmi/issues)
- [libvmi/libvmi on GitHub](https://github.com/libvmi/libvmi)
- [License: LGPL-3.0](https://github.com/libvmi/libvmi/blob/master/LICENSE)
- [README](https://github.com/libvmi/libvmi/blob/master/README.md)
- [Releases](https://github.com/libvmi/libvmi/releases)

---

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