While renaming a vSphere Virtual Machine is very straightforward using the vSphere UI or API, this operation only updates the display name in the vSphere Inventory. To ensure the underlying VM configuration files (e.g. .vmdk, .vmx, etc. ) are also updated, a Storage vMotion is also required, which requires you to have at least two vSphere Datastores to perform the operation.
If Storage vMotion is not an option, you only have a single datastore or you are using vSAN, then your only option is to manually rename the individual VM files. For vSAN-based VMs, one additional step is required as vSAN manages objects and not files.
Step 1 - Rename your VM to the desired name using the vSphere UI
Step 2 - Unregister the VM using the vSphere UI
Step 3 - SSH to your ESX host and then change into the VM directory where its configuration files and VMDK are located in.
We are ONLY going to rename the non-VMDK files, so everything that does NOT end with .vmdk can be renamed from the old to the new label by using the "mv" command. While you can technically perform this operation using the vSphere UI Datastore Browser, we do need to run a command on the ESX Shell in the next step.
Step 4 - To rename the VMDK file(s), we will need to use the vmkfstools utility and repeat this for each VMDK file while preserving the original filename structure. In my example, the VM has two VMDK: photon-03.vmdk and photon-03_1.vmdk, so the commands to rename will be the following:
vmkfstools -E photon-03.vmdk photon-02.vmdk
vmkfstools -E photon-03_1.vmdk photon-02_1.vmdk
Step 5 - We now need to edit the VMX file to update all references of the old name to the new name. If you are comfortable with "vi", you can use following macro :%s/oldname/newname/g which will assume you have no spaces in your VM name to perform a global replace.
Step 6 - To rename the VM folder located on a vSAN Datastore, we need to use the objtool utility and provide it the vSAN UUID for that object. The easiest way to find the VM Folder UUID is to simply change into the root vSAN Datastore directory (e.g. /vmfs/volumes/vsanDatastore) and run "ls" command and look for the VM folder you wish to rename.
In my example, the VM folder is called "photon-03" and as you can see from the screenshot below, the label is actually symlink to vSAN UUID. Once we have the vSAN UUID, simply run the following command and replacing the UUID and the desired VM folder name to perform the rename operation:
/usr/lib/vmware/osfs/bin/objtool setAttr -u 20fe8268-6735-58ff-7935-5847ca7f8972 -n "photon-02"
If we perform the "ls" command again on the new VM folder name, we can see it still points to the same vSAN UUID as before.
Step 7 - The last step is to re-register your newly renamed VM using the vSphere UI Datastore Browser.
When you power on the VM, you will be asked whether you had "copied" or "moved" the VM.
Make sure to choose "moved" as selecting "copied" will then change the underlying VM UUID and MAC Address and potentially impact the actual VM itself.
While Step 4-5 can be tedious depending on the number of files for a given VM, I did provide the details to ChatGPT to build me quick shell script that can at least automate that portion of the workflow. By default, the script will run in "dry-run" mode and only unless you provide the --apply argument, it will not make any changes. You will still be responsible for performing Step 6 manually but you can certainly extend this further to have everything automated, but I will leave that as an exercise for the reader 🙂
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #!/bin/ash | |
| # Thank you ChatGPT for creating the script given my requirement/prompts | |
| # Usage: ./rename-esxi-vm.sh old_vm_name new_vm_name [--apply] | |
| # | |
| # Example dry-run (default): | |
| ./rename-esxi-vm.sh photon-03 photon-02 | |
| # Apply changes: | |
| ./rename-esxi-vm.sh photon-03 photon-02 --apply | |
| OLD="$1" | |
| NEW="$2" | |
| MODE="$3" | |
| if [ -z "$OLD" ] || [ -z "$NEW" ]; then | |
| echo -e "\nUsage: " | |
| echo -e "\t$0 old_vm_name new_vm_name [--apply]\n" | |
| exit 1 | |
| fi | |
| # Default is dry-run unless --apply is explicitly set | |
| if [ "$MODE" = "--apply" ]; then | |
| APPLY=1 | |
| echo "🚨 APPLY mode enabled — changes will be made!" | |
| else | |
| APPLY=0 | |
| echo "🧪 Dry-run mode (default): no files will be modified" | |
| fi | |
| echo "Renaming VM from '$OLD' to '$NEW'..." | |
| # Step 1: Rename all non-VMDK/non-VMX files | |
| for file in ${OLD}.*; do | |
| ext="${file##*.}" | |
| case "$ext" in | |
| vmdk|vmx) continue ;; # Skip VMDK and VMX | |
| esac | |
| newfile="${file/$OLD/$NEW}" | |
| echo "📁 Rename: $file → $newfile" | |
| [ "$APPLY" -eq 1 ] && mv "$file" "$newfile" | |
| done | |
| # Step 2: Rename VMDK files using vmkfstools | |
| for vmdk in ${OLD}*.vmdk; do | |
| [ ! -f "$vmdk" ] && continue | |
| suffix="${vmdk#$OLD}" | |
| newvmdk="${NEW}${suffix}" | |
| echo "💽 vmkfstools -E \"$vmdk\" \"$newvmdk\"" | |
| [ "$APPLY" -eq 1 ] && vmkfstools -E "$vmdk" "$newvmdk" | |
| done | |
| # Step 3: Rename .vmx and update its contents | |
| VMX_FILE="${OLD}.vmx" | |
| NEW_VMX_FILE="${NEW}.vmx" | |
| if [ -f "$VMX_FILE" ]; then | |
| echo "📄 Rename .vmx: $VMX_FILE → $NEW_VMX_FILE" | |
| if [ "$APPLY" -eq 1 ]; then | |
| cp "$VMX_FILE" "$NEW_VMX_FILE" | |
| sed -i "s/$OLD/$NEW/g" "$NEW_VMX_FILE" | |
| rm -f "$VMX_FILE" | |
| else | |
| echo "📝 Would copy and update internal references in $NEW_VMX_FILE" | |
| fi | |
| else | |
| echo "⚠️ .vmx file not found: $VMX_FILE" | |
| fi | |
| echo | |
| if [ "$APPLY" -eq 1 ]; then | |
| echo "✅ Rename completed (applied)" | |
| else | |
| echo "✅ Dry-run completed — use '--apply' to execute changes" | |
| fi | |
Great content!! In the v9 we still have this nightmare rename vms with a single datastore?
AI forgot that you need to shutdown the VM for that.
Why can't we just get a powercli commandlet which will perform these actions for us? This will also help a lot within an automation context.