7.39. VBoxManage snapshot

Manage Oracle VM VirtualBox virtual machine snapshots.

7.39.1. Synopsis

VBoxManage snapshot { uuid|vmname }

VBoxManage snapshot { uuid|vmname } take { snapshot-name } [--description=description] [--live] [--uniquename Number,Timestamp,Space,Force]

VBoxManage snapshot { uuid|vmname } delete { snapshot-name }

VBoxManage snapshot { uuid|vmname } restore { snapshot-name }

VBoxManage snapshot { uuid|vmname } restorecurrent

VBoxManage snapshot { uuid|vmname } edit { snapshot-name | --current } [--description=description] [--name=new-name]

VBoxManage snapshot { uuid|vmname } list [[--details] | [--machinereadable]]

VBoxManage snapshot { uuid|vmname } showvminfo { snapshot-name }

7.39.2. Description

The VBoxManage snapshot command manages snapshots.

Oracle VM VirtualBox uses the snapshot to capture the state of a virtual machine (VM). You can later use the snapshot to revert to the state described by the snapshot.

A snapshot is a complete copy of a VM's settings. If you take the snapshot while the VM is running, the snapshot also includes the VM's state file.

After you take a snapshot, Oracle VM VirtualBox creates a differencing hard disk for each normal hard disk that is associated with the host machine. When you restore a snapshot, Oracle VM VirtualBox uses these differencing files to quickly reset the contents of the VM's virtual hard disks.

For each VBoxManage snapshot command, you must specify the name or the universal unique identifier (UUID) of the VM for which you want to take a snapshot.

7.39.2.1. General Command Operand

uuid|vmname: Specifies the UUID or name of the VM.

7.39.2.2. Take a Snapshot of a Virtual Machine

VBoxManage snapshot { uuid|vmname } take { snapshot-name } [--description=description] [--live] [--uniquename Number,Timestamp,Space,Force]

The VBoxManage snapshot take command takes a snapshot of the current state of the VM. You must supply a name for the snapshot and can optionally supply a description. The new snapshot is inserted into the snapshots tree as a child of the current snapshot and then becomes the new current snapshot.

--description=description: Specifies a description of the snapshot.
--live: Specifies that the VM is not stopped while you create the snapshot. This operation is know as live snapshotting.
--uniquename Number,Timestamp,Space,Force: TBD.
snapshot-name: Specifies the name of the snapshot to create.

7.39.2.3. Delete a Snapshot

VBoxManage snapshot { uuid|vmname } delete { snapshot-name }

The VBoxManage snapshot delete command removes the specified snapshot.

The delete operation may take some time to finish. This is because the differencing images that are associated with the snapshot may need to be merged with their child differencing images.

snapshot-name: Specifies the UUID or name of the snapshot.

7.39.2.4. Restore a Snapshot

VBoxManage snapshot { uuid|vmname } restore { snapshot-name }

The VBoxManage snapshot restore command restores the specified snapshot. This operation resets the VM's settings and current state to that of the snapshot. The state of the VM on which you restore a snapshot is lost. When restored, the specified snapshot becomes the new current snapshot and subsequent snapshots are children of that snapshot.

snapshot-name: Specifies the UUID or name of the snapshot.

7.39.2.5. Restore the Current Snapshot

VBoxManage snapshot { uuid|vmname } restorecurrent

The VBoxManage snapshot restorecurrent command restores the current snapshot. The current snapshot is the one from which the current state is derived. This command is equivalent to using the VBoxManage snapshot restore command and specifying the name or UUID of the current snapshot.

7.39.2.6. Change the Name or Description of an Existing Snapshot

VBoxManage snapshot { uuid|vmname } edit { snapshot-name | --current } [--description=description] [--name=new-name]

The VBoxManage snapshot edit command enables you to change the name or the description of a specified snapshot.

snapshot-name

Specifies the UUID or name of the snapshot to edit.

This option is mutually exclusive with the --current option.

--current

Specifies that you update the current version of the snapshot.

This option is mutually exclusive with a specific snapshot name or its UUID.

--description=description

Specifies a new description for the snapshot.

--name=new-name

Specifies a new name for the snapshot.

7.39.2.7. List the Snapshots

VBoxManage snapshot { uuid|vmname } list [[--details] | [--machinereadable]]

The VBoxManage snapshot list command lists all the snapshots for a VM.

--details

Specifies that the output shows detailed information about the snapshot.

This option is mutually exclusive with the --machinereadable option.

--machinereadable

Specifies that the output is shown in a machine-readable format.

This option is mutually exclusive with the --details option.

7.39.2.8. Show Information About a Snapshot's Settings

VBoxManage snapshot { uuid|vmname } showvminfo { snapshot-name }

The VBoxManage snapshot showvminfo command enables you to view the VM settings that are part of an existing snapshot.

snapshot-name: Specifies the UUID or name of the snapshot.

7.39.3. Examples

The following command creates a snapshot of the ol7u4 VM. The snapshot is called ol7u4-snap-001. The command uses the --description option to provide a description of the snapshot contents.

$ VBoxManage snapshot ol7u4 take ol7u4-snap-001 \
--description="Oracle Linux 7.4"

The following command lists the snapshots for the ol7u4 VM.

$ VBoxManage snapshot ol7u4 list

The following command changes the description for the ol7u4-snap-001 snapshot of the ol7u4 VM.

$ VBoxManage snapshot ol7u4 edit ol7u4-snap-001 \
--description="Oracle Linux 7.4 with UEK4 kernel"

The following command shows VM settings for the ol7u1-snap-001 snapshot of the ol7u4 VM.

$ VBoxManage snapshot ol7u4 showvminfo ol7u4-snap-001
Name:            ol7u4
Groups:          /
Guest OS:        Oracle (64-bit)
UUID:            43349d78-2ab3-4cb8-978f-0e755cd98090
Config file:     C:\Users\user1\VirtualBox VMs\ol7u4\ol7u4.vbox
...
Snapshots:

   Name: ol7u4-snap-001 (UUID: 1cffc37d-5c37-4b86-b9c5-a0f157a55f43)
   Description: Oracle Linux 7.4 with UEK4 kernel