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

download PDF
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 21.3. virt-diff options
Command Description Example
--help Displays a brief help entry about a particular command or about the virt-diff utility. 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, see Section 21.4.2, “Adding Files with guestfish”. virt-diff -a rbd://[:port]/pool/newdisk -A rbd://[: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, see
Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.