# Azure PowerShell: the Az module, its rollup structure and its update model

> A read of the Azure/azure-powershell repository: how the Az rollup module is built and released, what changed with the AzureRM migration, and where a 1,572 issue backlog comes from.

**Azure/azure-powershell** — Microsoft Azure PowerShell

- Repository: https://github.com/Azure/azure-powershell
- Stars: 4,807 · Forks: 4,283
- Language: C#
- License: NOASSERTION
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/azure-azure-powershell

## One repository, dozens of modules, two rollups

The repository is not one module. It is the source for a large set of PowerShell modules, each published to the PowerShell Gallery and to a Microsoft Artifact Registry, and it presents two rollups at the top: `Az` for stable and `AzPreview` for the modules that include preview functionality. The README points at a separate page for the complete module list, which is the first thing anyone evaluating this needs, because the rollup's contents change as new Azure services appear.

The build layout in the tree explains how a codebase this size stays generated. `src/` holds the hand-written module sources, `generated/` holds code produced from service definitions, and `swagger_to_sdk_config.json` is the mapping that drives that generation. `tools/` and `eng/` carry the build scripts, `setup/` the packaging, and `build.proj`, `Repo.props` and `Directory.Build.targets` the MSBuild orchestration. `documentation/` holds the docs, and `.azure-pipelines/`, `.ci-config.json` and `.devcontainer/` cover continuous integration and a development container.

So the architecture is code generation driven rather than handwritten cmdlet by cmdlet, which is the only sane way to keep hundreds of service modules in sync with a REST API. It also means a large part of the source is machine-written, and the interesting hand-written part is the shared plumbing: authentication, contexts, pipelines and error handling.

## Installing Az and the AzureRM migration

Installation is a single command in a PowerShell session:

```powershell
Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force
```

The `-Scope CurrentUser` choice avoids needing administrator rights and keeps the module out of the machine-wide module path, which is what you want on a workstation or a build agent that manages more than one identity. PowerShell 7 is the recommended version across Windows, Linux and macOS, and the module also runs on Windows PowerShell 5.1 with .NET Framework 4.7.2 or higher.

The migration instruction is unambiguous: the `Az` module replaces `AzureRM`, and you should not install `Az` side-by-side with `AzureRM`. That is a real constraint rather than advice, because both define cmdlets for the same nouns and the older one shadows commands unpredictably. Anyone arriving from AzureRM scripts has to remove the old module first.

The Az module is also preinstalled in Azure Cloud Shell, which is the fastest way to try it without installing anything locally, and it is a reasonable default when you want a logged-in session without managing local credentials.

## Update-Module never removes anything

This is the line in the README that causes the most trouble in long-lived environments:

```powershell
Update-Module -Name Az -Scope CurrentUser -Force
```

`Update-Module` installs the new version side-by-side with previous versions and does not uninstall them. The README states this plainly, which means a machine that has been updated a dozen times has a dozen `Az` versions in the CurrentUser module directory, all of which remain loadable.

That is fine interactively and a problem in automation. When several module versions are present, the one PowerShell imports depends on resolution order, and a script that runs on a developer machine and then on a CI runner can load different module versions with the same cmdlet names. For reproducible automation the practical approach is to pin module versions explicitly in a script or to build the module path deliberately rather than relying on which version happens to be newest.

The release list explains why version pinning has to be per module rather than global. The three most recent releases are all individual modules, not the rollup: Az.DataProtection 3.1.0 on 2026-09-18, Az.Resources 10.2.1 on 2026-09-17 and Az.ArtifactSigning 0.2.2 on 2026-09-16. Their numbers do not correlate with each other, because each module follows its own service's API version.

## Contexts, tenants and signing in to the right cloud

Authentication opens a browser by default:

```powershell
Connect-AzAccount
```

For unattended use there is a service principal path, where the application ID acts as the username and the secret as the password:

```powershell
$Credential = Get-Credential
Connect-AzAccount -ServicePrincipal -Credential $Credential -TenantId $TenantId
```

The `Environment` parameter selects the cloud, with `AzureChinaCloud`, `AzureCloud` and `AzureUSGovernment` named in the README. That matters more than it looks for anyone working across sovereign clouds, because a context created against the public cloud will not resolve resources in another one.

A session context holds the login information and persists across modules and PowerShell instances, which is what makes multi-subscription work possible. `Get-AzContext` shows the current one, `Get-AzContext -ListAvailable` lists the stored ones, and `Set-AzContext` switches between them, either by argument or by piping from `Get-AzSubscription`:

```powershell
Get-AzSubscription -SubscriptionName $SubscriptionName | Set-AzContext -Name 'MyContext'
```

Naming contexts with `-Name` is the part worth building into habits. An unnamed context is convenient once and a recurring source of running a command against the wrong subscription, since the destructive cmdlets are named for create, remove and set.

## Finding a cmdlet when you do not know its name

The Az surface is large enough that discovery matters. `Get-Command` covers three useful patterns, all shown in the README: list everything in a module, filter by name, and combine both.

```powershell
Get-Command -Module Az.Compute -Name '*VM*'
```

The documentation side has the same shape with `Get-Help`, which accepts `-Examples`, `-Full` and `-Online`. The `-Online` switch pulls the learn.microsoft.com page for the cmdlet, so the README effectively points you at Microsoft's hosted documentation as the authoritative reference for behaviour.

That is the honest division of labour in this project. The repository README is an installation and orientation guide of about a page, and everything else is on learn.microsoft.com or in the module help. For a project with 1,572 open issues at the time of writing, that is not surprising, but it does mean evaluating a cmdlet means looking it up rather than reading the source.

## Recent release notes show what Microsoft is fixing

The three most recent module releases are small and diagnostic. Az.DataProtection 3.1.0 upgrades the Data Protection API version to 2026-06-01 now that it is generally available, and the note says it natively models Azure Elastic SAN backup and restore types. Az.Resources 10.2.1 aligns deployment stack `WhatIf` result tag preservation with the deployment stack cmdlets when `-Tag` is omitted or explicitly null, which is the kind of fix that only surfaces from real preview use.

Az.ArtifactSigning 0.2.2 is the most instructive. It fixed a token audience mismatch that produced `401 Unauthorized` calls, caused by a trailing slash in the authentication resource URL. A wrong audience on a signing endpoint is the sort of bug that looks like a credentials problem to the user and sends them rotating secrets for no reason.

Two structural notes sit alongside these. The repository is not archived and the last push was on 2026-09-22, four days after the newest release, so the pipeline is running. And feedback has a channel built into the product: the `Send-Feedback` cmdlet is the supported route for feature requests, alongside filing an issue in the repository or asking Azure Community Support.

On licensing, the repository metadata reports NOASSERTION while carrying a LICENSE.txt, and contributions require signing a Microsoft CLA, handled by a bot that checks each pull request once per person across all repositories using it. Read LICENSE.txt for the terms rather than inferring them from the metadata.

## Conclusion

Az PowerShell suits anyone automating Azure administration from PowerShell, particularly on Linux and macOS where PowerShell 7 is the recommended host. Its sharpest edge is the update model: `Update-Module` installs alongside previous versions and never removes them, so automation that assumes a single clean module will drift. The releases also ship per module rather than as one package, so pin versions per module when you need reproducibility. Start with `Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force`, authenticate with `Connect-AzAccount`, and check `Get-AzContext` before running anything that creates a resource.

## FAQ

### What is Azure PowerShell?

It is a set of PowerShell cmdlets for developing, deploying, administering and managing Microsoft Azure resources, published as the `Az` rollup module from the Azure/azure-powershell repository. It is preinstalled in Azure Cloud Shell and can be installed from the PowerShell Gallery.

### Is AZ PowerShell deprecated?

No. The `Az` module replaced the older `AzureRM` module, and the README states you should not install the two side-by-side. Module releases continued through September 2026, with Az.DataProtection 3.1.0 published on 2026-09-18.

### Does Update-Module remove the old version of Az?

No. The README states that `Update-Module` installs the new version side-by-side with previous versions and does not uninstall them, so several versions can remain in the CurrentUser module directory and PowerShell resolves which one to import.

## Sources

- [Azure/azure-powershell on GitHub](https://github.com/Azure/azure-powershell)
- [Issues](https://github.com/Azure/azure-powershell/issues)
- [README](https://github.com/Azure/azure-powershell/blob/main/README.md)
- [Releases](https://github.com/Azure/azure-powershell/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/azure-azure-powershell