Repository navigation
Homebrew cask launcher asks for AZ_PYTHON when the Homebrew prefix is a symlink #34187
Description
Describe the bug
With the new Homebrew cask (brew install --cask azure-cli, 2.91.0), az fails on a Mac where the Homebrew prefix is a symlink (here /opt/homebrew -> /private/.bulk/opt/homebrew, which itself resolves to another volume):
Error: AZ_PYTHON not set.
For offline/tarball installs, set AZ_PYTHON to a Python 3.14 path.
Cause: scripts/release/standalone/templates/az_launcher.sh.in resolves its own path with cd -P (physical), then compares the result against literal prefixes:
if [[ "$SCRIPT_PATH" == /opt/homebrew/Caskroom/* ]] || \
[[ "$SCRIPT_PATH" == /usr/local/Caskroom/* ]] || \
[[ "$SCRIPT_PATH" == /home/linuxbrew/.linuxbrew/Caskroom/* ]]; thenbash -x shows the resolved path is /Volumes/Data/.bulk/opt/homebrew/Caskroom/azure-cli/2.91.0/bin/../libexec/bin/az, so INSTALLER=TARBALL and the launcher demands AZ_PYTHON, even though it is a cask install and python@3.14 is installed. The same happens with any custom Homebrew prefix.
To reproduce
- Make the Homebrew prefix a symlink to another location (for example, a prefix relocated to a second volume).
brew install --cask azure-cliaz version
Expected behavior
The cask install is detected and uses Homebrew's python@3.14, with no AZ_PYTHON needed.
Suggestions
- Detect a cask install by pattern rather than literal prefix, for example
*/Caskroom/azure-cli/*. Or compare against the physical path of$HOMEBREW_PREFIX, orbrew --prefix. - Minor: the first candidate,
opt/python@3.14/libexec/bin/python3, doesn't exist in Homebrew'spython@3.14(itslibexec/binhaspython, notpython3). Detection only works because of thebin/python3.14fallback.
Workaround
export AZ_PYTHON="$HOMEBREW_PREFIX/opt/python@3.14/bin/python3.14"
Environment
- azure-cli 2.91.0, Homebrew cask (Homebrew 7.0.8), macOS 27 on Apple silicon
- Homebrew prefix:
/opt/homebrew, a symlink to/private/.bulk/opt/homebrew
Activity
yonzhan commentedon Oct 8, 2026
Thank you for opening this issue, we will look into it.
x-engineering-agent commentedon Oct 8, 2026
Bug Analysis
Affected area: Homebrew cask / standalone packaging in
Azure/azure-cli, target branchdev. Target inference found no command module or extension; this is repository-owned launcher code, not an extensions-repository issue.Use this EXACT PR title:
[Packaging] Fix #34187:az version: Detect Homebrew casks with symlinked prefixesReported reproduction and expected result
Azure CLI 2.91.0 installed as a Homebrew cask, Homebrew 7.0.8, macOS 27 on Apple silicon. With the Homebrew prefix symlinked to a relocated directory, install the cask and invoke
az versionwithoutAZ_PYTHON. The reporter observesError: AZ_PYTHON not set.and the offline/tarball Python instruction, despite Homebrewpython@3.14being installed. The expected result is cask detection and use of the cask's Homebrew Python without requiringAZ_PYTHON.The issue supplies the exact command, error, expected behavior, versions and reproduction steps. No additional reporter information is blocking. Similar-issue lookup returned no candidates. This is source-supported analysis, not a locally executed reproduction.
Current source evidence
Inspected
devatfec1915074bb57bfcf40961fe0b982c1c96d7848:templates/az_launcher.sh.inresolves launcher symlinks using physical directories, but classifies casks using three literal Homebrew prefixes. A resolved relocated prefix falls through toINSTALLER=TARBALL, which explains the reportedAZ_PYTHONerror.build_binary_tar_gz.pyrenders the launcher from that.intemplate in_create_launcher_script, uses Python version3.14by default and substitutesPYTHON_BIN=python3. Its build-timefind_homebrew_pythonalready uses the formula'slibexec/bin/pythoncandidate. The install structure createsbin/azas a relative link to../libexec/bin/az.templates/azure-cli.rb.indeclares the versioned Homebrew Python formula dependency and installsbin/azas the cask binary.Requirements for the fix
libexec/bin/python3candidate; preserve working versioned-interpreter fallbacks.AZ_PYTHON, including existing missing/non-executable diagnostics. Preserve argument forwarding,AZ_INSTALLER,PYTHONPATH, package-location validation and supported standard-prefix behavior.bin/azlink, default-prefix behavior, versioned/formula Python lookup, missing Python, and non-cask execution with and withoutAZ_PYTHON. Include quoted paths with spaces. Use isolated fixtures, not mutations of a developer's Homebrew installation. In the implementation job, run the applicable existing validation and report actual results; do not claim macOS or live validation that was not performed.build_binary_tar_gz.pyis the verified renderer; use the real renderer for coverage where appropriate. No AAZ-generated command code is involved or needs modification. Do not expand the fix into AAZ output. If an AAZ dependency is discovered, report the blocker and require the governed durableAzure/aazsource-PR/generation workflow rather than directly editing generated files.PR title & description format (required)
This repo enforces a PR format (guide). Please author the PR exactly as follows or CI's Check the Format of Pull Request Title and Content will fail.
Use this EXACT PR title (copy verbatim, do not reword):
Keep the backticks around the command and the
Fix #34187:prefix. You may only adjust the wording after the command (the final summary) if the fix changes; the[Packaging]prefix, issue link, and backticked command must stay.Description — follow the PR template and fill in:
Fixes #34187.az ...command this affects.[Packaging] `az <command>`: <note>.Posted by x-engineering-agent (Fixer)
{Packaging} Fix #34187: `az version`: Detect Homebrew casks with syml…