Installing and Configuring Azure CLI: A Step-by-Step Guide

Before You Start

You need an Azure account with at least one subscription. If you do not have one yet, Microsoft offers a free account with credits for new users — see Azure Free Tier for what is included. You will also need a terminal: Command Prompt, PowerShell, Windows Terminal, or bash on macOS/Linux.

If you want to skip local installation entirely and use the CLI from a browser, Azure Cloud Shell provides a pre-configured environment with no install required. This page focuses on local installation for when you want the CLI available in your own environment.

Installing on Windows

Microsoft distributes an MSI installer for Windows that handles everything including adding the az command to your PATH.

1. Go to the Azure CLI documentation page and download the latest MSI installer for Windows (x64). The direct download URL from Microsoft’s documentation is straightforward to find by searching “install azure cli windows”.
2. Run the MSI. Accept the license agreement. Click through the installation wizard with default options. The installer adds Azure CLI to your PATH automatically.
3. Open a new Command Prompt, PowerShell, or Windows Terminal window (not an existing one — it needs to pick up the updated PATH).
4. Verify the install:

az --version

You should see output listing the CLI version number and versions of its Python dependencies. If you see “command not found” or “az is not recognized”, close all terminal windows and open a fresh one.

Alternative: Install via winget

If you have the Windows Package Manager (winget) available (built into Windows 11 and available for Windows 10), you can install from the command line:

winget install --exact --id Microsoft.AzureCLI

This installs the same CLI as the MSI and adds it to your PATH.

Windows Subsystem for Linux (WSL)

If you work primarily in WSL, install the CLI inside the WSL environment using the Linux instructions below rather than the Windows MSI. The two installations are independent — commands you run inside WSL use the WSL installation; commands in a native Windows terminal use the Windows installation.

Installing on macOS

The recommended method on macOS is Homebrew:

brew update && brew install azure-cli

If you do not have Homebrew, install it first from brew.sh. After the CLI installs, verify it:

az --version

To update the CLI later:

brew upgrade azure-cli

Homebrew puts the CLI binary in /usr/local/bin (Intel Macs) or /opt/homebrew/bin (Apple Silicon Macs). Both should be on your PATH automatically if Homebrew is set up correctly.

Installing on Linux

Ubuntu and Debian (apt)

Microsoft maintains an official apt repository for Azure CLI. The quickest way to install is:

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

This script adds the Microsoft signing key, adds the repository to your sources list, and installs the CLI in one step. After installation, verify:

az --version

To update later:

sudo apt-get update && sudo apt-get install --only-upgrade azure-cli

Red Hat, CentOS, Fedora (dnf/yum)

Import the Microsoft GPG key and add the repository:

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

# For Fedora / RHEL 8+
sudo dnf install -y https://packages.microsoft.com/config/rhel/8/packages-microsoft-prod.rpm
sudo dnf install azure-cli

Adjust the RHEL version in the URL to match your system (7, 8, or 9).

Any Linux: pip install

If your distribution is not listed or you want to install without root access:

pip install azure-cli

This works in virtual environments. The pip installation does not add shell completions automatically, but the CLI itself functions the same way.

Authenticating: az login

With the CLI installed, the next step is to authenticate your terminal session with your Azure account. There are two main login methods.

Interactive Browser Login

This is the standard method for local development machines:

az login

The CLI opens a browser window pointing to a Microsoft sign-in page. You sign in with the Microsoft account or work/school account that has access to your Azure subscription. After successful sign-in, the browser shows a confirmation message and the terminal displays a JSON list of your accessible subscriptions.

If the CLI cannot open a browser automatically (for example, the command is running inside a terminal multiplexer that cannot launch a GUI), you can pass the URL from the error message manually to a browser.

Device Code Login (Headless Environments)

When there is no browser available — a remote server, a Docker container, WSL without a display server, or CI/CD — use device code flow:

az login --use-device-code

The terminal prints output similar to:

To sign in, use a web browser to open the page https://microsoft.com/devicelogin
and enter the code ABCDE1234 to authenticate.

Open that URL on any device — your phone, a different computer, anything with a browser — enter the displayed code, and sign in. The terminal polls until authentication completes, then shows your subscriptions. This flow is useful for initial setup on servers where you can use a different device as the browser.

Setting Your Subscription

After login, the CLI shows all subscriptions your account can access. If you have multiple subscriptions, you need to tell the CLI which one to use. Skipping this step is the most common source of confusion for new users.

First, list your subscriptions:

az account list --output table

The output shows each subscription’s name, ID, and whether it is currently the default. Find the subscription you want to work in, then set it:

az account set --subscription "my-dev-subscription"

You can use the subscription name (in quotes if it has spaces) or the subscription ID (the UUID). Confirm the change:

az account show --output table

This one-line output confirms the name, ID, and tenant of the currently active subscription. Make this your habit at the start of every CLI session. See Azure Subscriptions for more context on how subscriptions work.

Configuring Defaults

To avoid typing the same flags on every command, you can configure defaults:

az configure --defaults location=eastus group=myapp-dev-rg

After this, commands that require a location or resource group will use these values automatically unless you override them explicitly with a flag. To see what defaults are currently configured:

az configure --list-defaults

To clear a default, set it to an empty string:

az configure --defaults group=

From Fresh Install to First Resource: A Complete Walkthrough

Here is the complete sequence from a fresh install to creating and listing a resource group — the typical starting point for any new project:

# Step 1: Verify the install
az --version

# Step 2: Log in
az login

# Step 3: See your subscriptions
az account list --output table

# Step 4: Set the correct subscription
az account set --subscription "my-dev-subscription"

# Step 5: Confirm the active subscription
az account show --output table

# Step 6: Create a resource group in East US
az group create --name myapp-dev-rg --location eastus

# Step 7: Confirm the resource group exists
az group list --output table

# Step 8: List all resources in the group (empty for now)
az resource list --resource-group myapp-dev-rg --output table

At this point you have a working CLI session, the right subscription selected, a resource group ready to receive resources, and you have confirmed the CLI can reach Azure successfully. Every subsequent Azure CLI guide builds on these eight steps.

Shell Tab Completion

The Azure CLI supports tab completion in bash and zsh. On bash, add the following to your ~/.bashrc:

source /etc/bash_completion.d/azure-cli

On zsh, add this to your ~/.zshrc:

autoload -U +X bashcompinit && bashcompinit
source /etc/bash_completion.d/azure-cli

After reloading your shell, pressing Tab after az will show available command groups, and pressing Tab after a partial command like az storage ac will autocomplete to az storage account. This makes the CLI much faster to use and easier to learn.