How to Install Azure CLI on Windows, Mac and Linux (Download and Setup Guide)

The Azure CLI (az) is Microsoft's cross-platform command-line tool for creating and managing Azure resources. It runs on Windows, macOS and Linux, inside a Docker container, and comes preinstalled in Azure Cloud Shell. This guide covers every supported way to download and install it, then how to verify it, sign in, keep it updated, remove it, and fix the install problems I see most often.

All commands below come from the official Install the Azure CLI pages on Microsoft Learn.

Quick Answer: Install Azure CLI in One Command

Operating system	Command
Windows 10/11 (WinGet)	winget install --exact --id Microsoft.AzureCLI
macOS (Homebrew)	brew update && brew install azure-cli
Ubuntu / Debian	curl -fsSL 'https://azurecliprod.blob.core.windows.net/$root/deb_install.sh' | sudo bash
RHEL / CentOS Stream	Add the Microsoft repo, then sudo dnf install azure-cli
Docker	docker run -it mcr.microsoft.com/azure-cli:azurelinux3.0
Browser, nothing to install	Open Azure Cloud Shell

After any local install, close and reopen your terminal, then run az version to confirm it worked and az login to sign in.

Microsoft ships a new release about once a month. The current version number is listed at the top of the Windows install page and in the Azure CLI release notes.

Do You Need Python First?

No. Older guides (including the first version of this post) told you to install Python before the CLI. You don't install Python yourself any more. The Windows installers and the apt package bundle it, and Homebrew and dnf install it as a dependency.

Install Azure CLI on Windows

Windows has three options: WinGet, the MSI installer, and a ZIP package. Whichever you pick, you run az from PowerShell or Command Prompt. You don't need to uninstall an older version first, because the MSI upgrades whatever is already there.

Option 1: WinGet (recommended)

WinGet is built into Windows 11 and current builds of Windows 10. Open PowerShell or Windows Terminal and run:

winget install --exact --id Microsoft.AzureCLI

The --exact flag makes sure you get the official package and not a lookalike. On a 64-bit system WinGet installs the 64-bit CLI by default. To pin a specific version, add --version:

winget install --exact --id Microsoft.AzureCLI --version 2.67.0

If winget isn't recognised, follow Microsoft's WinGet install guide first.

Option 2: Download the MSI installer

If you prefer a normal installer:

1. Download the 64-bit MSI (recommended) or the 32-bit MSI.
2. Run it, accept the license, and select Install. Choose Yes when Windows asks to allow changes.
3. Close and reopen PowerShell or Command Prompt.

The 64-bit MSI has been available since version 2.51.0 and Microsoft recommends it for better performance. Installing it automatically removes an existing 32-bit install, but you'll need to reinstall any CLI extensions afterwards.

To install the MSI silently from PowerShell (handy for scripts and VM images), open PowerShell as administrator and run:

$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest -Uri https://aka.ms/installazurecliwindowsx64 -OutFile .\AzureCLI.msi
Start-Process msiexec.exe -Wait -ArgumentList '/I', 'AzureCLI.msi', '/quiet'
Remove-Item .\AzureCLI.msi

Microsoft's own example uses the 32-bit URL (https://aka.ms/installazurecliwindows); I've swapped in the 64-bit one here. For a specific version, download it directly using this URL pattern:

https://azcliprod.blob.core.windows.net/msi/azure-cli-`<version>`-x64.msi

Option 3: ZIP package (no admin rights)

The ZIP package is useful on locked-down machines where you can't run an installer. Microsoft still lists it as preview, and it's 64-bit only.

1. Download the latest ZIP and extract it to a folder you control, for example C:\Tools\azure-cli.
2. Add that folder's bin subfolder to your user Path environment variable (Start, search for "environment variables", Edit the system environment variables, Environment Variables, then edit Path under your user variables).
3. Restart your terminal and run az version.

You can also run it without touching Path:

C:\Tools\azure-cli\bin\az.cmd version

To update a ZIP install, delete the old folder and extract the new version to the same location.

Install Azure CLI on macOS

On macOS, Microsoft supports Homebrew. The package requires macOS 13 or later. If you don't have Homebrew yet, install it from brew.sh first.

brew update && brew install azure-cli

Homebrew pulls in everything the CLI needs. Starting with version 2.85.0 (preview), the CLI is also published as a Homebrew cask, which Microsoft describes as a more secure install method that also supports broker-based sign-in. To install the cask explicitly:

brew update && brew install --cask azure-cli

If you installed the CLI before it moved to the cask, uninstall and reinstall once so future upgrades come from the cask:

brew uninstall azure-cli
brew update
brew install azure-cli

Install Azure CLI on Linux

Use your distribution's package manager. It's the method Microsoft recommends, and it keeps the CLI updated along with the rest of your system.

Ubuntu and Debian: one-command install script

The Azure CLI team maintains a script that adds the Microsoft repository and installs the package in one step:

curl -fsSL 'https://azurecliprod.blob.core.windows.net/$root/deb_install.sh' | sudo bash

If you'd rather read a script before piping it to sudo bash (a good habit), download it first with curl -fsSL -o deb_install.sh and the same URL, read it, then run it.

The apt packages are built for x86_64 and ARM64 and are tested on Debian 11 and 12, and Ubuntu 22.04, 24.04 and 26.04.

Ubuntu and Debian: manual apt install

This is what the script does, step by step. I use this version on servers where I want to see each change.

1. Install the packages the setup needs:

sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release

2. Download and install the Microsoft signing key:

sudo mkdir -p /etc/apt/keyrings
curl -sLS https://packages.microsoft.com/keys/microsoft.asc |
  gpg --dearmor | sudo tee /etc/apt/keyrings/microsoft.gpg > /dev/null
sudo chmod go+r /etc/apt/keyrings/microsoft.gpg

3. Add the Azure CLI repository:

AZ_DIST=$(lsb_release -cs)
echo "Types: deb
URIs: https://packages.microsoft.com/repos/azure-cli/
Suites: ${AZ_DIST}
Components: main
Architectures: $(dpkg --print-architecture)
Signed-by: /etc/apt/keyrings/microsoft.gpg" | sudo tee /etc/apt/sources.list.d/azure-cli.sources

4. Install the azure-cli package:

sudo apt-get update
sudo apt-get install azure-cli

To install a specific version, list what's available with apt-cache policy azure-cli, then install it by version and codename:

sudo apt-get install azure-cli=2.51.0-1~bullseye

RHEL, CentOS Stream and Fedora (dnf)

1. Import the Microsoft repository key. RHEL 10 and CentOS Stream 10 use the 2025 key:

sudo rpm --import https://packages.microsoft.com/keys/microsoft-2025.asc

Older versions use:

sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc

2. Add the packages-microsoft-prod repository for your version (run only the line that matches):

# RHEL 10
sudo dnf install -y https://packages.microsoft.com/config/rhel/10/packages-microsoft-prod.rpm
# CentOS Stream 10
sudo dnf install -y https://packages.microsoft.com/config/centos/10/packages-microsoft-prod.rpm
# RHEL 9 or CentOS Stream 9
sudo dnf install -y https://packages.microsoft.com/config/rhel/9.0/packages-microsoft-prod.rpm
# RHEL 8
sudo dnf install -y https://packages.microsoft.com/config/rhel/8/packages-microsoft-prod.rpm

3. Install the CLI:

sudo dnf install azure-cli

On systems without dnf, use yum with the same package name. Note that 2.38.2 was the last release for RHEL 7 and CentOS 7, so those systems won't get updates.

Microsoft's dnf instructions target RHEL and CentOS Stream. Fedora isn't listed by name, so if the packages-microsoft-prod route fails on your Fedora release, the Docker option below is the reliable fallback.

Other distributions

Microsoft also documents zypper for SLES and openSUSE and tdnf for Azure Linux on the Linux install page. The old generic InstallAzureCli script that worked on any distribution is no longer published on the Learn install pages (current or LTS), and it only ran on Python 3.8 to 3.10. I don't recommend it for new installs; use a package manager or Docker instead.

Run Azure CLI in Docker

If you don't want anything installed on the host, run the CLI in a container. Microsoft's current image is based on Azure Linux 3.0:

docker run -it mcr.microsoft.com/azure-cli:azurelinux3.0

To use your local SSH keys inside the container, mount your .ssh folder:

docker run -it --mount type=bind,src="$HOME"/.ssh,dst=/root/.ssh mcr.microsoft.com/azure-cli:azurelinux3.0

For pipelines, pin a version tag, for example mcr.microsoft.com/azure-cli:2.74.0-azurelinux3.0. The older Alpine-based image stopped at version 2.63.0 and no longer gets fixes, so move off it if you still use it.

To update, pull the latest image and recreate your containers. Don't store anything you care about inside a CLI container.

docker pull mcr.microsoft.com/azure-cli:latest

Use Azure CLI in Azure Cloud Shell (No Install)

Azure Cloud Shell is a browser-based terminal with the Azure CLI preinstalled and already signed in. It's what I point people to when they just need to run a few commands.

1. Sign in to the Azure portal and select the Cloud Shell icon in the top bar, or go straight to shell.azure.com.
2. The first time, choose Bash (PowerShell has the CLI too).
3. Choose whether to mount a storage account. Mounting one keeps your files between sessions; you can also continue without storage.
4. Run az version to see which CLI version Cloud Shell is running.

See Get started with Azure Cloud Shell for the storage options.

Verify the Installation

Open a new terminal window and run:

az version

You'll get JSON output with the azure-cli version, the core and telemetry versions, and any installed extensions. az --version works too.

The CLI installs here, which helps when you're debugging PATH problems:

Platform	Install location
Windows (64-bit)	C:\Program Files\Microsoft SDKs\Azure\CLI2
Windows (32-bit)	C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2
Ubuntu / Debian	/opt/az/
RHEL / CentOS Stream / Azure Linux	/lib64/az/

Your settings and tokens live in $HOME/.azure on Linux and macOS, and %USERPROFILE%\.azure on Windows.

Sign In with az login

az login

On Windows, az login uses the Windows sign-in broker (Web Account Manager). On macOS and Linux it opens your default browser. After you sign in, the CLI lists your subscriptions and lets you choose a default.

If there's no browser (an SSH session, a headless VM, a container), use the device code flow. The CLI prints a code; open https://aka.ms/devicelogin on any device, enter the code and sign in:

az login --use-device-code

Then check which subscription you're working in, and switch if needed:

az account show
az account list --output table
az account set --subscription "My Subscription"

Microsoft now requires multifactor authentication for user accounts signing in through the Azure CLI. If you have scripts that run az login with a username and password, move them to a service principal or managed identity. See Sign into Azure interactively using the Azure CLI for the full details.

Once you're signed in, my Azure CLI basics post covers the commands you'll use every day.

Practise it: the Deploy your first website with the Azure CLI lab on CloudLearn gives you a real Azure environment to run az commands against, with nothing left running afterwards.

Update Azure CLI

The CLI can update itself (version 2.11.0 and later). This also updates installed extensions:

az upgrade

You can also update through the package manager you installed with:

Install method	Update command
Homebrew	brew update && brew upgrade azure-cli
apt	sudo apt-get update && sudo apt-get install --only-upgrade -y azure-cli
dnf	sudo dnf update azure-cli
MSI	Run the latest MSI again
ZIP	Replace the folder with the new version
Docker	docker pull mcr.microsoft.com/azure-cli:latest

Uninstall Azure CLI

Windows: open Settings > Apps > Installed apps (Windows 11) or Settings > Apps > Apps & features (Windows 10), search for Azure CLI, and uninstall Microsoft CLI 2.0 for Azure.

macOS:

brew uninstall azure-cli

Ubuntu and Debian:

sudo apt-get remove -y azure-cli
sudo rm /etc/apt/sources.list.d/azure-cli.sources
sudo rm /etc/apt/keyrings/microsoft.gpg
sudo apt autoremove

Only remove the signing key if you don't use other Microsoft packages from that repository.

RHEL and CentOS Stream:

sudo dnf remove azure-cli

Docker:

docker rmi mcr.microsoft.com/azure-cli

To remove your saved sign-in and settings too, delete the .azure folder. On macOS and Linux:

rm -rf ~/.azure

On Windows, delete the .azure folder in your user profile (%USERPROFILE%\.azure).

Fix Common Azure CLI Install Problems

"az is not recognized" or "command not found"

The most common cause is a terminal that was open before the install. Close every terminal window and open a new one. If you used the ZIP package, check that the bin folder is in your user Path.

Azure CLI is slow on Windows

You're probably on the 32-bit build. Run az --version to note your extensions, install the 64-bit MSI (it removes the 32-bit one), then reinstall your extensions with az extension add --name followed by the extension name.

"Unable to locate package azure-cli" on Ubuntu or Debian

The Microsoft repository isn't configured. Repeat steps 2 to 4 of the manual apt install, and check that /etc/apt/sources.list.d/azure-cli.sources exists.

Wrong codename on Linux Mint, elementary OS and other derivatives

Some Ubuntu-based distributions return their own codename from lsb_release -cs, so apt looks for a repository that doesn't exist. Edit /etc/apt/sources.list.d/azure-cli.sources and set the Suites: line to the Ubuntu codename your distribution is based on (for example jammy), then run sudo apt-get update again. Ubuntu releases older than Bionic and Debian older than Buster aren't supported.

Proxy blocks the download

On Windows, set the proxy under Settings > Network & internet > Proxy, and allow HTTPS to https://aka.ms/ and https://azcliprod.blob.core.windows.net/. On Linux and macOS, export HTTP_PROXY and HTTPS_PROXY in your shell, and allow HTTPS to https://packages.microsoft.com (Linux) or the Homebrew hosts (macOS). The CLI needs the same proxy settings to reach Azure after it's installed. The Azure CLI troubleshooting guide has the details.

Homebrew install can't find Python

There may be a version mismatch with Homebrew's Python. Microsoft's fix is to reinstall and relink the Python dependency:

brew update && brew install python@3.10 && brew upgrade python@3.10
brew link --overwrite python@3.10

Install fails inside WSL

If the same steps work on a normal Linux VM but fail in Windows Subsystem for Linux, the problem is usually WSL itself. Update WSL, or install the Windows version of the CLI and use it from PowerShell instead.

Which Install Method Should You Use?

• Your own Windows laptop: WinGet. One command, and it's easy to script for a new machine.
• Locked-down Windows without admin rights: the ZIP package.
• Mac: Homebrew.
• Linux servers and WSL: the apt or dnf package, so updates arrive with your normal patching.
• CI pipelines: the Docker image with a pinned version tag, or the CLI that's already on your hosted build agent.
• Just trying it out: Cloud Shell. No install, and you're already signed in.

Next Steps

• Learn the everyday commands in Azure CLI basics.
• Combine az with shell scripts using Bash scripting for beginners.
• Use the CLI to deploy infrastructure as code with your first Azure Bicep template.
• Bookmark Microsoft's Install the Azure CLI page and the release notes to see what changes each month.