{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`)

Aperta
  • Qualcosa non va?
#34,103 3 commenti 0 reazioni 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@naga-nandyala ci sta già lavorando.

Dal 19/9/2026.

  • #34122 di @a0x1ab — chiusa senza merge

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

Azure CLI Team bug customer-reported
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
  • #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.
  • #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

Lingua principale
Python
Stelle
4.7k
Fork
3.5k
Merge medio
4g 14h
PR unite (30g)
92

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Azure/azure-cli

Tutte le issue di Azure/azure-cli

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.