vboxmanage-unregistervm

Unregister an existing VM

$ VBoxManage unregistervm [uuid|vm_name]

$ VBoxManage unregistervm [uuid|vm_name] --delete

$ VBoxManage unregistervm [uuid|vm_name] --delete-all

VBoxManage unregistervm VM name or UUID [--delete]

VM name or UUID
    Specifies the name or universally unique identifier (UUID) of the virtual machine to be unregistered. This is a mandatory argument.

--delete
    An optional flag that instructs VirtualBox to permanently delete all associated virtual disk images, snapshots, and saved states along with unregistering the VM definition. Use with extreme caution as this action is irreversible.

The VBoxManage unregistervm command is used to remove a virtual machine's definition from the VirtualBox inventory. When a VM is unregistered, it no longer appears in the VirtualBox Manager GUI or in the list returned by VBoxManage list vms. By default, this command only removes the VM's configuration file (.vbox or .vbox-prev) and its entry from the VirtualBox registry. This means the associated virtual disk images (VDI, VMDK, etc.), snapshots, and saved states remain on the file system.

The optional --delete flag significantly alters this behavior. When --delete is specified, VBoxManage unregistervm will not only remove the VM definition but also permanently delete all linked virtual disk images, snapshots, and saved states from your storage. This is a powerful, destructive operation and should be used with extreme caution. It's crucial to understand the distinction between unregistering a VM (removing its entry) and deleting its associated files (freeing up disk space). The command requires the VM to be powered off before it can be unregistered.

1. Irreversibility: When the --delete flag is used, all associated disk images, snapshots, and saved states are permanently removed from your system without a confirmation prompt. Ensure you have backed up any critical data before using this option.
2. VM State: The virtual machine must be powered off before it can be successfully unregistered. Attempting to unregister a running VM will result in an error.
3. Partial Deletion: Without the --delete flag, only the VM definition is removed. Other files like log files or additional attachments (e.g., ISOs) might remain on the disk and need manual cleanup.

Understanding the behavior of unregistervm is critical for disk space management. If you only unregister a VM without the --delete flag, its virtual disks still consume disk space. You would then need to manually locate and delete the .vdi or other disk image files if you intend to free up storage.

Before using VBoxManage unregistervm --delete, always double-check the VM name/UUID to ensure you are targeting the correct virtual machine. It is highly recommended to create backups of important data or critical VMs before performing such a destructive operation.

VBoxManage(1), VBoxManage list vms(1), VBoxManage registervm(1), VBoxManage showvminfo(1), VBoxManage closevm(1)