How to migrate from AzureRM to Az in Azure PowerShell

Posted on December 20, 2018

Software Engineer, Microsoft Azure

On December 18, 2018, the Azure PowerShell team released the first stable version of “Az,” a new cross-platform PowerShell module that will replace AzureRM. You can install this module by running “Install-Module Az” in an elevated PowerShell prompt.

Screenshot of PowerShell session where Az was installed from the Gallery

Since January 2018, PowerShell has been a cross-platform product with the introduction of PowerShell Core. Therefore, it has also become a priority for Azure PowerShell to have cross-platform support. Because of the changes required to support running Azure PowerShell cross-platform, we decided to create a new module rather than make modifications to the existing AzureRM module. Moving forward, all new functionality will be added to the Az module, while AzureRM will only be updated with bug fixes.

Configure Az in your environment

Because both Az and AzureRM use the same dependencies with different versions, it is not possible to run Az and AzureRM side by side in the same PowerShell session. Thus, Az and AzureRM cmdlets cannot be used together in scripts and in interactive sessions. To ensure that a script does not try to import both Az and AzureRM modules in the same session, if you do not have many existing scripts that use AzureRM, we recommend that you remove all AzureRM modules from your machine after installing Az. For your convenience, we have created the “Uninstall-AzureRm” cmdlet, located in in the new Az module. To use this cmdlet, please ensure that all PowerShell sessions in which AzureRM modules are imported have been closed, then run “Uninstall-AzureRm” in an elevated PowerShell session.

Screenshot of PowerShell session where Uninstall-AzureRm cmdlet was run.

What about your existing Azure PowerShell scripts?

If you would like to continue using AzureRM for your existing scripts while also writing new scripts using Az then you have two possible options.

Option 1 – Install PowerShell Core 6

One option is to install Az on PowerShell Core 6 while continuing to use AzureRM on Windows PowerShell 5.1. This will allow you to run your existing AzureRM scripts on Windows PowerShell 5.1 without the possibility of running into issues where AzureRM and Az are imported in the same session.

Option 2 – Explicit module loading

Alternatively, if you cannot install PowerShell 6 on your machine, please ensure that you explicitly require either the Az or the AzureRM modules you intend to use at the beginning of each script, making certain that the modules required are not from both AzureRM and Az. To turn off warnings about the side by side installation of AzureRM and Az, please add “$env:SkipAzInstallationChecks=true” to your PowerShell profile.

Using the AzureRM aliases with Az

To simplify and normalize our cmdlet names, we have changed the prefix from AzureRM and Azure to Az for every cmdlet in the new Az modules. To enable preexisting scripts that were written for AzureRM to successfully execute in Az, we have written a cmdlet, “Enable-AzureRmAlias,” to create aliases to the old cmdlet names. This cmdlet includes a Scope parameter, which allows you to select whether the aliases should be created for only the current session or for all future sessions. Additionally, you can import aliases for specific modules using the “Module” parameter. Once your scripts have been converted to use “Az” prefixes, aliases can be turned off using the “Disable-AzureRmAlias” cmdlet. All new cmdlets added to the Az modules will not have these AzureRM aliases, so all new scripts should use the “Az” prefix syntax.

Screenshot of PowerShell session where Enable-AzureRm cmdlet was run.

Az on CloudShell

If you are looking for a quick way to test out the new Az modules interactively, CloudShell will now be shipping with the new Az modules. CloudShell is a great option as it runs everywhere and doesn’t require an install so you can keep your environment untouched while trying out all the new Az features. Simply navigate to the PowerShell tab within a CloudShell session, and all Az modules will be automatically installed into your session.

Az on CloudShell

Try it out

We want the new Az module to enable you to be more productive and efficient in managing Azure from any platform or operating system. Therefore, we would like to invite you to try out the new cross-platform module and we look forward to getting your feedback, suggestions or issues via the built-in “Send-Feedback” cmdlet, which is available in both AzureRM and the new Az module. Alternatively, you can always open an issue in our GitHub repository.