virt-xml

List all the suboptions for a specific option

$ virt-xml --[option]=?

$ virt-xml --disk=? --network=? --boot=?

$ virt-xml [domain] --edit --[option] [suboption]=[new_value]

$ virt-xml [domain] --edit --metadata description="[new_description]"

$ virt-xml [domain] --edit --boot bootmenu=[on|off]

$ virt-xml [domain] --update --add-device --hostdev [bus].[device]

virt-xml [domain] [action-option...] [generic-option...]
virt-xml --build-xml [xml-modifier...] [generic-option...]

--add-device type[,option=value...]
    Add a new device to the domain. Examples include disk, network, hostdev, controller, channel, input, rng, tpm, memballoon, vsock, etc. Each type has specific options.

--remove-device type[,option=value...]
    Remove a device matching the specified type and options. Used to identify which instance of a device to remove.

--edit xpath=value
    Apply a specific XPath edit to the domain's XML. This allows for precise modifications to any part of the XML.

--delete xpath
    Delete the XML element or attribute specified by the XPath.

--cpu model[,options]
    Define the CPU model and topology for the guest. Options include sockets, cores, threads, mode (e.g., host-model, host-passthrough).

--memory amount,unit=unit
    Set the guest's maximum memory allocation (e.g., 2048,unit=MiB). Units can be KiB, MiB, GiB.

--current-memory amount,unit=unit
    Set the guest's current memory, useful for memory hotplug. Requires hypervisor and guest support.

--disk options
    Configure or add a disk device. Common options: path, size, bus, format, device (disk|cdrom|floppy), serial, readonly, snapshot, cache.

--network options
    Configure or add a network interface. Common options: network, bridge, mac, model, type (direct|hostdev|ethernet|network|bridge), source.

--hostdev options
    Configure or add a host device passthrough (PCI, USB, etc.). Options: pci_address, usb_address, managed, mode.

--graphics options
    Configure the guest's graphical console. Options: type (vnc|spice|sdl|egl-headless|none), port, autoport, listen, keymap, password, gl.

--console options
    Configure the guest's serial console. Options: type (pty|dev|null), target_type (serial|virtio), target_port, path.

--boot options
    Configure boot devices and order. Options: path (e.g., hd, cdrom, network), menu=on|off, order.

--os-variant variant
    Specify the guest OS variant (e.g., rhel8, win10) to optimize domain settings.

--connect URI
    Connect to a specified hypervisor URI (e.g., qemu:///system).

--update
    Apply changes to an inactive domain by redefining it. This is the default action if no other output option is specified.

--replace
    Replace the domain's XML entirely. This first undefines the domain, then redefines it with the new XML. Use with caution.

--dry-run
    Show what changes would be applied without actually making them. Useful for testing.

--print-xml
    Print the resulting XML to standard output instead of applying changes. Useful for review or piping.

--build-xml
    Generate new XML based on the provided arguments, rather than modifying an existing domain. Requires --print-xml or an output target.

--autolearn
    Attempts to derive device configuration (like bus type) from the VM's existing configuration if not specified.

virt-xml is a powerful command-line utility for manipulating the XML configuration of virtual machines managed by Libvirt. It provides a simplified interface to modify common aspects of a domain's XML without directly editing the verbose XML file. Users can add, remove, or edit devices such as disks, network interfaces, USB devices, and host devices. It also facilitates changes to core VM parameters like CPU topology, memory allocation, and various other domain settings. This tool is invaluable for automation, scripting, and quickly adjusting VM configurations without launching a full graphical interface like virt-manager. It integrates seamlessly with virsh commands, allowing for flexible management of virtualized environments. The command can apply changes directly to an inactive or active domain (if supported), or output the modified XML to stdout for review or further processing. Its primary goal is to make common Libvirt XML modifications more accessible and less error-prone.

Incorrect usage of virt-xml can lead to unbootable or misconfigured virtual machines. Always back up domain XML before making significant changes.
Hotplugging devices and changes to active domains are dependent on hypervisor and guest operating system support, and may not work for all device types or configurations.
While simplifying common tasks, complex XML modifications or debugging may still require direct XML knowledge or usage of virsh edit.

virt-xml intelligently parses the existing domain XML (or builds a new one with --build-xml), applies the requested modifications, and then either outputs the result or redefines the domain. It attempts to place new XML elements in logical and consistent locations within the domain definition.
Many operations are designed to be idempotent, meaning applying the same command multiple times will result in the same final configuration, preventing duplicate entries for common device types unless specifically intended.

virt-xml is part of the virt-manager project, initially developed by Red Hat. It was created to provide a robust command-line interface for common Libvirt domain XML modifications, addressing the need for automation and streamlined configuration management. Its development has progressed alongside the evolution of Libvirt and KVM, becoming an essential tool for administrators and developers working with virtualized environments on Linux.

virsh(1), virt-install(1), virt-manager(1), qemu-kvm(1), libvirtd(8)