virtnbdbackup: online VM backups built on dirty bitmaps and NBD

The problem: backups that need the machine switched off

The About section states the problem the project exists to solve. Existing backup solutions or scripts for libvirt and kvm usually depend on the external snapshot feature to create backups, and sometimes even require shutting down or pausing the virtual machine.

For a production VM that is a hard constraint, and the whole point of the project is to avoid it. Recent additions to both the libvirt and qemu projects introduced new capabilities that allow creating online, full and incremental backups, using so called dirty bitmaps, or changed block tracking. virtnbdbackup uses these features to create online full and incremental or differential backups.

The mechanism is worth understanding because it explains both the power and the limits of the tool. A dirty bitmap is a per-disk record of which blocks have changed since a given point in time. QEMU can maintain that record natively, without a snapshot, and the backup tool then asks for only the changed blocks since the last full backup and stitches them into a chain. That is what makes an incremental backup possible while the guest is running and writing.

The cost is that the guest's storage stack has to support it. The README is direct about the prerequisite: you require a libvirt and qemu version that supports the incremental backup features. Since libvirt v7.6.0 and qemu 6.1 the required features are enabled by default and are considered production ready.

The audience is therefore administrators of libvirt managed KVM infrastructure, and the topics list confirms the shape of the tool: backup, cbt, differential, incremental, kvm, libvirt, nbd, nbd-client, qemu and virtualization.

Three commands, and the difference between backup and map

The project ships a small family of programs rather than a single tool, and the split is the interesting part.

`virtnbdbackup` creates the online full, incremental or differential backups. `virtnbdrestore` can be used to reconstruct the complete image from the thin provisioned backups. And `virtnbdmap` can be used to map a thin provisioned backup image into a block device on the fly, for easy single file restore or even instant boot from a backup image.

That third program is the one that changes how you think about recovery. Instead of restoring a whole disk to get at one file, you map the backup chain as a block device and mount the filesystem inside it, and the single file comes out without writing a full image first. The README has a section on single file restore and instant recovery, and the project description calls the tool agentless, which refers to the fact that no agent has to be installed inside the guest for the recovery path.

The packaging confirms the four-program layout. The setup script lists `scripts=["virtnbdbackup", "virtnbdrestore", "virtnbdmap", "virtnbd-nbdkit-plugin"]`, and there is a fourth entry, the nbdkit plugin, which is what lets the NBD server expose the backup chain to the kernel as a block device.

The internals section of the README describes the pieces you would want to understand before trusting it: output target plugins, the backup format, extents, the backup I/O and performance notes about scratch files, and a debugging section. The output target plugin mechanism is what makes the tool extensible, and the repository ships two example plugins under `examples/`, one for an FTP output target and one generic output target plugin.

There is a companion project for the case libvirt does not manage the guest. For backing up standalone qemu virtual machines not managed by libvirt, the README points to qmpbackup.

Installing the tool: packages, virtualenv, Docker

The README's table of contents lists five installation routes, which tells you the project expects to be deployed in more than one kind of environment.

There is a Python package route, an RPM package route for the RHEL, CentOS Stream, Alma and Rocky Linux platforms, a Debian package route, a virtualenv route, and Docker images. The `docker/` directory in the repository and the `build.yml` workflow badge for package builds line up with that list.

The Python dependencies are short and they tell you what the tool talks to:

libvirt-python>=6.0.0
tqdm
lz4>=2.1.2
lxml
paramiko
typing_extensions
colorlog

`libvirt-python` is the client for the hypervisor, `paramiko` is the SSH library, which is how the remote backup and remote restore features reach a host, `lz4` is the compression library, `lxml` handles the XML in libvirt's domain and storage descriptions, `tqdm` provides the progress bars, and `colorlog` colours the log output.

The setup script reads its `install_requires` straight from `requirements.txt` at build time rather than duplicating the list, and it takes the version from the package's own `__version__` attribute:

name="virtnbdbackup",
version=libvirtnbdbackup.__version__,

One more packaging detail is worth noting. The packages are found with `find_packages(exclude=("docs", "tests", "env"))`, and the repository top level contains a `venv/` directory, which suggests the virtualenv route is the one the maintainer uses day to day.

The prerequisites section also splits by platform, with separate notes for libvirt versions 7.6.0 and below on Debian Bullseye and Ubuntu 20.x, for RHEL family systems on version 8.5 and below versus 8.6 and above, and a section on environment dependencies. That split is a practical warning: the packaging expectations differ per platform and per libvirt generation.

What the feature set actually covers

The table of contents is long, and reading it is the fastest way to understand the scope, because every entry is a documented capability.

On the backup side there are local full and incremental backups, backing up offline virtual domains, application consistent backups, rotating backups, excluding disks, estimating differential and incremental backup size, a backup threshold, backup concurrency, compression, and a set of remote backup options: QEMU sessions, NBD with TLS, using a separate network for data transfer, and piping data to other hosts. There is also handling of kernel and initrd plus additional files, and extraction of Windows Bitlocker recovery keys.

On the restore side there is dumping backup information, verifying created backups, complete restore, restoring only specific disks, point in time recovery, restoring with a modified virtual machine config, remote restore, and restore with compression enabled, followed by a section on post restore steps and considerations.

Then there is the transient virtual machines material about checkpoint persistency on clusters, supported hypervisors with sections on Ovirt, RHEV or OLVM, and OpenNebula, an authentication section, and the internals section described above.

Two features stand out as the ones that change how the tool is used in practice. Application consistent backups matter because a live filesystem backup is only useful if the data inside it is consistent, and point in time recovery matters because it turns a set of incremental backups into a timeline rather than a single restore point.

The authentication section is also worth noticing in a tool of this kind, because the remote backup path moves data between hosts and the plugin path exposes a block device to the kernel, and both are surfaces where authentication decisions have to be made deliberately.

The FAQ is where the real operational knowledge lives

The last part of the README is a long FAQ, and the entries are more informative than the feature list because they describe the failure modes.

The first is the one every user hits. The thin provisioned backups are bigger than the original qcow images. The FAQ has a section with that exact title, which tells you the project considers it a known characteristic of the format rather than a bug, and it is the same structural reason that a sparse or thin image expands when it is materialised.

Then there are four distinct backup failures, each with its own cause. Backup fails with Cannot store dirty bitmaps in qcow2 v2 files. Backup fails with unable to execute QEMU command 'transaction': Bitmap already exists. Backup fails with Bitmap inconsistency detected: please cleanup checkpoints using virsh and execute new full backup. And backup fails with Error during checkpoint removal: internal error: bitmap not found in backing chain of.

Three of those four are dirty bitmap bookkeeping failures, which is exactly where you would expect a tool that depends on QEMU's changed block tracking to be fragile. The first is a format constraint, the second and the fourth are state left behind by an interrupted run, and the third is the recovery instruction, which is to clean up checkpoints with virsh and start a new full backup.

There is also a failure where the virtual machine does not support required backup features, please adjust virtual machine configuration, which is the disk type and backing store constraint, and one where backup fails with Timed out during operation: cannot acquire state change lock, which is a concurrency problem between the backup tool and other libvirt operations on the same domain.

Then two operational questions. High memory usage during backup, and fstrim and incremental backup sizes, which is the interaction between discarding unused blocks and the size of the incremental chain.

And the entry that matters most, listed as its own section: Test your backups! The README does not merely suggest it, it puts it in the table of contents.

Where virtnbdbackup is the wrong tool

The first wrong-tool case is a standalone qemu guest with no libvirt. The project says so directly and points to qmpbackup for that case, because virtnbdbackup's model is the libvirt domain: it asks libvirt for the disks, it uses libvirt's checkpoint and transaction machinery to manage dirty bitmaps, and it restores into a libvirt domain.

The second is older storage. The whole design rests on dirty bitmaps being available, which the README ties to libvirt 7.6.0 and qemu 6.1 as the versions where the features are enabled by default and considered production ready. On a qcow2 v2 image, the FAQ documents a hard failure, and a disk that does not support the required backup features produces the message asking you to adjust the virtual machine configuration.

The third is a database or filesystem that needs quiescing. An online backup of a running database is a copy of whatever was on disk at the moment the blocks were read, and the application consistent backup feature exists precisely because that is not always usable. If your workload cannot tolerate the app's own quiesce mechanism, this is the wrong tool.

The fourth is an environment where the tool cannot have the access it needs. The failure Failed to bind socket to /var/tmp/virtnbdbackup.XX: Permission denied is a permissions problem on the host, and the NBD and remote features mean the tool needs to open sockets and, in the remote case, authenticate over SSH to another machine.

The alternative worth naming is taking a snapshot and copying it, which is what the existing solutions do and what the project describes itself as replacing. The difference in approach is that a snapshot and copy is a point-in-time copy of the whole disk, it needs either a snapshot chain to manage or a pause, and every run costs the full size. Dirty bitmaps make the incremental case cheap and keep the guest running, and the price is the dependency on the storage stack, on QEMU's own bitmap bookkeeping, and on the recovery procedures the FAQ has to document. Which trade is right depends on whether your guests can be paused and whether your storage can do changed block tracking.

Maintenance, licence and the shape of the project

The project is not archived, and the last push was on 2026-10-15. The release history is dense: v2.53 on 2026-09-07, v2.52 on 2026-09-02 and v2.51 on 2026-09-01, three releases in a week. Those tags are named Version 2.53 and so on, and a changelog sits at the top level of the tree, so the release history is a plain version sequence rather than a calendar scheme.

The repository layout shows a mature project with a lot of surface area. There is the `libvirtnbdbackup/` Python package, the `virtnbdbackup/`, `virtnbdrestore/` and `virtnbdmap/` directories for the commands, the `virtnbd-nbdkit-plugin` directory for the nbdkit plugin, `man/` for the manual pages, `docker/` for the images, `examples/` for the plugins, `scripts/`, `t/` for tests, `docs/`, a `setup.py` alongside a `setup.cfg`, a `requirements.txt`, a `SECURITY.md`, and a `Changelog` file.

The presence of `man/` directories and the `stdeb.cfg` file for Debian packaging tells you this is a tool meant to be installed system-wide and run from a shell by an administrator, not imported as a library. The `SECURITY.md` file is also worth noting, since the tool has a remote path that moves data over the network.

The licence is GPL-3.0, with a `LICENSE` file in the tree. For a system administration tool that is the expected choice, and it is worth being explicit that the licences of the components it drives, libvirt and qemu, are separate matters from this one.

The one thing to check before you plan around it is the version floor. Three releases in the first week of September 2026 and a push in mid-October indicate active work on a codebase that has been running for a long time, and the version sequence in the 2.5x range means you should read the changelog for the release you intend to pin rather than assuming the newest is the safest.

Editorial conclusion

Adopt virtnbdbackup when you run libvirt managed KVM guests on storage that supports dirty bitmaps, when you need online backups because pausing or shutting down a production VM is not acceptable, and when you want incremental and differential backups rather than a full copy each time. Do not adopt it for standalone qemu guests without libvirt, since the project points those users to qmpbackup, and do not adopt it on a libvirt older than 7.6.0 with qemu older than 6.1, where the required features were not enabled by default. Before you start, confirm the qcow format version in use, because the FAQ documents a failure with dirty bitmaps in qcow2 v2 files, and check the disk type, since the tool works on thin provisioned RAW disks and direct attached volumes, and the FAQ notes that the thin provisioned backups can end up bigger than the original qcow images.

Frequently asked questions

Official sources

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