AboutFree templates
How-to · Azure

Install the Azure CLI and sign in

At the end you will have the az command working on your PC or Mac, be signed in to your Azure tenant and have the right subscription selected. If you cannot install software, use Azure Cloud Shell instead.

Updated 9 steps5 official sources
Start hereBack to the playbook
Before you start

What you need before step 1

Applies to: Azure CLI 2.x on Windows 10/11, macOS 13 or later and supported Linux distributions (as documented by Microsoft)

Admin roles you need

  • Local administrator on Windows to run the MSI or the documented PowerShell install (the script is run "as administrator")
  • An account that can run sudo on Linux; an admin account on macOS for Homebrew
  • A Microsoft Entra ID account with at least one Azure role assignment on the subscription you want to manage (az login only lists subscriptions you can access)

Licences

None needed.

Download

Azure CLI MSI for Windows (64-bit)Microsoft recommends the 64-bit MSI for better performance. 32-bit: https://aka.ms/installazurecliwindowshttps://aka.ms/installazurecliwindowsx64Download

Install instructions

Install the Azure CLI on Windows (Microsoft Learn)Lists the MSI, ZIP and WinGet optionshttps://learn.microsoft.com/en-us/cli/azure/install-azure-cli-windows?view=azure-cli-latestInstall steps
Install the Azure CLI on macOS (Microsoft Learn)Uses Homebrew. Install Homebrew first from https://docs.brew.sh/Installation.htmlhttps://learn.microsoft.com/en-us/cli/azure/install-azure-cli-macos?view=azure-cli-latestInstall steps
Install the Azure CLI on Linux (Microsoft Learn)apt, dnf, zypper and tdnf instructions plus the Debian/Ubuntu install scripthttps://learn.microsoft.com/en-us/cli/azure/install-azure-cli-linux?view=azure-cli-latestInstall steps

Also have ready

  • Internet access to https://aka.ms/ and https://azcliprod.blob.core.windows.net/ (Microsoft lists these for the Windows installer). If you are behind a proxy, set HTTP_PROXY and HTTPS_PROXY.
  • macOS 13 or later for the Homebrew package
  • A web browser on the same machine for interactive sign-in, or a second device for the device code flow
Step by step

9 steps

  1. 1

    Install on Windows with WinGet (option A)

    Where: Windows PC: right-click Start and select Terminal (Admin) or Windows PowerShell (Admin)

    Type the command below and press Enter. Microsoft notes that --exact makes sure the official Azure CLI package is installed. Accept the source agreement if WinGet asks.

    winget install --exact --id Microsoft.AzureCLI
    You should see: WinGet downloads and installs Microsoft Azure CLI and reports "Successfully installed".
  2. 2

    Or install on Windows with the MSI (option B)

    Where: Windows PC, in Microsoft Edge, then the downloaded installer

    Go to https://aka.ms/installazurecliwindowsx64 to download the 64-bit MSI. Open the downloaded file and follow the installer prompts to the end. To do the same silently, run the PowerShell commands below in an elevated PowerShell window (Microsoft's documented script uses the 32-bit link; swap in the x64 link if you prefer).

    $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
    You should see: The installer completes. Microsoft CLI 2.0 for Azure appears in Settings > Apps > Installed apps.
  3. 3

    Or install on macOS with Homebrew

    Where: Mac: Finder > Applications > Utilities > Terminal

    If Homebrew is not installed, install it first from https://docs.brew.sh/Installation.html. Then run the command below.

    brew update && brew install azure-cli
    You should see: Homebrew finishes with no errors and the az command is available in Terminal.
  4. 4

    Or install on Debian or Ubuntu Linux

    Where: Linux terminal (bash) on Debian 11/12 or Ubuntu 22.04/24.04/26.04

    Run Microsoft's install script. If you want to read the script first, download it with curl and open it in a text editor before running it. For RHEL, SUSE or Azure Linux use the dnf, zypper or tdnf steps on the Linux install page listed above.

    curl -fsSL 'https://azurecliprod.blob.core.windows.net/$root/deb_install.sh' | sudo bash
    You should see: The script adds the Microsoft repository and installs the azure-cli package.
  5. 5

    Close and reopen the terminal, then check the version

    Where: A new PowerShell, Command Prompt or Terminal window

    Close every terminal window you had open during the install and open a new one. Microsoft says the most common cause of az not being found is not restarting the terminal. Then type the command below.

    az version
    You should see: JSON output listing "azure-cli" and its version number, plus "azure-cli-core".
  6. 6

    Sign in to Azure

    Where: The same terminal window

    Type az login. On Windows 10/11 and Windows Server 2019 or later the Azure CLI uses Web Account Manager (WAM) and shows a Windows sign-in window. On macOS and Linux it opens your default browser. Sign in with your work account and complete MFA. If no browser can open (for example over SSH), use the device code option, then open https://aka.ms/devicelogin on any device and enter the code shown.

    az login
az login --use-device-code
    You should see: If you have access to more than one subscription you see "Select a subscription and tenant (Type a number or Enter for no changes):" with a numbered list.
  7. 7

    Sign in to a specific tenant (only if you have several)

    Where: The same terminal window

    If your account is a guest in other tenants, sign in to the right one with --tenant, using the tenant ID or its .onmicrosoft.com domain. Microsoft notes that in some environments you must turn off the subscription selector first.

    az config set core.login_experience_v2=off
az login --tenant contoso.onmicrosoft.com
    You should see: Sign-in completes and the subscriptions for that tenant are listed.
  8. 8

    Select the subscription to work in

    Where: The same terminal window

    Commands run against the selected subscription. Change it at any time with az account set, using the subscription ID or name.

    az account set --subscription "00000000-0000-0000-0000-000000000000"
    You should see: The command returns no output. Later az commands run against that subscription.
  9. 9

    Use Azure Cloud Shell if you cannot install anything

    Where: Azure portal (https://portal.azure.com) > Cloud Shell icon in the top bar

    Microsoft describes Cloud Shell as a browser-based shell with no installation required. It supports Bash and PowerShell and comes with the latest Azure CLI preinstalled. Select the Cloud Shell icon, choose Bash or PowerShell and run az commands there.

    az version
    You should see: A shell pane opens at the bottom of the portal and az version returns the installed version.
From experience

Expert tips

Confirm the subscription before every change

Since version 2.61.0 the CLI asks you to pick a subscription at sign-in, and every command runs against it. Run az account show --output table before you create or delete anything, and switch with az account set --subscription "<id>".

Automation needs a workload identity, not your account

Microsoft requires multifactor authentication for Microsoft Entra user accounts in the Azure CLI, so scripts that sign in with a user name and password fail with "interactive authentication is needed". Use a service principal or managed identity for scheduled migration jobs.

Turn off the Windows broker if sign-in misbehaves

From 2.61.0 Windows uses Web Account Manager (WAM). If you see "User cancelled the Accounts Control Operation", run az account clear, az config set core.enable_broker_on_windows=false, then az login to go back to browser sign-in.

Make output readable or scriptable

Add --output table for people and --output tsv with --query (JMESPath) for scripts, for example az vm list --query "[].name" --output tsv. Use az find vm to discover commands.

Use --debug to see what failed

When a command fails with a vague message, rerun it with --debug to see the REST calls and the real error from Azure, such as a missing role or a policy denial.

Check it worked

How to confirm it worked

  • Run az version in a new terminal. It returns JSON with the "azure-cli" version.

  • After az login, the list of subscriptions shows the one you selected with isDefault: true. On the next sign-in, the default subscription is marked with an asterisk.

Undo

How to reverse it

Rollback:

Sign out with az logout. To remove the CLI: on Windows 11 go to Start > Settings > Apps > Installed apps, search for Azure CLI and uninstall Microsoft CLI 2.0 for Azure, then delete C:\Users\<username>\.azure\msal_token_cache.bin or .json. On macOS run brew uninstall azure-cli then rm -rf ~/.azure. On Debian or Ubuntu run sudo apt-get remove -y azure-cli, remove /etc/apt/sources.list.d/azure-cli.sources and /etc/apt/keyrings/microsoft.gpg, then rm -rf ~/.azure.

Troubleshooting

Errors you might see

az is not recognised after installing (PATH variable not set)

Cause: Microsoft says the most common cause is not restarting the active terminal window after installation.

Fix: Close and reopen every terminal window, then run az version again.

The connection for this site isn't secure (during az login)

Cause: Microsoft Edge is the default browser and an HSTS policy blocks the localhost redirect.

Fix: Go to edge://net-internals/#hsts, add localhost under "Delete domain security policy" and select Delete, then run az login again.

User cancelled the Accounts Control Operation

Cause: A problem with the Web Account Manager (WAM) sign-in on Windows.

Fix: Run az account clear, then az config set core.enable_broker_on_windows=false, then az login to use browser sign-in instead.

Authentication failed against tenant

Cause: Your account belongs to more than one tenant.

Fix: Run az login with --tenant and the tenant ID or .onmicrosoft.com domain.

Unable to find Python or installed packages (macOS)

Cause: A version mismatch during the Homebrew install.

Fix: Run brew update && brew install python@3.10 && brew upgrade python@3.10, then brew link --overwrite python@3.10.

FAQ

Questions

How do I update the Azure CLI?

From version 2.11.0 run az upgrade, which also updates installed extensions. On macOS you can also run brew update && brew upgrade azure-cli.

Do I need the 64-bit or 32-bit MSI?

Microsoft recommends the 64-bit MSI for better performance. Use https://aka.ms/installazurecliwindowsx64.

Can I use the Azure CLI without installing it?

Yes. Azure Cloud Shell in the Azure portal has the latest Azure CLI preinstalled and works in a browser.

How do I see which subscriptions I can use?

The list appears when you run az login. If it is out of date, run az account clear and sign in again.

Sources

Official sources

Vendors change menus and requirements. Confirm on the source before you rely on a detail. Last checked 4 Nov 2026.

Microsoft Learn: Install the Azure CLI on WindowsMicrosoft Learn: Install Azure CLI on macOSMicrosoft Learn: Install the Azure CLI on LinuxMicrosoft Learn: Sign in with Azure CLI at a command lineMicrosoft Learn: Get started with Azure CLI