PANDA on QEMU 11.1: the engine (upstream QEMU with PANDA's patch series and sources, in
engine/, built with --enable-panda), the headers libpanda-ng generates
from it, panda-ng's plugins, and pandare2, the Python interface. Everything is built by this
repository's nix flake, from this repository. There are three ways to use it:
| you want | use |
|---|---|
pip install into your own Python |
the wheel: pandare2-<v>-py3-none-manylinux_2_38_<arch>.whl |
| to build on it with nix | the flake: packages, apps, overlays.default, lib |
| plain QEMU | qemu-system-<arch>, from the flake (nix run) or the wheel (console scripts) |
Supported hosts: x86_64-linux and aarch64-linux. Targets: x86_64, i386, arm, aarch64, mips, mipsel, mips64, mips64el, ppc, ppc64, loongarch64, riscv32, riscv64.
Documentation is in docs/ (nix build .#docs builds the site): what works
and how well tested it is (docs/features.md), the Python API, every callback
and whether it fires, and the engine patches. The generated pages are checked by nix flake check;
after changing docs/features.toml, an engine header or a test's callback lists, run
nix run .#regen-docs.
python3 -m venv venv
venv/bin/pip install pandare2-*-manylinux_2_38_$(uname -m).whl
venv/bin/python -c 'from pandare2 import Panda; Panda(arch="x86_64", mem="256M")'
venv/bin/qemu-system-riscv64 -versionThe wheel needs glibc 2.38 or newer (Debian 13, Ubuntu 24.04, Fedora 39, RHEL 10 and later) and
nothing else from the host: the engine (libpanda-<arch>-softmmu.so), the plugins, QEMU's
firmware, the qemu-system-<arch> launcher, and every library they use apart from glibc
(glib, pixman, libslirp, libstdc++, ...) are inside it. It works with any Python 3 the host has
(pandare2's bindings are cffi ABI mode, so the wheel is py3-none). It is about 120 MB.
Build it with nix build .#wheel (the wheel is in result/). How it's made:
enginePortable: the engine built withnix/glibc-compat/termios-compat.clinked in. nix's glibc is 2.42, whosecfsetispeed/cfsetospeedhave new symbol versions (speed_t became the baud rate itself). Those were the only symbols newer than GLIBC_2.38 anywhere in the engine, plugins or their libraries; the shim translates the rate to the old code and calls the original version, which every glibc has. The engine is otherwise the same as.#engine.pip wheelbuilds the pure-Python pandare2 (with the cffi bindings generated from that engine's headers).tools/wheel/repair.pyadds the engine, plugins, firmware and launcher underpandare2/data/, and does whatauditwheel repairdoes: it copies each needed library except glibc's intopandare2.libs/under a hashed name, rewrites DT_NEEDED and RUNPATH ($ORIGIN), gives the launcher the standard ELF interpreter, fails if anything still points into/nix/storeor needs a glibc newer than 2.38, and tags the wheelmanylinux_2_<highest GLIBC_2.N needed>_<arch>. (auditwheel itself won't bundle libstdc++, and nix's is newer than the hosts'.) Libraries the wheel ships itself (engine, plugins) are never copied again, every RUNPATH is$ORIGIN:$ORIGIN/<to pandare2.libs>, and no soname is bundled twice.- Licenses: the wheel contains GPL-2.0-only QEMU and LGPL/BSD/MIT/... libraries, not just the
MIT Python package.
pandare2-*.dist-info/licenses/holds each component's license files (taken from its upstream source) andSOURCES.txt, which says where each one's source is (the panda-ng commit and engine/'s patch series for the engine, the panda-ng commit, each library's upstream tarball). METADATA has the combinedLicense-Expression. The list of libraries and their licenses iswheelThirdPartyin flake.nix; repair.py fails if it bundles a library from a package not on it.
pandare2 looks for its engine, plugins and firmware in pandare2/data/, then in the flake's
(which builds them into pandare2), so the same source works from the wheel and from nix.
PANDA_LIB, PANDA_PLUGIN_DIR and Panda(libpanda_path=, plugin_path=, biospath=) point it
elsewhere, e.g. at a build tree.
Older hosts (glibc < 2.38: Ubuntu 22.04, Debian 12) would need the engine built in a manylinux container instead; pip refuses the wheel there rather than failing at import.
Packages (nix build .#<name>), for x86_64-linux and aarch64-linux:
| package | what |
|---|---|
engine |
QEMU + PANDA: lib/libpanda-<arch>-softmmu.so, include/panda-ng/, share/qemu/, QEMU's tools |
engine-x86_64 |
one target, for iterating on the build |
engine-src |
the patched QEMU tree the engine builds from (tarball + engine/patches + engine/src) |
plugins (default) |
lib/panda/plugins/libpanda-<plugin>_<arch>-softmmu.so |
pandare2 |
the Python package, wired to this engine and these plugins |
python |
nix's Python with pandare2 |
qemu |
bin/qemu-system-<arch> for every target (+ qemu-img, qemu-io, qemu-nbd) |
qemu-system-<arch> |
one of those |
plugin-sdk |
headers for building a plugin outside this tree |
dist |
engine + plugins + python under one prefix (panda-python, panda-system-<arch>) |
deb |
dist's closure as a .deb (bundles nix's Python; any Debian/Ubuntu) |
wheel |
the pip wheel |
Apps: nix run .#qemu-system-<arch> -- <qemu args>, nix run .#python -- script.py.
examples/consumer is a complete one: it builds an out-of-tree C
plugin against the engine, runs a pandare2 script that loads it, and re-exports qemu.
{
inputs.panda-ng.url = "github:panda-re/panda-ng/workspace/panda-next";
inputs.nixpkgs.follows = "panda-ng/nixpkgs"; # share panda-ng's builds
outputs = { nixpkgs, panda-ng, ... }:
let
system = "x86_64-linux";
pkgs = import nixpkgs { inherit system; overlays = [ panda-ng.overlays.default ]; };
pn = panda-ng.lib.${system};
in {
packages.${system} = {
# overlay: pkgs.pandaNext.<package>, and pandare2 in every Python package set
python = pkgs.python3.withPackages (ps: [ ps.pandare2 ]);
qemu = pkgs.pandaNext.qemu;
# lib: build a plugin against the engine's headers
myplugin = pn.buildPandaPlugin { pname = "myplugin"; src = ./plugin; };
};
};
}overlays.defaultaddspandaNext(everything in the table above, plus the helpers below) built with the consumer's nixpkgs, andpandare2to every Python package set throughpythonPackagesExtensions.lib.<system>: this flake'sengine,plugins,pluginDir,pluginSdk,qemu,pandare2,python, and:buildPandaPlugin { pname, src, targets ? [ "x86_64" "aarch64" "riscv64" ], buildInputs, extraCFlags }: compiles every*.cinsrcintolib/panda/plugins/libpanda-<pname>_<arch>-softmmu.so. It builds againstengine's generated headers; such a plugin also works with the wheel's engine (enginePortable) only while both come from the same engine source revision.pluginDirWith [ drv ... ]: a plugin directory with panda-ng's plugins and yours, forPANDA_PLUGIN_DIRorPanda(plugin_path=...).mkEngine { targets, portable }: an engine for other targets.
lib.mkPandaNext pkgs: the whole set for any nixpkgs (what the overlay calls).
Checks: nix flake check applies the engine's series (engine-src) and runs -version and
-machine help on every qemu-system-<arch>. nix develop .#engine is the engine's toolchain.
For working on the engine, the plugins or pandare2, tools/dev/dev.sh build --targets x86_64
keeps an incremental build of all three in .dev/, and .dev/bin/python3 runs pandare2 from
python/core on it (docs/guides/development.md).
engine/README.md: the layout (base.json, patches/<version>/, src/),
working on the series (import, export, verify), the CI gates, rebasing onto a new QEMU release,
and what came from rehosting/qemu_builder, where the engine lived until October 2026. Engine
work (the series, the overlay in engine/src/, its tests) happens here now; nothing is taken
from qemu_builder any more.
nix run .#qemu-system-aarch64 -- -M virt -cpu max -bios edk2-aarch64-code.fd -m 1G \
-display none -serial stdio -drive file=disk.qcow2,if=virtio
venv/bin/qemu-system-x86_64 -version # from the wheelThe engine is built as a library, libpanda-<arch>-softmmu.so (the object pandare2 loads), and
qemu-system-<arch> is launcher/panda-qemu.c: a few kB that
dlopens that library (RTLD_GLOBAL) and calls its main(). It picks the arch from its name
(qemu-system-<arch>, panda-system-<arch>, or panda-qemu <arch> ...), finds the library in
../lib (or $PANDA_QEMU_LIBDIR), and QEMU finds its firmware in ../share/qemu relative to
the launcher. Why a launcher rather than the engine's own bin/qemu-system-* executables or
linking those with --export-dynamic:
- it runs exactly the code pandare2 runs, and everything the library exports (the PANDA API) is
visible to plugins QEMU loads; the engine's executables export only
qemu_plugin_*(80 symbols, nopanda_*), so a PANDA plugin can't load in them; --export-dynamicwould fix the exports, but each executable is still a second ~25 MB copy of its target (308 MB for 13), which the wheel and the .deb would have to carry next to the libraries; the launcher costs nothing.
The engine still installs its own bin/qemu-system-* (the engine and dist outputs keep
them for now).
panda-ng's own code is under the MIT license (LICENSE). Code that comes from
elsewhere keeps its license. REUSE.toml gives the license of every file, and
the texts are in LICENSES/. reuse lint checks them.
- MIT: panda-ng's own code (pandare2's new modules, tools, tests, build files, the launcher).
- GPL-2.0-or-later: the engine (
engine/: patches to QEMU and the overlay linked into it), and the pandare2 modules and headers taken from classic PANDA (panda-re/panda). - GPL-2.0-only: classic PANDA's plugins and other files whose header says "GNU GPL, version 2";
the bindings generated from the engine's headers (
rust/panda-bindings/src/autogen/).
- Each patch in
engine/patches/<version>/has aSPDX-License-Identifier:trailer (the licenses of the QEMU files it changes) and anOrigin:trailer (upstream QEMU, classic PANDA, penguin, ...);ORIGINS.mdthere lists them.
- Vendored: nlohmann/json (MIT), pycparser's fake libc headers (BSD-3-Clause), Volatility's syscall tables (GPL-2.0-or-later), Linux kernel excerpts (GPL-2.0-only).
The engine as built is QEMU and so GPL-2.0-only as a whole (QEMU's LICENSE). The wheel bundles
the engine, the plugins and third-party libraries; its METADATA has the combined
License-Expression, and pandare2-*.dist-info/licenses/ has every component's license files.