20.9. Removing and Deleting a Virtual Machine

20.9.1. Undefining a Virtual Machine

The virsh undefine domain [--managed-save] [storage] [--remove-all-storage] [--wipe-storage] [--snapshots-metadata] [--nvram] command undefines a domain. If domain is inactive, the configuration is removed completely. If the domain is active (running), it is converted to a transient domain. When the guest virtual machine becomes inactive, the configuration is removed completely.
This command can take the following arguments:
  • --managed-save - this argument guarantees that any managed save image is also cleaned up. Without using this argument, attempts to undefine a guest virtual machine with a managed save will fail.
  • --snapshots-metadata - this argument guarantees that any snapshots (as shown with snapshot-list) are also cleaned up when undefining an inactive guest virtual machine. Note that any attempts to undefine an inactive guest virtual machine with snapshot metadata will fail. If this argument is used and the guest virtual machine is active, it is ignored.
  • --storage - using this argument requires a comma separated list of volume target names or source paths of storage volumes to be removed along with the undefined domain. This action will undefine the storage volume before it is removed. Note that this can only be done with inactive guest virtual machines and that this will only work with storage volumes that are managed by libvirt.
  • --remove-all-storage - in addition to undefining the guest virtual machine, all associated storage volumes are deleted. If you want to delete the virtual machine, choose this option only if there are no other virtual machines using the same associated storage. An alternative way is with the virsh vol-delete. See Section 20.31, “Deleting Storage Volumes” for more information.
  • --wipe-storage - in addition to deleting the storage volume, the contents are wiped.

Example 20.17. How to delete a guest virtual machine and delete its storage volumes

The following example undefines the guest1 virtual machine and remove all associated storage volumes. An undefined guest becomes transient and thus is deleted after it shuts down:
virsh undefine guest1 --remove-all-storage

20.9.2. Forcing a Guest Virtual Machine to Stop

Note

This command should only be used when you cannot shut down the virtual guest machine by any other method.
The virsh destroy command initiates an immediate ungraceful shutdown and stops the specified guest virtual machine. Using virsh destroy can corrupt guest virtual machine file systems. Use the virsh destroy command only when the guest virtual machine is unresponsive. The virsh destroy command with the --graceful option attempts to flush the cache for the disk image file before powering off the virtual machine.

Example 20.18. How to immediately shutdown a guest virtual machine with a hard shutdown

The following example immediately shuts down the guest1 virtual machine, probably because it is unresponsive:
virsh destroy guest1
You may want to follow this with the virsh undefine command. See Example 20.17, “How to delete a guest virtual machine and delete its storage volumes”