azure-powershell-migration/docs/quickstart-migrate-azurerm-to-az-automatically.md

---
title: Automatically migrate PowerShell scripts from AzureRM to the Az PowerShell module
description: Learn how to automatically migrate PowerShell scripts from AzureRM to the Az PowerShell module.
author: mikefrobbins
ms.service: azure-powershell
ms.topic: quickstart
ms.custom: devx-track-azurepowershell
ms.author: mirobb
ms.date: 09/11/2020
---

# Quickstart: Automatically migrate PowerShell scripts from AzureRM to the Az PowerShell module

In this article, you'll learn how to use the Az.Tools.Migration PowerShell module to automatically
upgrade your PowerShell scripts and script modules from AzureRM to the Az PowerShell module.

Report feedback and issues about the Az.Tools.Migration PowerShell module via
[a GitHub issue](https://github.com/Azure/azure-powershell-migration/issues) in the
`azure-powershell-migration` repository.

## Requirements

* Update your existing PowerShell scripts to AzureRM PowerShell module version [6.13.1](https://github.com/Azure/azure-powershell/releases/tag/v6.13.1-November2018) or [6.13.2](https://github.com/Azure/azure-powershell/releases/tag/v6.13.2-March2021).
* Install the Az.Tools.Migration PowerShell module.

  ```powershell
  Install-Module -Name Az.Tools.Migration
  ```

## Step 1: Generate an upgrade plan

You use the `New-AzUpgradeModulePlan` cmdlet to generate an upgrade plan for migrating your scripts
and modules to the Az PowerShell module. The upgrade plan details the specific file and offset
points that require changes when moving from AzureRM to the Az PowerShell cmdlets.

> [!NOTE]
> The `New-AzUpgradeModulePlan` cmdlet doesn't execute the plan, it only generates the upgrade steps.

```powershell
#  Generate an upgrade plan for the specified PowerShell script and save it to a variable.
$Plan = New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion latest -FilePath 'C:\Scripts\my-azure-script.ps1'
```

```powershell
# Generate an upgrade plan for all the scripts and module files in the specified folder and save it to a variable.
$Plan = New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion latest -DirectoryPath 'C:\Scripts'
```

Review the results of the upgrade plan.

```powershell
# Show the entire upgrade plan
$Plan
```

Run the following command to filter the results to commands that have warnings or errors. This may
be helpful on large result sets to quickly identify errors before performing the upgrade.

```powershell
# Filter plan results to only warnings and errors
$Plan | Where-Object PlanResult -ne ReadyToUpgrade | Format-List
```

## Step 2: Perform the upgrade

The upgrade plan is executed when you run the `Invoke-AzUpgradeModulePlan` cmdlet. This command performs 
an upgrade of the specified file or folders except for any errors that were identified by the `New-AzUpgradeModulePlan` cmdlet.

This command requires you to specify if the files should be modified in place or if new files should be saved 
alongside your original files (leaving originals unmodified).

> [!CAUTION]
> There is no undo operation. Always ensure that you have a backup copy of your PowerShell scripts
> and modules that you're attempting to upgrade.

> [!WARNING]
> The `Invoke-AzUpgradeModulePlan` cmdlet is destructive when the `-FileEditMode ModifyExistingFiles` option is specified! It modifies your scripts and functions
> in place according to the module upgrade plan generated by the `New-AzUpgradeModulePlan` cmdlet. For the non-destructive option specify `-FileEditMode SaveChangesToNewFiles` instead.

```powershell
# Execute the automatic upgrade plan and save the results to a variable.
$Results = Invoke-AzUpgradeModulePlan -Plan $Plan -FileEditMode SaveChangesToNewFiles
```

Review the results of the upgrade operation.

```powershell
# Show the results for the entire upgrade operation
$Results
```

If any errors are returned, you can take a closer look at the error results with the following command:

```powershell
# Filter results to show only errors
$Results | Where-Object UpgradeResult -ne UpgradeCompleted | Format-List
```

## Limitations

* File I/O operations use default encoding. Unusual file encoding situations may cause problems.
* AzureRM cmdlets passed as arguments to Pester unit test mock statements aren't detected.
* Currently, only Az PowerShell module version 10.3 is supported as a target.

## Next steps

To learn more about the Az PowerShell module, see the [Azure PowerShell documentation](https://docs.microsoft.com/powershell/azure/)