MENU

WindowsでAzure CLIの「Pip failed with status code 1」を解決する：Anaconda競合と旧CLI残骸の徹底対処ガイド

Azure

Windows 環境で az extension add を実行した際に「Pip failed with status code 1」で止まってしまう――その多くは Anaconda 系ディストリビューションの“システム Python 登録”や、旧 Azure CLI の残存ファイルが原因です。本記事では、症状の見分け方から根本原因、再発防止までを一気通貫で解説し、現場でそのまま使える確認コマンドと復旧手順を具体的にまとめます。

目次

問題の概要と再現症状

Azure CLI の拡張（例：subscription、containerapp）を追加しようとして次のようなメッセージで失敗します。

PS> az extension add --name subscription
An error occurred. Pip failed with status code 1.

--debug を付けると、pip 実行中に Python ランタイムの読み込みに失敗している痕跡が出ます。代表例は次のとおりです。

ログの一部意味合い
ImportError: DLL load failed while importing ...参照すべき DLL（例：python3x.dll、vcruntime140.dll、_ssl.pyd）の読み込みに失敗
FileNotFoundError: [WinError 2] The system cannot find the file specified別系統の Python を誤参照し、存在しないパス/モジュールを要求
Fatal error in launcher: Unable to create process using ...レジストリ/環境変数の衝突で Python ランチャーが誤動作

なぜ発生するのか（内部の仕組み）

Windows 用 Azure CLI は、インストーラー（MSI）に同梱された「埋め込み Python」を自前で持っています。拡張機能の追加は内部で pip を呼び出し、Azure CLI が同梱する Python 環境にホイール（.whl）をインストールする方式です。

ところが、以下の条件があると CLI が同梱 Python ではなく「外部の Python（多くは Anaconda/Miniconda/Miniforge）」を巻き込み、pip が異なる DLL を見に行って壊れます。

  • Anaconda 系を「Register as system Python（システム既定の Python として登録）」している
  • かつ PATH/レジストリ/環境変数（PYTHONHOME や PYTHONPATH）が混線している
  • または 旧バージョンの Azure CLI がディスク上に残留し、DLL の解決順序が乱れている

結果として、Azure CLI から見ると「pip を同梱 Python で起動したつもりが、途中で別の Python の DLL を拾ってしまいクラッシュする」状態になります。

主な原因（現場での頻出順）

原因説明
Anaconda 系ディストリビューションとの競合Anaconda/Miniconda/Miniforge を「システム既定の Python」として登録したり、PATH に全体適用すると、Azure CLI が同梱の埋め込み Python ではなく Conda 側を参照してしまい、pip で DLL 読み込みが破綻します。
旧 Azure CLI の残骸Program Files 配下に旧 CLI のファイルが残ると、モジュールや DLL の解決順序が乱れ、pip 実行時の ImportError/FileNotFoundError を誘発します。

まず行う一次切り分けチェック

以下の手順で「どの Python を見に行っているのか」を素早く特定します。

  1. CLI と Python の所在確認
PS> Get-Command az | Format-List
PS> where az
PS> az --version
PS> where python
PS> py -0p

az --version の出力中に「Python location」が C:\Program Files\Microsoft SDKs\Azure\CLI2（または ... (x86)\...）を指していれば正常です。逆に conda 配下やユーザー領域の Python を指していれば競合が濃厚です。

  1. デバッグログに Python の解決パスを吐かせる
PS> az extension add --name subscription --debug 2> $env:TEMP\azext_debug.log
PS> notepad $env:TEMP\azext_debug.log

ログ内で pip、python.exe、site-packages、DLL といったキーワードを検索し、どの Python ルートが使われているかを確認します。

  1. 環境変数を確認
PS> gci env: | where { $_.Name -match 'PYTHON|CONDA|AZURE' } | sort Name

PYTHONHOME や PYTHONPATH がシステム全体またはユーザーに設定されている場合、Azure CLI の同梱 Python を汚染します。特に PYTHONPATH が Conda 側を指していれば高確率でアウトです。

  1. レジストリ（任意・管理者）
PS (Admin)> Get-ChildItem 'HKLM:\Software\Python\PythonCore' -ErrorAction SilentlyContinue | 
  Get-ItemProperty | 
  Select-Object PSChildName,InstallPath,ExecutablePath

ここに Anaconda 系の登録があり、さらに「Register as system Python」を有効にしていると、Windows の Python 解決に影響します。

観点期待される状態NG 例
Azure CLI の PythonC:\Program Files\Microsoft SDKs\Azure\CLI2\ 配下C:\Users\<user>\anaconda3\ を指している
環境変数PYTHONHOME/PYTHONPATH 未設定（またはセッション内でのみ設定）システム環境変数に PYTHONPATH=...anaconda3
レジストリ必要最小限の登録のみAnaconda が既定 Python として登録済み

解決策（推奨順）

最優先：Anaconda 系の「システム Python 登録」をやめる（または一旦アンインストール）

最も再現率が高く、効果が大きい対処です。

  1. アンインストール：アプリと機能から Anaconda/Miniconda/Miniforge/Navigator を削除します。開発用に必要な場合は後で再インストールします。
  2. 再インストール時の注意：
    • セットアップの「Add Anaconda to my PATH」をオフ
    • 「Register as system Python（システムに Python として登録）」をオフ
    • ユーザーごとの仮想環境（conda create -n）で運用し、システム全体には登録しない

Conda を残したい場合の一時回避として、その PowerShell セッション内だけ Azure CLI の Python を優先させる方法もあります。

PS&gt; $env:PYTHONPATH = 'C:\Program Files\Microsoft SDKs\Azure\CLI2'
PS&gt; az extension add --name subscription

恒久化する場合は「ユーザー環境変数」に設定します（ただし他ツールへの副作用に注意）。

第二優先：Azure CLI のクリーン再インストール

旧ファイル残存による DLL 誤参照を解消します。

  1. コントロール パネルから Microsoft Azure CLI をアンインストール。
  2. 以下の残存ディレクトリを手動で削除（存在する方のみ）。
    • C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2
    • C:\Program Files\Microsoft SDKs\Azure\CLI2
  3. PC を再起動（DLL ロックの解放目的）。
  4. 公式 MSI から最新版を再インストール。

再セットアップ後は az --version で「Python location」が CLI2 配下を指していることを確認してください。

第三優先：環境変数で Azure CLI の Python を固定（Conda を共存させたい場合）

開発都合で Conda を残すなら、Azure CLI 実行時だけ埋め込み Python を強制します。

PS&gt; $env:PYTHONHOME = 'C:\Program Files\Microsoft SDKs\Azure\CLI2'
PS&gt; $env:PYTHONPATH = 'C:\Program Files\Microsoft SDKs\Azure\CLI2'
PS&gt; az extension add --name containerapp

この方法は「セッション限定」で使うのが安全です。システム環境変数への恒久設定は、他アプリの Python 利用に影響を与えうるため推奨しません。

追加ヒント（復旧を加速する小技）

  • CLI 自体が古いと拡張の解決に失敗することがあります。まず az upgrade を実行。
  • pip のアップグレード先が Conda 側に向くなら競合のサインです。Azure CLI の Python を指名して更新します。 PS> "C:\Program Files\Microsoft SDKs\Azure\CLI2\python.exe" -m pip install --upgrade pip
  • ログの取り方の定石：--debug と 2> path\to\log を組み合わせ、使用 Python/モジュールの実体を可視化。

具体例：subscription / containerapp での復旧パターン

subscription 拡張

PS&gt; az extension remove --name subscription
PS&gt; az extension add --name subscription --debug

上記で ImportError が再現する場合、Conda 登録解除 → Azure CLI 再インストールの順に対応します。復旧後は次のように表示されます。

PS&gt; az extension list -o table
Name          Version    Summary
------------  ---------  -----------------------------------------
subscription  0.X.Y      Manage subscription resources

containerapp 拡張

PS&gt; az extension add --name containerapp --upgrade --debug

同様に外部 Python 競合が原因であれば、セクション「解決策」を適用すれば成功します。どうしても拡張のオンライン取得が難しい回線環境ではローカルの .whl を指定する手もありますが、内部で結局 pip を使うため Python 衝突が残っていると回避できません。

運用でのベストプラクティス（再発防止）

  1. ツールごとに Python を分離：Azure CLI の同梱 Python と、開発用 Python（Conda など）を PATH/レジストリで混在させない。
  2. 仮想環境を徹底：Conda/venv はユーザー領域の仮想環境で使用し、システム全体には登録しない。
  3. 定期アップデート：az upgrade で CLI を最新に保つ。
  4. 問題時はログ添付で報告：--debug ログ中の「Python location」「site-packages」「DLL」行を抜粋して共有すると再現が早い。

よくある誤解と落とし穴

  • 「pip を最新にしたら直るはず」：問題の本質は「どの Python の pip を使っているか」です。Conda 側で pip install --upgrade pip を実行しても、Azure CLI の同梱 Python に効きません。
  • 「Windows 用 Azure CLI を pip で入れ直す」：Windows では MSI 版の利用が標準です。Python 環境に直接 azure-cli を入れる運用は混乱のもとになります。
  • 「Visual C++ 再頒布可能パッケージを入れれば解決」：DLL ロード失敗の文言だけを見るとそう見えますが、今回は DLL の不足ではなく「別の Python の DLL を誤って掴む」ことが根本原因であるケースが多いです。

現場で使える診断スクリプト（PowerShell）

次のスクリプトは、Azure CLI がどの Python を参照しているかと、代表的な衝突要因をまとめて出力します。

# 保存名: inspect-azurecli-python.ps1
Write-Host '=== Azure CLI path ==='
Get-Command az | Format-List

Write-Host '=== az --version (short) ==='
az --version 2>&1 | Select-String -Pattern 'python|Python|location|azure-cli' | ForEach-Object { $_.Line }

Write-Host '=== where python / py -0p ==='
where python 2> $null
py -0p 2> $null

Write-Host '=== Relevant Environment Variables ==='
gci env: | where { $_.Name -match 'PYTHON|CONDA|AZURE' } | sort Name

Write-Host '=== Registry PythonCore (Admin only) ==='
$reg = 'HKLM:\Software\Python\PythonCore'
if (Test-Path $reg) {
Get-ChildItem $reg | Get-ItemProperty | Select PSChildName,InstallPath,ExecutablePath
} else {
Write-Host 'No HKLM PythonCore registry.'
}

クリーンアップ手順のテンプレート

Conda の登録解除と Azure CLI の再セットアップを、変更の少ない順に並べた手順例です。企業端末でも実施しやすいように、最小権限で始めてダメなら深掘りするフローにしています。

  1. PowerShell（通常権限）で inspect-azurecli-python.ps1 を実行。外部 Python 参照の痕跡があるかを確認。
  2. Conda を使用している場合は システム登録を解除するため、アンインストール → 「PATH 追加」オフ／「システム Python 登録」オフで再インストール。
  3. 状況が変わらない場合、Azure CLI をアンインストールし、CLI2 ディレクトリを手動削除 → 再起動 → 再インストール。
  4. 復旧後、az extension add --name subscription、--name containerapp の順で再検証。

チームで共有したい運用スタンダード（サンプル）

複数メンバー・複数プロジェクトが同一端末を使う現場では、以下のルールで事故率が激減します。

  • Windows 端末では Azure CLI は MSI 版、Conda はユーザー仮想環境で運用する。
  • Conda セットアップ時は 「PATH 追加」「システム Python 登録」を禁止（手順書・チェックリスト化）。
  • Azure CLI の拡張は az extension add で管理し、Python/pip で直接いじらない。
  • 社内ポータルに「inspect スクリプト」「復旧フロー」「トラブル事例」を常備。

ケーススタディ：解決までのトレース例

ある検証端末で az extension add --name containerapp が常に失敗。ログには ImportError: DLL load failed: _ssl.pyd。az --version を確認すると Python location が C:\Users\<user>\miniconda3\。Conda をアンインストール後、Azure CLI をクリーン再インストール。再度 az extension add を実行したところ正常完了。その後、Miniconda を「PATH 追加オフ／登録オフ」で再導入し、以降は再現せず。

現場で多い Q&A

Q. az extension add でしか失敗しません。他の az コマンドは動きます。 A. 拡張の追加は内部で pip を起動するため、Python の解決が最も揺らぎます。CLI 単体のコマンドが通っても、拡張追加では外部 Python を拾って落ちます。 Q. 32bit/64bit の違いは関係ありますか？ A. 旧 CLI の 32bit 残骸と 64bit の新規インストールが同居していると DLL 解決順序が乱れやすくなります。クリーン再インストールで解消します。 Q. 端末のセキュリティ製品やプロキシは関係しますか？ A. ネットワーク遮断でオンライン取得が失敗するケースはありますが、今回の DLL ロード系エラーは Python 衝突が主因であることが多いです。

トラブル時に共有したい報告テンプレート

【端末】Windows 10/11, x64
【Azure CLI】az --version の全文
【発生手順】実行したコマンド（例：az extension add --name containerapp --debug）
【ログ】--debug の抜粋（Python location / site-packages / DLL に関する行）
【Python】where python / py -0p の結果
【環境変数】PYTHONHOME/PYTHONPATH/CONDA* の有無
【直近の変更】Anaconda/Miniconda の導入・更新有無、Azure CLI の更新有無

確認用コマンド集（コピー＆ペースト可）

# 1) バージョンと Python 位置
az --version

# 2) az と python の解決パス

Get-Command az | Format-List
where az
where python
py -0p

# 3) 拡張のデバッグインストール（ログ保存）

az extension add --name subscription --debug 2> $env:TEMP\azext_debug.log

# 4) 問題の拡張を一旦削除

az extension remove --name subscription
az extension remove --name containerapp

# 5) Azure CLI の Python で pip を更新

"C:\Program Files\Microsoft SDKs\Azure\CLI2\python.exe" -m pip install --upgrade pip

# 6) 環境変数の一時設定（セッション限定）

$env:PYTHONHOME = 'C:\Program Files\Microsoft SDKs\Azure\CLI2'
$env:PYTHONPATH = 'C:\Program Files\Microsoft SDKs\Azure\CLI2'

まとめ（要点の再掲）

  • エラーの正体：Pip failed with status code 1 の多くは 外部 Python の混入が原因。
  • 最短の直し方：Anaconda 系の「システム Python 登録」をやめる（必要ならアンインストール→登録オフで再導入）。
  • それでもダメなら：Azure CLI をクリーン再インストールして残骸を排除。
  • 共存のコツ：Conda はユーザー仮想環境運用。Azure CLI の Python は他と混在させない。
  • 検証の勘所：az --version の Python location、--debug ログのパス、環境変数/レジストリを確認。

付録：実務で役立つ運用チェックリスト

チェック項目合格基準頻出不具合
Conda のインストールオプションPATH 追加オフ／システム登録オフPATH 追加や登録オンにして端末全体を汚染
Azure CLI のバージョンaz upgrade 済み古い CLI が残り、拡張だけ失敗
残骸の有無CLI2 配下の二重化なし32bit/64bit の混在・旧フォルダ残留
環境変数PYTHONHOME/PYTHONPATH は未設定システム環境変数で Conda を指す

スレッドの知見（要約）

実地の報告では、Anaconda を削除するか、「システム Python 登録」をオフにして再インストールすることで az extension add が正常動作に戻ったケースが多数見られます。Azure CLI 側だけの再インストールでは改善しない事例もあり、Conda 側の設定見直しが決定打になることが多い、というのが実務上の結論です。

他拡張機能でも起こる同類エラー

az extension add --name containerapp --upgrade でも同種の pip 失敗報告が見られます。原因は同じく外部 Python の競合です。本記事の対処（Conda の登録解除／CLI のクリーン再インストール／環境変数の固定運用）で解決できます。

長期安定運用のためのチェックポイント

  • Azure CLI の拡張導入は az extension add に統一し、pip 直叩きは避ける。
  • Conda の更新時は「PATH 追加」「システム登録」のチェックが勝手に変わっていないか毎回確認する。
  • 端末標準の Python を必要とする別製品がある場合は、Windows の py ランチャー（py.exe）でバージョンごとに呼び分ける運用に統一する。
  • 不具合時は --debug ログを最初に採取し、再現手順と合わせてチームに共有する。

最後に

「Pip failed with status code 1」はメッセージが漠然としているため、闇雲に Visual C++ や証明書、プロキシを疑って時間を失いがちです。まずは Python の参照先に着目し、Anaconda のシステム登録を外す・Azure CLI をクリーンに保つ――この 2 点を押さえれば、ほとんどのケースは短時間で復旧できます。本記事のコマンド群とチェックリストをチーム運用に組み込んでおけば、次回以降の復旧はさらに速く、確実になります。

Azure
トラブルシューティング Windows Python pip Anaconda Azure CLI

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次