{Packaging} `az.bat` silently runs an unrelated Python when the shim is copied outside the environment's Scripts directory (e.g. `uv tool install azure-cli`)

[aeb-dev]

Describe the bug

On Windows, when azure-cli is installed from PyPI by a tool that places console shims in a shared bin directory (for example uv tool install azure-cli), the shipped az.bat silently falls back to whatever python is first on PATH instead of the interpreter of the environment azure-cli was installed into. That interpreter has no azure package, so every command fails.

The cause is the interpreter probe in src/azure-cli/az.bat:

IF EXIST "%~dp0\python.exe" (
  "%~dp0\python.exe" -m azure.cli %*
) ELSE (
  python -m azure.cli %*
)

az.bat is declared through setuptools scripts= rather than as a console_scripts entry point, so installers copy the file verbatim. The probe assumes the copy still sits next to the environment's python.exe. Any installer that relocates shims into a shared bin directory breaks that assumption, and the ELSE branch then executes an unrelated interpreter with no warning.

The failure is shell-dependent on Windows, which makes it hard to diagnose. PATHEXT causes PowerShell and cmd to resolve az to the broken az.bat, while Git Bash ignores PATHEXT and resolves the extensionless az script, whose shebang correctly pins the environment's interpreter. The same machine and the same installation therefore succeed in one shell and fail in another.

Related issues

• Error while finding module specification for 'azure.cli' (ModuleNotFoundError: No module named 'azure') #21737 reports the identical error from the same ELSE branch (an az.bat under one Python's Scripts directory invoking a different Python from PATH). It was closed for inactivity rather than fixed.
• {Packaging} Prepend embedded Python folder to PYTHONPATH on Windows #30801 states: "In src/azure-cli/az and src/azure-cli/az.bat, src is added in PYTHONPATH. It seems to be a mistake. But these scripts no longer seem to be used." These scripts are the entry point for every PyPI installation on Windows, so that assumption does not hold for pip/uv installs.

Suggested fix

1. Expose az as a console_scripts entry point. pip and uv both generate a Windows launcher that embeds the absolute path to the environment's interpreter, which removes the probe and makes shim relocation safe. This is the durable fix.
2. Failing that, drop the ELSE python -m azure.cli %* fallback, or gate it behind a check that the interpreter can actually import azure.cli, and emit a clear error otherwise. Silently running an arbitrary interpreter produces a confusing ModuleNotFoundError far from its cause.

Related command

Any command. Reproduced with az version and az --version; the failure occurs before command dispatch, so it affects every command.

Errors

C:\Users\<user>\AppData\Local\Programs\Python\Python314\python.exe: Error while finding module specification for 'azure.cli' (ModuleNotFoundError: No module named 'azure')

Issue script & Debug output

> uv tool install azure-cli
> az version
C:\Users\<user>\AppData\Local\Programs\Python\Python314\python.exe: Error while finding module specification for 'azure.cli' (ModuleNotFoundError: No module named 'azure')

--debug produces no additional output: the failure happens in the .bat launcher, before azure.cli is imported and before any CLI argument parsing.

Behaviour of each launcher present on one machine, using az --version to report the bound interpreter:

Launcher	Interpreter used	Result
MSI wbin\az.cmd	bundled CLI2\python.exe (3.14.6)	works
<uv tool venv>\Scripts\az.bat	tool venv python.exe (3.14.4, adjacent, probe succeeds)	works
~\.local\bin\az (extensionless, shebang)	tool venv python.exe (3.14.4)	works
~\.local\bin\az.bat (shim copied by uv)	bare python from PATH	fails

All four share ~/.azure as config directory, so the login session is not involved; only the launcher differs.

Expected behavior

az resolves the interpreter of the environment it was installed into, regardless of where the launcher is placed.

If that interpreter cannot be located, the command should fail with an explicit message naming the problem, rather than silently executing an unrelated Python and surfacing a ModuleNotFoundError that points nowhere near the cause.

Environment Summary

• OS: Windows 11 Pro 26200
• Install method: uv tool install azure-cli (uv 0.12.13)
• azure-cli: 2.90.0
• Environment interpreter: CPython 3.14.4
• Interpreter wrongly selected by az.bat: CPython 3.14 from PATH

Additional context

No response

[yonzhan]

Thank you for opening this issue, we will look into it.

[x-engineering-agent]

Bug Analysis

Classification and ownership: Sufficiently specified bug in Azure CLI's handwritten Windows/PyPI packaging and startup code. Repository-aware target inference returned unknown, consistent with a launcher failure before any command module or extension is loaded. Route to Azure/azure-cli, base branch dev; no extension tracker is needed. Packaging is the PR component, not a command module.

Use this EXACT PR title:

[Packaging] Fix #34103: `az version`: Use the installed environment interpreter for relocated Windows launchers

Reported reproduction and expected behavior

The failing command is az version; az --version is also reported to fail. The report supplies Windows 11 Pro 26200, Azure CLI 2.90.0, uv 0.12.13, and a tool environment using CPython 3.14.4. After installing Azure CLI with uv, its copied batch launcher in the shared bin directory selects a different CPython 3.14 from PATH. It fails with Error while finding module specification for 'azure.cli' (ModuleNotFoundError: No module named 'azure') before CLI argument parsing, so --debug cannot help.

The reporter distinguishes the failing shared-bin batch shim in cmd/PowerShell from the working environment-local launcher, extensionless launcher in Git Bash, and MSI installation. Those observations are reported evidence, not executions performed during this triage.

Expected: launching Azure CLI uses the interpreter of the environment into which that CLI was installed, even when the installed launcher is relocated. If the installation cannot be located, return a clear launcher-specific error and nonzero status rather than silently executing an unrelated PATH interpreter.

Evidence from current owned dev source

• src/azure-cli/az.bat, the IF EXIST/ELSE interpreter-selection block: only a colocated python.exe is checked; the fallback unconditionally runs bare python -m azure.cli. This directly explains the reported wrong-interpreter failure after relocation. The script also sets AZ_INSTALLER=PIP and adjusts PYTHONPATH.
• src/azure-cli/setup.py, setup(..., scripts=[...]): both az and az.bat are shipped as scripts; there is no interpreter-bound az console entry point. The checked source declares version 2.90.0, matching the report.
• src/azure-cli/az, the os.execl(sys.executable, ...) handoff: it preserves its selected interpreter and forwards arguments to python -m azure.cli. Preserve the working extensionless-launcher behavior and installer/environment handling.
• src/azure-cli/azure/cli/__main__.py, cli_main(cli, args) and the module-level startup/finalization flow: cli_main is not a zero-argument console entry-point callable, and importing this module currently runs CLI initialization and invocation. A launcher refactor must not accidentally invoke the CLI twice or bypass exit-code handling, telemetry finalization, or existing python -m azure.cli behavior.

Intended scoped change

Provide an installation-bound Windows/PyPI launcher, preferably using the packaging tool's generated console launcher with a suitable callable entry point, after checking the repository's packaging compatibility requirements. Preserve argument forwarding/quoting and process exit status. Do not leave a competing shipped batch shim that can continue to select the wrong interpreter. If a legacy batch entry path is retained, it must not silently fall back to an arbitrary PATH Python when its intended installation is unavailable; provide an actionable diagnostic instead. Merely checking whether a PATH Python can import azure.cli is insufficient: it can select a different Azure CLI installation.

Keep the fix in packaging/bootstrap code and directly related regression coverage. Preserve working pip/uv environment-local installs, extensionless/POSIX launchers, MSI launchers, installer identity handling, and module invocation. Do not change command implementations or generated output to mask this startup failure.

Focused regression coverage for the implementation worker

1. Exercise an installed Windows launcher relocated to a shared bin directory with an unrelated Python first on PATH. Cover both az version and az --version; assert the intended environment is used, not just a successful exit. Include the case where the other interpreter has a different Azure CLI installation.
2. Cover actual command resolution in cmd and PowerShell, including launcher-name/PATHEXT conflicts; retain the working extensionless launcher behavior. Use the existing Windows packaging/test infrastructure and isolated local installation fixtures.
3. Cover any retained batch launcher's valid colocated-interpreter path and missing-installation path. The latter must fail clearly and nonzero without executing an unrelated Python.
4. Check argument quoting with spaces, argument forwarding, exit-code propagation, and single invocation through any new callable entry point and through python -m azure.cli. Preserve the existing startup/finalization contract.
5. Run focused existing packaging/startup tests and relevant style checks in the implementation job; document Windows installation smoke-test results and any unavailable environment. No Azure-resource live test is needed to establish this pre-dispatch bug. No tests or implementation were executed during triage.

Generation scope and execution routing

The inspected files are handwritten packaging/bootstrap files, outside src/azure-cli/azure/cli/command_modules and generated aaz/<profile>/ paths. No AAZ model/output change is currently indicated. Confirm that classification in the implementation checkout. The generic generation guidance below remains authoritative if generated scope is encountered; its <module> placeholder is not a packaging module name. The configured durable generation source is Azure/aaz. Do not hand-edit generated files.

Queue implementation through the approved durable Foundry workflow for this repository, with its configured a0x1ab managed fork and all deterministic security, generation, approval, and publication gates intact. This analysis is not a hosted GitHub Agent Task or a direct Copilot assignment.

Mandatory Codegen execution protocol

Before editing implementation files, determine whether the affected <module> command is AAZ-generated. Files under aaz/<profile>/ are generated output and must never be patched directly, including by an AI agent. Check out Azure/aaz beside Azure/azure-rest-api-specs, Azure/aaz-dev-tools, and the downstream repository. API-schema defects start in the specification; command naming, grouping, arguments, API-version selection, help, and examples belong in the durable Azure/aaz command model; non-modelable client behavior belongs in a handwritten subclass or wrapper in custom.py, registered from commands.py. X Engineering Agent creates and promotes the corresponding durable Azure/aaz source pull request before it promotes downstream generated output.

Follow the Azure CLI repository's Codegen workflow and the aaz-dev setup documentation. Set up the checked-out repositories with azdev setup. Use generate only when importing or redesigning command models from Swagger/TypeSpec. For an existing module whose durable Azure/aaz model has been updated, render that model with regenerate:

aaz-dev cli regenerate --name <module> --cli-path <azure-cli>

# New/imported command model only:
aaz-dev cli generate --spec <specification-name> --module <module>

You MUST actually run the generator; do not merely describe it or imitate its output. If the AAZ/specification checkout, local source change, credentials, or generator is unavailable, stop and report the blocker instead of editing generated files. Inspect _aaz_info provenance and the complete regenerated diff, then run focused azdev style, azdev linter, and azdev test validation. For an extension, also update its version and HISTORY.rst, preserve azext_metadata.json compatibility, and let release automation update src/index.json.

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):

[Packaging] Fix #34103: `az version`: Use the installed environment interpreter for relocated Windows launchers

Keep the backticks around the command and the Fix #34103: 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:

• Link the issue — start the Description with a closing keyword so the PR auto-links and closes it: Fixes #34103.
• Related command — the az ... command this affects.
• Description (mandatory) — why the bug happens, what you changed, and the resulting behavior.
• Testing Guide — example command(s) showing the fix works.
• History Notes — leave the title to drive the history note, or add extra lines in the same format (component in brackets + the command in backticks), e.g. [Packaging] `az <command>`: <note>.
• Keep the template checklist and tick the items you've satisfied.