virsh-undefine

Delete only the virtual machine configuration file

$ virsh undefine --domain [vm_name]

$ virsh undefine --domain [vm_name] --remove-all-storage

$ virsh undefine --domain [vm_name] --storage [sda,sdb,path/to/source,...]

virsh undefine <domain> [--nvram] [--managed-save] [--snapshots-metadata] [--check-connected] [--storage]

<domain>
    The name or UUID of the virtual machine (domain) to be undefined. This is a mandatory argument.

--nvram
    If specified, deletes the Non-Volatile RAM (NVRAM) file associated with the domain. This is typically used for UEFI-based virtual machines.

--managed-save
    If specified, deletes any managed save image for the domain. A managed save image is created when a VM is suspended with virsh save.

--snapshots-metadata
    If specified, deletes all snapshot metadata associated with the domain. This does not delete the snapshot disk images themselves, but rather the libvirt-managed metadata.

--check-connected
    If specified, the command will fail if any active remote connections to the domain are detected.

--storage
    If specified, this option will also undefine any storage volumes that are reported as belonging to the domain and are managed by libvirt. Depending on the storage pool type and volume format, this can result in the deletion of the actual disk image files themselves. Use this option with extreme caution.

The virsh undefine command is used to remove the definition of a virtual machine (domain) from the libvirt daemon's configuration. This means libvirt will no longer recognize or manage the specified VM.

It's important to understand that, by default, virsh undefine only removes the XML configuration file associated with the domain from libvirt's registry. It does not delete the virtual machine's disk images or other associated data files from the storage system. These files remain on your host, allowing you to re-define the VM later using its original XML configuration if needed.

This command is typically used when a virtual machine is no longer needed, needs to be completely reconfigured from scratch, or when moving its definition to another libvirt host. To successfully undefine a domain, the virtual machine must be in an inactive state (e.g., shut off or paused).

VM State Requirement
The virtual machine targeted for undefinition must be in an inactive state (e.g., shut off, paused, or saved). If the VM is running, you must first stop it using commands like virsh shutdown (for graceful shutdown) or virsh destroy (for immediate, forceful termination).

Disk Image Preservation (Default)
By default, virsh undefine only removes the VM's configuration. It does not delete its disk images or other associated files. These files remain on your storage system. If you wish to remove these, you must do so manually or use the --storage option with caution.

Extreme Caution with --storage
The --storage option is powerful and potentially destructive. It can lead to the permanent deletion of your virtual machine's disk image files if they are managed by libvirt and the storage pool type allows it. Always double-check which volumes are linked and confirm you genuinely want to delete the underlying data before using this option.

Undefining a domain primarily removes its XML configuration from libvirt's active management. The VM will no longer appear in virsh list --all (unless it was autostarted and that autostart record is still active, in which case it will appear as 'inactive'). This operation is equivalent to removing a VM's entry from a hypervisor's inventory without touching its underlying storage.

A virtual machine that has been undefined can be re-defined using its original XML configuration file via the virsh define <path/to/xml> command, assuming its disk images and other dependencies are still intact.

virsh define(1), virsh start(1), virsh destroy(1), virsh shutdown(1), virsh list(1), virsh autostart(1), virsh vol-delete(1)