22.13. virt-diff: Listing the Differences between Virtual Machine Files

The virt-diff command-line tool can be used to lists the differences between files in two virtual machines disk images. The output shows the changes to a virtual machine's disk images after it has been running. The command can also be used to show the difference between overlays.


You can use virt-diff safely on live guest virtual machines, because it only needs read-only access.
This tool finds the differences in file names, file sizes, checksums, extended attributes, file content and more between the running virtual machine and the selected image.


The virt-diff command does not check the boot loader, unused space between partitions or within file systems, or "hidden" sectors. Therefore, it is recommended that you do not use this as a security or forensics tool.
To install virt-diff, run one of the following commands:
# yum install /usr/bin/virt-diff
# yum install libguestfs-tools-c
To specify two guests, you have to use the -a or -d option for the first guest, and the -A or -D option for the second guest. For example:
$ virt-diff -a old.img -A new.img
You can also use names known to libvirt. For example:
$ virt-diff -d oldguest -D newguest
The following command options are available to use with virt-diff:

Table 22.3. virt-diff options

Command Description Example
--help Displays a brief help entry about a particular command or about the virt-diff package. For additional help, see the virt-diff man page. $ virt-diff --help
-a [file] or --add [file]
Adds the specified file, which should be a disk image from the first virtual machine. If the virtual machine has multiple block devices, you must supply all of them with separate -a options.
The format of the disk image is auto-detected. To override this and force a particular format, use the --format option.
$ virt-customize --add /dev/vms/original.img -A /dev/vms/new.img
-a [URI] or --add [URI] Adds a remote disk. The URI format is compatible with guestfish. For more information, refer to Section 22.4.2, “Adding Files with guestfish”. $ virt-diff -a rbd://example.com[:port]/pool/newdisk -A rbd://example.com[:port]/pool/olddisk
--all Same as --extra-stats --times --uids --xattrs. $ virt-diff --all
--atime By default, virt-diff ignores changes in file access times, since those are unlikely to be interesting. Use the --atime option to show access time differences. $ virt-diff --atime
-A [file] Adds the specified file or URI, which should be a disk image from the second virtual machine. $ virt-diff --add /dev/vms/original.img -A /dev/vms/new.img
-c [URI] or --connect [URI] Connects to the given URI, if using libvirt. If omitted, then it connects to the default libvirt hypervisor. If you specify guest block devices directly (virt-diff -a), then libvirt is not used at all. $ virt-diff -c qemu:///system
--csv Provides the results in a comma-separated values (CSV) format. This format can be imported easily into databases and spreadsheets. For further information, see Note. virt-diff --csv
-d [guest] or --domain [guest] Adds all the disks from the specified guest virtual machine as the first guest virtual machine. Domain UUIDs can be used instead of domain names. $ virt-diff --domain 90df2f3f-8857-5ba9-2714-7d95907b1c9e
-D [guest] Adds all the disks from the specified guest virtual machine as the second guest virtual machine. Domain UUIDs can be used instead of domain names. $ virt-diff --D 90df2f3f-8857-5ba9-2714-7d95907b1cd4
--extra-stats Displays extra statistics. $ virt-diff --extra-stats
--format or --format=[raw|qcow2] The default for the -a/-A option is to auto-detect the format of the disk image. Using this forces the disk format for -a/-A options that follow on the command line. Using --format auto switches back to auto-detection for subsequent -a options (see the -a command above). $ virt-diff --format raw -a new.img -A old.img forces raw format (no auto-detection) for new.img and old.img, but virt-diff --format raw -a new.img --format auto -a old.img forces raw format (no auto-detection) for new.img and reverts to auto-detection for old.img. If you have untrusted raw-format guest disk images, you should use this option to specify the disk format. This avoids a possible security problem with malicious guests.
-h or --human-readable Displays file sizes in human-readable format. $ virt-diff -h
Displays time fields for changed files as days before now (negative if in the future).
Note that 0 in the output means between 86,399 seconds (23 hours, 59 minutes, and 59 seconds) before now and 86,399 seconds in the future.
$ virt-diff --time-days
-v or --verbose Enables verbose messages for debugging purposes. $ virt-diff --verbose
-V or --version Displays the virt-diff version number and exits. $ virt-diff -V
-x Enables tracing of libguestfs API calls. $ virt-diff -x


The comma-separated values (CSV) format can be difficult to parse. Therefore, it is recommended that for shell scripts, you should use csvtool and for other languages, use a CSV processing library (such as Text::CSV for Perl or Python's built-in csv library). In addition, most spreadsheets and databases can import CSV directly.
For more information, including additional options, refer to libguestfs.org.