From bfdaab0f197c1ca7d27a6605768063d06e8188f0 Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" <6719572+mikefrobbins@users.noreply.github.com> Date: Tue, 24 Mar 2026 11:10:50 -0500 Subject: [PATCH 1/6] Added macos install cask & tarball preview article --- .../install-azure-cli-macos-preview.md | 281 ++++++++++++++++++ .../Latest-version/zone-pivot-groups.yml | 8 + 2 files changed, 289 insertions(+) create mode 100644 docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md diff --git a/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md b/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md new file mode 100644 index 0000000000..c9093085a0 --- /dev/null +++ b/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md @@ -0,0 +1,281 @@ +--- +title: Install Azure CLI on macOS using Homebrew Cask or Tarball preview +description: Install Azure CLI on macOS using Homebrew Cask or Tarball. Includes offline setup, upgrade, uninstall, and migration guidance. +ms.service: azure-cli +ms.custom: devx-track-azurecli +zone_pivot_group_filename: azure/zone-pivot-groups.json +zone_pivot_groups: cli-macos-installation-method +keywords: Install azure cli, azure cli macos, macos cli, install azure cli macos +--- + +# Install Azure CLI on macOS using Homebrew Cask or Tarball preview + +Azure CLI is a cross-platform command-line tool used to manage Azure resources from the command line +or through scripts. + +On macOS, Azure CLI is transitioning to a new installation model that provides greater flexibility +across environments. This model includes: + +- Homebrew Cask (recommended for most users) +- Tarball (recommended for offline, restricted, or custom environments) + +This experience is currently in preview and will become the standard installation approach in a +future release. + +> [!NOTE] +> For the current stable installation guidance, see [Install Azure CLI on macOS][01]. + +## What is changing + +Azure CLI installation on macOS is moving away from the Homebrew formula to a more maintainable and +flexible model. + +- Current method: `brew install azure-cli` +- New methods: + - `brew install --cask azure-cli` + - Tarball-based installation + +During the transition period, both installation methods are supported. The Homebrew formula will be +deprecated in a future release. + +This change improves consistency across environments and provides better support for scenarios such +as offline installation and controlled deployment environments. + +## Choose an installation method + +Use the following guidance to select the installation method that best fits your scenario: + +| Scenario | Recommended method | +| -------------------------------- | ------------------ | +| Most users | Homebrew Cask | +| Offline or air-gapped systems | Tarball | +| Custom install location required | Tarball | + +::: zone pivot="cask" + +## Install Azure CLI using Homebrew Cask + +Homebrew provides the simplest and most maintainable installation experience for Azure CLI on macOS. +It handles installation, upgrades, and removal using standard package management workflows. + +### Prerequisites + +- macOS (Apple Silicon or Intel) +- [Homebrew][02] installed + +If Azure CLI is already installed using the Homebrew formula, uninstall it before proceeding to +avoid conflicts: + +```bash +brew uninstall azure-cli +``` + +### Install Azure CLI + +```bash +brew update && brew install --cask azure-cli +``` + +This installs Azure CLI using the Homebrew Cask, which is the preferred installation method going +forward. + +### Verify installation + +After installation, confirm Azure CLI is available: + +```bash +az --version +``` + +## Upgrade Azure CLI + +To upgrade to the latest version: + +```bash +brew upgrade --cask azure-cli +``` + +## Uninstall Azure CLI + +To remove Azure CLI: + +```bash +brew uninstall --cask azure-cli +``` + +::: zone-end + +::: zone pivot="tarball" + +## Install Azure CLI using a Tarball + +Use this method if: + +- Homebrew isn't available +- Internet access is restricted +- You need full control over the installation location + +This method is commonly used in enterprise, regulated, or air-gapped environments. + +### Prerequisites + +- macOS (Apple Silicon or Intel) +- Python 3.13 installed using your preferred method (for example, `python.org` or `pyenv`) + +## Determine your architecture + +Before downloading the Tarball, determine your system architecture: + +```bash +uname -m +``` + +- `arm64` - Apple Silicon +- `x86_64` - Intel + +Selecting the correct architecture ensures compatibility and optimal performance. + +### Download the Tarball + +On a machine with internet access, download the desired Azure CLI release from: + +[https://github.com/Azure/azure-cli/releases][03] + +Example: + +```bash +# Replace and +curl -L -o azure-cli--macos-.tar.gz \ + https://github.com/Azure/azure-cli/releases/download/azure-cli-/azure-cli--macos-.tar.gz +``` + +> [!TIP] +> For offline environments, transfer the Tarball to the target system using a secure method such as +> removable media or secure file transfer. + +### Extract to installation directory + +Choose a directory where Azure CLI should be installed: + +```bash +sudo mkdir -p /target_directory_path +sudo tar -xzf azure-cli--macos-.tar.gz -C /target_directory_path +``` + +### Configure environment variables + +Azure CLI requires access to a Python runtime. Configure your environment to point to Python and the +Azure CLI binaries. + +Add the following to your shell profile (`~/.zshrc` or `~/.bashrc`): + +```bash +export AZ_PYTHON="/path_to_python" +export PATH="/target_directory_path/bin:$PATH" +``` + +Reload your shell configuration: + +```bash +source ~/.zshrc +``` + +### Verify installation + +```bash +az --version +``` + +## Upgrade Azure CLI + +To upgrade Azure CLI in an offline environment, download a newer Tarball and extract it over the +existing installation: + +```bash +sudo tar -xzf azure-cli--macos-.tar.gz -C /target_directory_path +``` + +### Uninstall Azure CLI + +Remove the installation directory: + +```bash +sudo rm -rf /target_directory_path +``` + +Then remove the `AZ_PYTHON` and `PATH` entries from your shell profile. + +::: zone-end + +## Troubleshooting + +If you encounter a problem when installing the Azure CLI through Homebrew, here are some common +errors. If you experience a problem not covered here, [file an issue on GitHub][04]. + +### Azure CLI not found + +Ensure your PATH includes the installation directory: + +```bash +echo $PATH +``` + +### Completion isn't working + +The Homebrew formula of Azure CLI installs a completion file named `az` in the Homebrew-managed +completions directory (default location is `/usr/local/etc/bash_completion.d/`). To enable +completion, follow [Homebrew's instructions][05]. + +For Zsh, add the following two lines to the bottom of your `.zshrc` file, then save and reload your +Zsh profile. + +```bash +autoload bashcompinit && bashcompinit +source $(brew --prefix)/etc/bash_completion.d/az +``` + +### Unable to find Python or installed packages + +There might be a minor version mismatch or other issue during homebrew installation. Azure CLI +doesn't use a Python virtual environment, so it relies on finding the installed Python version. A +possible fix is to install and relink the `python@3.13` dependency from Homebrew. + +```bash +brew update && brew install python@3.13 && brew upgrade python@3.13 +brew link --overwrite python@3.13 +``` + +### Proxy blocks connection + +You might be unable to get resources from Homebrew unless you configure it to use your proxy. Follow +the [Homebrew proxy configuration instructions][06]. + +> [!IMPORTANT] +> If you are behind a proxy, `HTTP_PROXY` and `HTTPS_PROXY` must be set to connect to Azure services +> with the Azure CLI. If you don't use basic auth, you should export these variables in your +> `.bashrc` file. Always follow your business' security policies and the requirements of your system +> administrator. + +To get the bottle resources from Homebrew, your proxy needs to allow HTTPS connections to the +following addresses: + +- `https://formulae.brew.sh` +- `https://homebrew.bintray.com` + +## Next Steps + +Now that you installed the Azure CLI on macOS, take a short tour of its features and common +commands. + +> [!div class="nextstepaction"] +> [Get started with the Azure CLI][07] + + + +[01]: install-azure-cli-macos.md +[02]: https://brew.sh/ +[03]: https://github.com/Azure/azure-cli/releases +[04]: https://github.com/Azure/azure-cli/issues +[05]: https://docs.brew.sh/Shell-Completion +[06]: https://docs.brew.sh/Manpage#using-homebrew-behind-a-proxy +[07]: get-started-with-azure-cli.md diff --git a/docs-ref-conceptual/Latest-version/zone-pivot-groups.yml b/docs-ref-conceptual/Latest-version/zone-pivot-groups.yml index 82dc7c5d53..dc426fcf52 100644 --- a/docs-ref-conceptual/Latest-version/zone-pivot-groups.yml +++ b/docs-ref-conceptual/Latest-version/zone-pivot-groups.yml @@ -24,3 +24,11 @@ groups: title: Microsoft Installer (MSI) with PowerShell - id: zip title: ZIP Package +- id: cli-macos-installation-method + title: Azure CLI installation method for macOS + prompt: Choose an installation method + pivots: + - id: cask + title: Homebrew Cask + - id: tarball + title: Tarball From 52c299586b1b055edd028e2bbc63dda3e787a2fc Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" <6719572+mikefrobbins@users.noreply.github.com> Date: Tue, 24 Mar 2026 12:16:08 -0500 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../install-azure-cli-macos-preview.md | 22 +++++++++---------- 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md b/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md index c9093085a0..02d16ab29e 100644 --- a/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md +++ b/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md @@ -10,8 +10,7 @@ keywords: Install azure cli, azure cli macos, macos cli, install azure cli macos # Install Azure CLI on macOS using Homebrew Cask or Tarball preview -Azure CLI is a cross-platform command-line tool used to manage Azure resources from the command line -or through scripts. +Azure CLI is a cross-platform command-line tool for managing Azure resources interactively or through scripts. On macOS, Azure CLI is transitioning to a new installation model that provides greater flexibility across environments. This model includes: @@ -122,7 +121,7 @@ This method is commonly used in enterprise, regulated, or air-gapped environment - macOS (Apple Silicon or Intel) - Python 3.13 installed using your preferred method (for example, `python.org` or `pyenv`) -## Determine your architecture +### Determine your architecture Before downloading the Tarball, determine your system architecture: @@ -174,10 +173,8 @@ export AZ_PYTHON="/path_to_python" export PATH="/target_directory_path/bin:$PATH" ``` -Reload your shell configuration: +Reload the shell configuration file you updated: -```bash -source ~/.zshrc ``` ### Verify installation @@ -195,7 +192,7 @@ existing installation: sudo tar -xzf azure-cli--macos-.tar.gz -C /target_directory_path ``` -### Uninstall Azure CLI +## Uninstall Azure CLI Remove the installation directory: @@ -209,8 +206,9 @@ Then remove the `AZ_PYTHON` and `PATH` entries from your shell profile. ## Troubleshooting -If you encounter a problem when installing the Azure CLI through Homebrew, here are some common -errors. If you experience a problem not covered here, [file an issue on GitHub][04]. +If you encounter a problem when installing or using the Azure CLI with either Homebrew Cask or the +Tarball method, here are some common errors (many of which are specific to Homebrew). If you +experience a problem not covered here, [file an issue on GitHub][04]. ### Azure CLI not found @@ -222,9 +220,9 @@ echo $PATH ### Completion isn't working -The Homebrew formula of Azure CLI installs a completion file named `az` in the Homebrew-managed -completions directory (default location is `/usr/local/etc/bash_completion.d/`). To enable -completion, follow [Homebrew's instructions][05]. +The Azure CLI Homebrew installation (whether via formula or cask) provides a completion file named +`az` in Homebrew's managed completions directory. To enable completion, follow +[Homebrew's instructions][05]. For Zsh, add the following two lines to the bottom of your `.zshrc` file, then save and reload your Zsh profile. From da0b7e74f72323fd4d481472bd47c5e10967911f Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" <6719572+mikefrobbins@users.noreply.github.com> Date: Wed, 25 Mar 2026 14:01:49 -0500 Subject: [PATCH 3/6] Updates based on peer review --- .../install-azure-cli-macos-preview.md | 63 ++++++++++--------- 1 file changed, 35 insertions(+), 28 deletions(-) diff --git a/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md b/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md index c9093085a0..13baf6bb39 100644 --- a/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md +++ b/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md @@ -25,6 +25,12 @@ future release. > [!NOTE] > For the current stable installation guidance, see [Install Azure CLI on macOS][01]. +Why use Homebrew Cask? + +- Simplest install and upgrade experience +- Automatically manages dependencies +- Aligns with the future supported installation model + ## What is changing Azure CLI installation on macOS is moving away from the Homebrew formula to a more maintainable and @@ -63,8 +69,8 @@ It handles installation, upgrades, and removal using standard package management - macOS (Apple Silicon or Intel) - [Homebrew][02] installed -If Azure CLI is already installed using the Homebrew formula, uninstall it before proceeding to -avoid conflicts: +If Azure CLI is already installed using the Homebrew `brew install azure-cli` formula, uninstall it +before proceeding to avoid conflicts: ```bash brew uninstall azure-cli @@ -122,45 +128,46 @@ This method is commonly used in enterprise, regulated, or air-gapped environment - macOS (Apple Silicon or Intel) - Python 3.13 installed using your preferred method (for example, `python.org` or `pyenv`) -## Determine your architecture +### Download the tarball -Before downloading the Tarball, determine your system architecture: +On a machine with internet access, you can automatically download the latest Azure CLI tarball for +your architecture: ```bash -uname -m +ARCH=$(uname -m) +VER=$(curl -s https://api.github.com/repos/Azure/azure-cli/releases/latest | grep tag_name | cut -d '"' -f4 | sed 's/azure-cli-//') +curl -L -o az.tar.gz "https://github.com/Azure/azure-cli/releases/download/azure-cli-$VER/azure-cli-$VER-macos-$ARCH.tar.gz" ``` -- `arm64` - Apple Silicon -- `x86_64` - Intel - -Selecting the correct architecture ensures compatibility and optimal performance. - -### Download the Tarball - -On a machine with internet access, download the desired Azure CLI release from: +This script detects your architecture and downloads the latest Azure CLI tarball from the Azure CLI +releases page. -[https://github.com/Azure/azure-cli/releases][03] +- `arm64` indicates Apple Silicon +- `x86_64` indicates Intel -Example: - -```bash -# Replace and -curl -L -o azure-cli--macos-.tar.gz \ - https://github.com/Azure/azure-cli/releases/download/azure-cli-/azure-cli--macos-.tar.gz -``` +Selecting the correct architecture ensures compatibility and optimal performance. > [!TIP] -> For offline environments, transfer the Tarball to the target system using a secure method such as -> removable media or secure file transfer. +> For offline environments, run this command on a machine with internet access, then transfer the +> downloaded tarball to the target system. ### Extract to installation directory Choose a directory where Azure CLI should be installed: -```bash -sudo mkdir -p /target_directory_path -sudo tar -xzf azure-cli--macos-.tar.gz -C /target_directory_path -``` +- User-level install (recommended): + + ```bash + mkdir -p $HOME/lib/azure-cli + tar -xzf az.tar.gz -C $HOME/lib/azure-cli + ``` + +- System-level install: + + ```bash + sudo mkdir -p /opt/azure-cli + sudo tar -xzf az.tar.gz -C /opt/azure-cli + ``` ### Configure environment variables @@ -192,7 +199,7 @@ To upgrade Azure CLI in an offline environment, download a newer Tarball and ext existing installation: ```bash -sudo tar -xzf azure-cli--macos-.tar.gz -C /target_directory_path +sudo tar -xzf az.tar.gz -C /target_directory_path ``` ### Uninstall Azure CLI From 0f1ae683974f13e2b058b519b35883e0f5dda54c Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" <6719572+mikefrobbins@users.noreply.github.com> Date: Mon, 6 Apr 2026 16:53:55 -0500 Subject: [PATCH 4/6] Updates based on peer review --- .../install-azure-cli-macos-preview.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md b/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md index 0f7c1b4ff1..ce278bcdaf 100644 --- a/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md +++ b/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md @@ -10,7 +10,8 @@ keywords: Install azure cli, azure cli macos, macos cli, install azure cli macos # Install Azure CLI on macOS using Homebrew Cask or Tarball preview -Azure CLI is a cross-platform command-line tool for managing Azure resources interactively or through scripts. +Azure CLI is a cross-platform command-line tool for managing Azure resources interactively or +through scripts. On macOS, Azure CLI is transitioning to a new installation model that provides greater flexibility across environments. This model includes: @@ -43,6 +44,12 @@ flexible model. During the transition period, both installation methods are supported. The Homebrew formula will be deprecated in a future release. +On macOS, Azure CLI is evolving to support more secure authentication experiences, including +broker-based authentication. These capabilities require a cask-based installation model. As a +result, we're transitioning from Homebrew Core to Homebrew Cask. This change doesn't remove or limit +any existing Azure CLI functionality. Homebrew Cask remains fully compatible with all current Azure +CLI features and versions. + This change improves consistency across environments and provides better support for scenarios such as offline installation and controlled deployment environments. @@ -154,20 +161,11 @@ Selecting the correct architecture ensures compatibility and optimal performance Choose a directory where Azure CLI should be installed: -- User-level install (recommended): - ```bash mkdir -p $HOME/lib/azure-cli tar -xzf az.tar.gz -C $HOME/lib/azure-cli ``` -- System-level install: - - ```bash - sudo mkdir -p /opt/azure-cli - sudo tar -xzf az.tar.gz -C /opt/azure-cli - ``` - ### Configure environment variables Azure CLI requires access to a Python runtime. Configure your environment to point to Python and the From 717fe851e72edd56903edf539498605a627fb4b3 Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" <6719572+mikefrobbins@users.noreply.github.com> Date: Tue, 7 Apr 2026 12:03:57 -0500 Subject: [PATCH 5/6] Added toc entry and other links --- .../Latest-version/install-azure-cli-macos-preview.md | 2 +- docs-ref-conceptual/Latest-version/install-azure-cli.md | 2 ++ docs-ref-conceptual/Latest-version/toc.yml | 2 ++ 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md b/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md index ce278bcdaf..e04ff11816 100644 --- a/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md +++ b/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md @@ -42,7 +42,7 @@ flexible model. - Tarball-based installation During the transition period, both installation methods are supported. The Homebrew formula will be -deprecated in a future release. +deprecated in our June release. On macOS, Azure CLI is evolving to support more secure authentication experiences, including broker-based authentication. These capabilities require a cask-based installation model. As a diff --git a/docs-ref-conceptual/Latest-version/install-azure-cli.md b/docs-ref-conceptual/Latest-version/install-azure-cli.md index f08fa42794..5ac2ff80f7 100644 --- a/docs-ref-conceptual/Latest-version/install-azure-cli.md +++ b/docs-ref-conceptual/Latest-version/install-azure-cli.md @@ -29,6 +29,7 @@ in a Docker container and Azure Cloud Shell. - [Install on Azure Linux with tdnf][07] - [Install on macOS][18] +- [Install on macOS using Homebrew Cask or Tarball preview][21] - [Run in Docker container][20] @@ -94,3 +95,4 @@ information on managing extensions, see [Use and manage extensions with the Azur [18]: install-azure-cli-macos.md [19]: install-azure-cli-windows.md [20]: run-azure-cli-docker.md +[21]: install-azure-cli-macos-preview.md diff --git a/docs-ref-conceptual/Latest-version/toc.yml b/docs-ref-conceptual/Latest-version/toc.yml index 3a2ef9a223..dfd7fe9c39 100644 --- a/docs-ref-conceptual/Latest-version/toc.yml +++ b/docs-ref-conceptual/Latest-version/toc.yml @@ -23,6 +23,8 @@ items: href: release-notes-azure-cli.md - name: Upcoming breaking changes href: upcoming-breaking-changes.md + - name: Install Azure CLI on macOS using Homebrew Cask or Tarball preview + href: install-azure-cli-macos-preview.md - name: Impact of MFA in automation href: authenticate-azure-cli-mfa.md - name: MSAL-based Azure CLI From 0170b258808711ca7cb94a6d90326e57efc44125 Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" <6719572+mikefrobbins@users.noreply.github.com> Date: Tue, 7 Apr 2026 15:51:32 -0500 Subject: [PATCH 6/6] Updates name of cask package --- .../Latest-version/install-azure-cli-macos-preview.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md b/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md index e04ff11816..8cccfa71d4 100644 --- a/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md +++ b/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md @@ -38,7 +38,7 @@ flexible model. - Current method: `brew install azure-cli` - New methods: - - `brew install --cask azure-cli` + - `brew install --cask azure-cli-preview` - Tarball-based installation During the transition period, both installation methods are supported. The Homebrew formula will be @@ -85,7 +85,7 @@ brew uninstall azure-cli ### Install Azure CLI ```bash -brew update && brew install --cask azure-cli +brew update && brew install --cask azure-cli-preview ``` This installs Azure CLI using the Homebrew Cask, which is the preferred installation method going @@ -104,7 +104,7 @@ az --version To upgrade to the latest version: ```bash -brew upgrade --cask azure-cli +brew upgrade --cask azure-cli-preview ``` ## Uninstall Azure CLI @@ -112,7 +112,7 @@ brew upgrade --cask azure-cli To remove Azure CLI: ```bash -brew uninstall --cask azure-cli +brew uninstall --cask azure-cli-preview ``` ::: zone-end