Edit

Switch between classic and preview Azure PowerShell

The preview Az modules install side by side with your existing (classic) Az modules. Both use the same module names (Az, Az.Compute, and so on), so a single PowerShell session can load only one of them at a time. This article explains how to choose which version loads and how to switch between them.

How coexistence works

When you install the preview, its modules land in the same module path as the classic modules, just at a different version number. The preview uses the 0.1.x version series; classic releases use higher version numbers (for example, 16.4.0). Installing a new preview version doesn't change classic Az or remove older preview versions.

Product Example version Notes
Classic Azure PowerShell 16.4.0 Your existing, full Az installation.
Azure PowerShell preview 0.1.5 An example preview module version.

Because both versions are available, PowerShell decides which one to load based on the version you request. For more information, see Install Azure PowerShell modules.

Check which versions are installed

List every installed version of the Az module:

Get-Module Az -ListAvailable | Select-Object Name, Version, ModuleBase

The preview appears as a version in the 0.1.x series, such as 0.1.5. If you also have classic Azure PowerShell, its higher version numbers appear in the same list.

Load a specific version

Use Import-Module with a version constraint to choose which version loads in the current session.

Load the preview in a new session before running Azure cmdlets. Use a minimum version of 0.1.0 and a maximum version of 0.1.9999 to load the newest installed preview:

Import-Module Az -MinimumVersion 0.1.0 -MaximumVersion 0.1.9999

To load one exact build instead, use -RequiredVersion with an installed version number from the previous step. For example, if you have version 0.1.5 installed:

Import-Module Az -RequiredVersion 0.1.5

Load the classic version (use the version number from the previous step):

Import-Module Az -RequiredVersion 16.4.0

Note

If you run Import-Module Az without a version, PowerShell loads the highest installed version. When classic Azure PowerShell is present, that means the classic modules load, not the preview. Pass the version range shown above (or a specific -RequiredVersion) to load the preview. Running an Azure cmdlet without explicitly importing the preview can also autoload classic modules.

Confirm which version is active

Check the version of the Az module loaded in the current session:

Get-Module Az | Select-Object Name, Version

A version in the 0.1.x series (for example 0.1.5) means the preview is active. A higher version means the classic modules are active. If nothing is returned, no Az module is loaded yet in this session.

Switch between versions

Each PowerShell session can use only one version. Decide which version you want before you run your first Import-Module Az, and start a new session to switch.

You can't switch versions inside a running session. The Az modules load binary (.NET) components, and once those are loaded, PowerShell can't replace them with a different version. Attempting to import the other version fails with an error such as:

Import-Module: Could not load file or assembly '...'. Assembly with same name is already loaded

Remove-Module doesn't help either: it removes the PowerShell module, but the loaded assemblies stay in the process. To switch, close the current session and start a new one — for example, run exit and then launch pwsh again. In the new session, load the version you want:

Import-Module Az -MinimumVersion 0.1.0 -MaximumVersion 0.1.9999

Optional: helper functions

To make switching feel seamless, add functions to your PowerShell profile that each start a clean session in the version you want:

function az-preview { pwsh -NoExit -Command 'Import-Module Az -MinimumVersion 0.1.0 -MaximumVersion 0.1.9999' }
function az-classic { pwsh -NoExit -Command 'Import-Module Az' }

Run az-preview or az-classic to open a fresh session with that version loaded.

For more information about adding these functions to your profile, see How to edit a profile.