virt-sparsify

Create a sparsified compressed image without snapshots from an unsparsified one

$ virt-sparsify --compress [path/to/image.qcow2] [path/to/image_new.qcow2]

$ virt-sparsify --in-place [path/to/image.img]

virt-sparsify [OPTION...] INFILE OUTFILE
virt-sparsify [OPTION...] --in-place FILE

--convert
    Converts the disk image to a specified format (e.g., qcow2, raw) during sparsification.

--in-place
    Modifies the disk image directly without creating a new output file. This option is experimental and requires sufficient temporary free space on the same filesystem.

--compress
    Compresses the output image if the target format supports compression (e.g., qcow2).

--check-zero
    Controls whether to explicitly check for all-zero blocks for sparsification. Setting this to 'false' can make the process faster but potentially less thorough.

--format
    Specifies the format of the input disk image. Useful when autodetection fails or for clarity.

--tmpdir
    Sets a specific temporary directory for sparse data and other operational files instead of the default.

-q, --quiet
    Suppresses progress messages, showing only errors or critical information.

-v, --verbose
    Enables verbose output, showing more details about the sparsification process, including debug information.

virt-sparsify is a utility designed to optimize virtual machine disk images by converting unused blocks within the image into 'holes' or sparse regions. This process, known as sparsification, allows the underlying host filesystem to reclaim storage space that was allocated but not actively used by the guest operating system. It's particularly useful after large files have been deleted inside a guest VM, or when converting a thickly provisioned disk image to a thinly provisioned format. virt-sparsify can operate on various disk image formats and can also perform format conversions (e.g., from raw to qcow2), optionally compressing the output. The tool accesses the guest filesystem directly using libguestfs to identify free blocks, ensuring a safe and efficient sparsification without needing the guest to be running. It typically operates by reading the input and writing a new, sparse output file, though an experimental in-place option is available.

virt-sparsify operates by accessing the guest filesystem and typically creating a new sparse copy of the disk image. The experimental --in-place option, while convenient, requires a substantial amount of temporary free space (up to twice the original image size) on the same filesystem for its operation and should be used with caution, ideally after backing up the original image. The input disk image should have a clean filesystem (e.g., no pending fsck issues). This tool reduces the physical size on disk, not the logical size as seen by the guest operating system. It relies on the correct functioning of libguestfs, which in turn depends on qemu and other virtualization components.

The command typically returns 0 on success. A non-zero exit status indicates an error, which can be useful for scripting and automation to determine if the sparsification process failed. Specific error codes might provide more granular information about the nature of the failure.

virt-sparsify is a core component of the libguestfs project, a suite of tools developed primarily by Red Hat since 2008. It was created to address the critical need for efficient offline management of virtual machine disk images, particularly for space optimization. Its design leverages libguestfs's ability to safely access and modify guest filesystems, making it a reliable solution for sparsifying disk images across various virtualization platforms and formats. The tool has evolved to include features like in-place sparsification and format conversion, reflecting ongoing development in virtual disk management.

virt-df(1), virt-ls(1), virt-resize(1), virt-sysprep(1), qemu-img(1), guestfish(1)