VMware ESXi and vSphere Cluster Management

Managing Virtual Machine UUIDs in VMware Player

Learn how VMware Player assigns virtual machine UUIDs, what happens when you move or copy a VM, how to preserve identity with uuid.action, and how to verify the result.

A VMware virtual machine has a UUID, short for Universal Unique Identifier. This is a globally distinctive identifier that helps distinguish one virtual machine from another.

VMware generates the virtual machine UUID during the VM’s initial startup. The identifier becomes part of the virtual machine’s hardware identity and can be used by guest operating systems, inventory systems, and management tools.

What a VMware Virtual Machine UUID Does

The UUID identifies the virtual machine as a logical machine, even when its files are stored in a different folder or on a different host. It is separate from the VM’s display name and file name. Renaming a VM does not necessarily change its UUID.

Normal operations such as shutting down and restarting the same VM generally preserve the UUID. Moving or duplicating the VM files is different because VMware must determine whether the files still represent the original machine or a new machine.

Where the UUID Is Exposed

VMware exposes the virtual machine UUID through SMBIOS. SMBIOS is system-management firmware information that describes hardware and system identity data to software running inside the guest.

A guest operating system can read SMBIOS data, and inventory or asset-management tools can collect the system UUID from it. SMBIOS-scanning utilities are commonly used to report this value. On a Linux guest, for example, an administrator may use a system-information utility such as dmidecode to inspect the system UUID when the necessary privileges are available.

sudo dmidecode -s system-uuid

UUID Persistence During Normal Use

A VM normally keeps its UUID while it remains in its original location and identity context. A regular shutdown, power-on, or restart does not normally create a new UUID.

Relocating the VM files or making a copy changes the situation. VMware can detect that the VM may have been moved or copied and asks you to identify the intended operation when the VM is powered on.

What Happens After Moving or Copying a VM

The moved-versus-copied prompt

When VMware Player detects that VM files are no longer in their previous context, the first startup may display a prompt asking whether the virtual machine was moved or copied.

• Moved: VMware treats the VM as the same logical machine in a new location and preserves its identity.
• Copied: VMware treats the files as a separate VM instance and assigns a different UUID.

Choose moved when you relocated an established VM and intend to continue using that same machine. Choose copied when you created an independent clone or lab instance.

Preserving a UUID with the VMX File

The VMX file is the virtual machine configuration file. It has a .vmx extension and is stored with the VM’s other files. The file commonly has a name similar to VM-NAME.vmx.

Prerequisites

1. Shut down the guest operating system.
2. Power off the virtual machine completely. Do not edit the configuration while the VM is running or suspended.
3. Locate the .vmx file belonging to the intended VM.
4. Make a backup copy of the VMX file before editing it.
5. Open the VMX file in a plain-text editor.

Set the UUID action

Add the following property to the VMX file:

uuid.action = "keep"

The uuid.action property controls how VMware handles the UUID after a VM is relocated or duplicated. The value keep instructs VMware to retain the existing UUID and suppresses the moved-versus-copied question on later startup.

Save the file, ensure the edited file is the one registered for the VM, and then start the VM. If the VMX file already contains a uuid.action entry, edit the existing entry rather than creating conflicting duplicate properties.

Operational Cautions

Two active VM copies with the same UUID can create identity conflicts in inventory systems, automation, monitoring, licensing, or workflows that use the UUID as a machine key. Preserving an identifier does not make two machines safely independent.

• For a VM relocated to a new folder or host, preserve the UUID if it is intended to remain the same machine.
• For an intentionally independent duplicate, allow VMware to assign a new UUID by selecting copied.
• Do not run simultaneous copies with an identical UUID when management systems expect UUID uniqueness.
• Consider other cloned-machine identities separately, including host names, network settings, and guest operating-system identifiers.

Verification Workflow

1. Start the original VM and record its UUID using an SMBIOS-reading utility or inventory tool.
2. Shut down the VM before moving or copying its files.
3. Relocate or duplicate the VM, depending on the intended outcome.
4. At the next startup, record whether you selected moved or copied. If uuid.action = "keep" was configured, note that the prompt should not appear.
5. After the guest starts, read the SMBIOS-reported system UUID again.
6. Compare the new value with the value recorded before the operation.

A matching UUID confirms that the identity was retained. A different UUID is expected when the copied option was selected for an independent VM. If the result does not match the selected behavior, check that the correct VMX file was edited, that the VM was fully powered off during editing, and that the property syntax is exact.

UUID Preservation Decision Guide

Troubleshooting

VMware asks whether the VM was moved or copied

This usually means the VM files were relocated or duplicated and VMware needs to determine the intended identity. Choose moved for the same logical machine or copied for a new independent VM. If preservation is required without the question, power off the VM and configure the VMX property before starting it.

The VM has a different UUID after duplication

This is expected when copied was selected. VMware generated a new machine identifier so the duplicate could be treated as independent. If the files were intended to represent the original machine instead, restore the intended workflow and preserve the UUID before the next relocation operation.

The UUID preservation setting has no effect

Common causes include editing the VMX file while the VM was running, changing the wrong VMX file, or entering an invalid property name or value. Fully shut down the VM, confirm the file belongs to the intended VM, verify the exact setting below, save it, and start the VM again.

uuid.action = "keep"

Two active VMs report the same UUID

A copied VM may have been configured to retain the source UUID. Treat one VM as an independent copy and allow it to receive a new UUID. Avoid operating duplicate identities where inventory or management software depends on UUID uniqueness.

Exam-Relevant Notes

• UUID means Universal Unique Identifier and distinguishes one VM from another.
• VMware generates the VM UUID during the VM’s initial startup.
• The UUID is exposed to the guest through SMBIOS system information.
• Normal restarts generally retain the UUID; moving or copying VM files can trigger an identity decision.
• Moved preserves the identity of the same logical machine.
• Copied creates a separate VM identity with a different UUID.
• The VM must be powered off before editing its .vmx file.
• uuid.action = "keep" tells VMware to retain the existing UUID and suppress the startup decision.
• Never preserve the same UUID across simultaneously used independent VM copies unless the surrounding workflow explicitly supports that design.

For a concise reference to this identifier, see Universal Unique Identifier UUID.