How to Rename Azure Virtual Machine?

Did you ever provision an Azure virtual machine only to realize you used the wrong name for the VM? Maybe you missed a letter or specified an entirely different name? You would think that you could just rename the VM. But lo and behold, there’s no straightforward Azure VM rename function.

Don’t worry. Hope is not lost. With a little bit of PowerShell magic, there’s a workaround to renaming a VM as though nothing happened.

So, what are the steps to rename Azure virtual machines? Here’s the high-level process.

  • Back up the old VM resource details.
  • Delete the old VM without deleting the OS disk, data disks (if any), and network interfaces.
  • Create a new VM configuration patterned after the old VM, except for the name.
  • Create the new VM.

Stick around and learn how in this step-by-step guide.


Before going any further, let’s review what you’ll need to follow along the steps in this post.

  • Windows PowerShell 5.1 or PowerShell Core 7+. This post will be using PowerShell 7.2.6 on Windows.
  • The Az PowerShell module must be installed on your computer. If not, you can install it first by following this link. The latest version is 8.0.3, which this post will be using.
  • The Azure VM that you’ll be renaming. This post will be demonstrating the procedure using a VM named sqlsvr001.rename azure virtual machine

Step 1: Backup the Old VM Resource Details

First, connect to Az PowerShell.


Once you’ve authenticated with Azure, define the old VM name and the resource group name where the VM resides. Replace the $resourceGroupName and $vmName with your own.

$resourceGroupName = 'DEV' 
$vmName 'sqlsvr001'

Get the Azure VM resource details and store the result in the $oldVmResource variable.

# Get the Azure VM resource details 
$oldVmResource = Get-AzResource -ResourceType 'Microsoft.Compute/virtualMachines' -ResourceName $vmName -ResourceGroupName $resourceGroupName

The OS disk, data disks (if any), and network interfaces persist by default after deleting their attached virtual machine. But, each of these resources has a property called deleteOption. If the value is detach, then the resource will survive the VM deletion.

To inspect the value of these deleteOption properties, run each command below. If the deleteOption property value is delete, the resource will be deleted along with the VM.

# Inspect the OS Disk, Data Disk, and Network Interface DeleteOptions 
$oldVmResource.Properties.storageProfile.osDisk | Format-List name, deleteOption 
$oldVmResource.Properties.storageProfile.dataDisks | Format-List name, deleteOption 
$oldVmResource.Properties.networkProfile.networkInterfaces | Format-List @{n = 'name'; e = { (($'/')[-1]) } }, @{n = 'deleteOption'; e = { $ } }

As you can see below, the OS Disk, data disks, and network interface attached to the VM are set to be deleted if the VM is deleted.

azure rename virtual machine

To persist the resources after deleting the old VM, run the commands below to set each resource’s deleteOption value to detach.

# Set the osDisk deleteOption property to detach 
$oldVmResource.Properties.storageProfile.osDisk.deleteOption = 'detach' 

# Set each dataDisk deleteOption property to detach 
if ($oldVmResource.Properties.storageProfile.dataDisks.count -gt 0) { 
$oldVmResource.Properties.storageProfile.dataDisks | ForEach-Object { $_.deleteOption = 'detach' } 

# Set each dataDisk deleteOption property to detach 
if ($oldVmResource.Properties.networkProfile.networkInterfaces.count -gt 0) { 
$oldVmResource.Properties.networkProfile.networkInterfaces | ForEach-Object { $_.Properties.deleteOption = 'detach' } 

# Update the old VM resource properties 
$oldVmResource | Set-AzResource -Force

If successful, you’ll see a similar result to the one below.

rename vm in azure

Now, save the VM resource details to a backup XML file.

$oldVmResource | Export-CliXml -Depth 7 .\oldVmResource.xml

Step 2: Delete the Old Azure VM

First, make sure the VM is stopped before trying to delete it.

Stop-AzVM -ResourceGroupName $resourceGroupName -Name $vmName -Force

rename vm azure

Confirm that the VM PowerState value shows VM deallocated.

(Get-AzVM -ResourceGroupName $resourceGroupName -Name $vmName -Status).Statuses

azure vm rename

Finally, run this command to delete the Azure VM.

Remove-AzVM -ResourceGroupName $resourceGroupName -Name $vmName

Confirm to delete the VM when prompted. After the deletion, you will see a status message returned as below.

rename a vm in azure

Step 3: Create a New Azure VM Configuration

Now that we’ve deleted the old VM, it’s time to compose the new VM configuration. Aside from a new name, the new VM configuration will have the same resources as the old one and be in the same resource group.

Initialize a new VM configuration and store it in the $newVmResource variable. In this example, we’re naming the new VM websvr001.

$newVmName = 'websvr001' 
$newVm = New-AzVMConfig ` 
-VMName $newVmName ` 
-VMSize $oldVmResource.Properties.hardwareProfile.vmSize ` 
-Tags $oldVmResource.Tags

Next, run the below commands to attach the OS disk resource to the new VM.

# Attach the OS Disk to the new VM configuration 
$osDiskParams = @{ 
VM = $newVm 
CreateOption = 'Attach' 
ManagedDiskId = $ 
Name = $oldVmResource.Properties.storageProfile.osDisk.Name 
DeleteOption = $oldVmResource.Properties.storageProfile.osDisk.deleteOption 
switch ($oldVmResource.Properties.storageProfile.osDisk.osType) { 
'Linux' { $osDiskParams += @{Linux = $true } } 
'Windows' { $osDiskParams += @{Windows = $true } } 

Attach all additional data disks (if any). Skip this step if there are no data disks to attach.

# Attach the data disks to the new VM configuration (if any) 
$oldVmResource.Properties.StorageProfile.DataDisks | ForEach-Object { 
$null = Add-AzVMDataDisk -VM $newVM ` 
-Name $_.Name ` 
-ManagedDiskId $_.ManagedDisk.Id ` 
-Caching $_.Caching ` 
-Lun $_.Lun ` 
-DiskSizeInGB $_.DiskSizeGB ` 
-CreateOption $_.createOption ` 
-DeleteOption $_.deleteOption 

Now, attach the network interfaces to the new VM.

# Attach the Network Interface resources to the VM config 
$oldVmResource.Properties.networkProfile.networkInterfaces | ForEach-Object { 
$null = Add-AzVMNetworkInterface -VM $newVM -Id $_.Id 

After creating the configuration, inspect the $newVM object.


You should see the virtual machine object properties that you created.

rename an azure virtual machine

Step 4: Create the Renamed Azure Virtual Machine

Finally, let’s create the new renamed Azure VM. To do so, run the below command to deploy the new VM. The VM will be created in the same resource group and location as the old VM.

Let’s rename Azure virtual machine sqlsvr001 to websvr001.

Note. If the Azure VM must be added to an availability set, add the -AvailabilitySetName <name> parameter to the command.

# Deploy the VM. 
New-AzVM -ResourceGroupName $resourceGroupName -Location $oldVmResource.Location -VM $newVM

After the deployment, you’ll see the below result.

azure rename a virtual machine

Run the following command to show the new VM you created.

Get-AzVM -ResourceGroupName $resourceGroupName -Name $newVmName

rename a vm in azure

If you look into the Virtual machines – Microsoft Azure Portal, you can confirm that the Azure VM rename operation was successful. The VM now has a different while retaining the same resources, including the public IP address.

rename a vm azure

Post Azure VM Rename Task

After you finish the Azure VM rename steps, remember that you only made changes to the VM level, not the guest OS. The guest OS, Ubuntu, in this case, still has the old computer name. You must log in to your Azure VM’s operating system and manually change the computer name.


That’s it! You’ve learned how to rename an Azure virtual machine using the Az PowerShell module. What you learned here covered only the essentials, and you must always exercise caution when deleting resources.

Leave a Reply

Your email address will not be published. Required fields are marked *