VS CodeでAzure Prompt Flowを使おうとしたのに、「Python環境が存在しない」「環境が見つからない」ように振る舞って作業が止まることがあります。多くの場合、原因はPrompt Flowそのものではなく、PythonのパスやVS Code側のインタープリタ選択、仮想環境の置き場所にあります。この記事では、ありがちな落とし穴を整理し、最短で復旧するための確認手順と再発防止策をまとめます。
VS CodeでAzure Prompt FlowのPython環境が認識されないときの典型的な症状
「認識されない」といっても、現れ方はいくつかあります。まずは状況を言語化すると切り分けが速くなります。
- Prompt FlowのUIやコマンドが「Pythonが見つからない」「インタープリタが無い」ようなエラーを出す
- VS Codeでは仮想環境が見えているのに、Prompt Flow側だけが「存在しない」扱いになる
- ターミナルでは動くのに、拡張機能の実行やデバッグだけ失敗する
- 別プロジェクトでは動くのに、特定のフォルダ配下だけ失敗する
このタイプの不具合は、たいてい「どのPythonを使っているか」がVS Code・ターミナル・Prompt Flowでズレているのが根本原因です。
まず押さえるべき前提：Prompt Flowが“同じPython”を見ているとは限らない
VS Codeには複数のレイヤーがあります。
- OSに入っているPython（Microsoft Store版、python.org版、Anacondaなど）
- 仮想環境（venv / conda / Poetry / uv など）
- VS CodeのPython拡張機能が選択しているインタープリタ（ワークスペース単位で変わる）
- 拡張機能（Prompt Flow）が内部で参照するPython（設定や実装都合で別解釈になることがある）
つまり「依存関係をインストールした」だけでは不十分で、Prompt Flowが見に行くPythonの実体が、依存関係を入れたPythonと一致しているかが重要です。
最重要ポイント：原因の多くはPythonパス（フォルダ場所）にある
環境が認識されないケースで特に多いのが、Pythonの実体（python.exe）や仮想環境の場所が、ツール側の想定から外れているパターンです。中でも頻出なのが次の3つです。
パスに空白が含まれている
例として、ユーザープロファイル名にスペースが入っていると、仮想環境のパスにもスペースが混ざりやすくなります。
- 例：
C:\Users\User Name\...
本来は引用符（ダブルクォーテーション）で回避できる場面もありますが、拡張機能や周辺ツールの実装によっては、空白を含むパス処理が不完全で、正しく解釈できずに失敗することがあります。
日本語・全角文字・特殊文字を含むパス
近年は改善されていますが、ツールチェーン全体で完全に安全とは言い切れません。特に「プロジェクトの場所」「venvの場所」「一時ディレクトリ」に全角が混ざっていると、再現性の低い不具合として表に出ることがあります。
指定しているPython実行ファイルのパスがそもそも違う
VS Code上で選んだつもりでも、別の設定ファイルや別ウィンドウで違うインタープリタが選択されていることがあります。また、PATHの優先順位で想定外のPythonが選ばれることもあります。
切り分けを最短で終えるチェック表
次の表を上から潰すと、多くのケースは途中で原因に当たります。
| チェック項目 | 確認方法 | ありがちなNG | 推奨の対処 |
|---|---|---|---|
| プロジェクトのパスに空白/全角がある | エクスプローラでパス確認 | C:\Users\User Name\… / OneDrive配下 | C:\dev\work\project など短いパスへ移動 |
| 仮想環境（venv等）のパスに空白/全角がある | venvフォルダの場所確認 | ユーザーフォルダ直下に作成 | C:\dev\venv\pf-env などへ作り直す |
| VS Codeが選んでいるインタープリタが正しい | Python: Select Interpreter | 別のPythonを選択している | Prompt Flow用の環境を明示的に選び直す |
| ターミナルのpythonと一致している | where python / python -c で確認 | ターミナルは別Pythonを指している | ターミナルを作り直し、環境を有効化 |
| 必要パッケージがその環境に入っている | pip show / python -m pip | 別環境にインストールしていた | python -m pip で必ず対象環境へ入れる |
手順：VS Code側で「いま使っているPython」を確定させる
最初にやるべきことは、VS Codeが参照するPythonを固定して、迷子をなくすことです。
VS Codeでインタープリタを選び直す
- コマンドパレット（Ctrl+Shift+P）を開く
- Python: Select Interpreter を実行する
- Prompt Flow用に使いたい仮想環境を選ぶ（venv / conda 等）
- VS Code左下（または右下）のPython表示が期待どおりか確認する
ここで重要なのは「表示が合っていること」よりも、次のコマンドで実体のパスまで一致することです。
ターミナルで実体パスを確認する（Windows / macOS / Linux）
VS Codeの統合ターミナルで、以下を実行します。
Windows（PowerShell / CMD）
where python
python -c "import sys; print(sys.executable)"
python -m pip -VmacOS / Linux
which python
python3 -c "import sys; print(sys.executable)"
python3 -m pip -Vポイントは、sys.executable が「あなたが使いたい仮想環境内のpython」を指していることです。ここがズレている限り、依存関係を追加しても別環境に入ってしまい、Prompt Flowからは“無い”ように見え続けます。
最も効く対処：スペースや全角を含まない場所に環境を作り直す
結論として、再現性が高く効果が大きいのがこの方法です。特にWindowsでは、ユーザーフォルダ配下（名前に空白が入る等）や同期フォルダ（OneDrive）配下を避けるだけで、突然安定するケースが多々あります。
おすすめのディレクトリ例
- プロジェクト：
C:\dev\work\promptflow-project - 仮想環境：
C:\dev\venv\promptflow
venvで作り直す例（Windows）
cd C:\dev\work\promptflow-project
py -3 -m venv C:\dev\venv\promptflow
C:\dev\venv\promptflow\Scripts\python.exe -m pip install -U pipそのうえで、依存関係（Prompt Flowに必要なパッケージ群）を必ず 対象環境のpython -m pip で入れます。
C:\dev\venv\promptflow\Scripts\python.exe -m pip install <必要なパッケージ>この「python -m pip」を徹底するだけで、インストール先の取り違えが激減します。
condaの場合に起きやすいズレ
conda環境は便利ですが、次のズレが起きやすいです。
- VS Codeではconda環境を選んだのに、ターミナルがbaseのまま
- ターミナルでconda activateしたのに、拡張機能側が別のPythonを使っている
対処としては、VS Codeのインタープリタ選択を最優先にし、統合ターミナルもその選択に追従する設定に寄せます。
VS Codeの設定ファイルでインタープリタを固定する
「毎回勝手に切り替わる」「ワークスペースを開き直すと別Pythonになる」場合は、プロジェクト内の設定で固定するのが効果的です。
.vscode/settings.json の例（Windows）
{
"python.defaultInterpreterPath": "C:\\\\dev\\\\venv\\\\promptflow\\\\Scripts\\\\python.exe",
"python.terminal.activateEnvironment": true
}この固定は、チーム開発でも効きます。ただし個人ごとに環境パスが違う場合は、共通化しやすいルール（例：全員C:\dev配下に置く）を決めると運用が安定します。
Prompt Flow側が“存在しない”と言うときに見落としがちなポイント
プロジェクトのルート位置とワークスペースの開き方
VS Codeで「フォルダ」ではなく「親フォルダ」や「別階層」を開いていると、ワークスペース設定・仮想環境検出・相対パス解決がズレることがあります。Prompt Flow関連のファイル（例：フロー定義ファイルや設定ファイル）があるディレクトリを、プロジェクトルートとして開き直してみてください。
設定ファイルにPythonパスを直書きしている
フロー定義やツール設定でPythonのパスや環境を明示している場合、そこが古いパスのまま残っていると、VS Codeで正しい環境を選んでもPrompt Flowが古いパスを見に行くことがあります。
- スペルミス（
Scripts/scriptなど） - 環境を作り直したのに、古い仮想環境のパスが残っている
- 空白や全角文字が混ざっている
「ファイルに書かれたパス」と「実際のpython.exeの場所」が一致しているか、フォルダを辿って確認してください。
必要な依存関係が“その環境”に入っていない
これは体感的に最も多い落とし穴です。特に、以下の状況だと「入れたつもり」が発生します。
- グローバルPythonに入れていた
- 別のvenvに入れていた
- pipコマンドが別Pythonのpipだった
確認は「その環境のpython」で行います。
python -c "import sys; print(sys.executable)"
python -m pip listここで表示されたPython実体が狙いどおりで、かつ必要なパッケージが一覧に載っている状態を作るのがゴールです。
Visual StudioとVisual Studio Codeは別物：混同が起きると調査が遠回りになる
「Visual Studioで動く/動かない」という話題が混ざると、解決が遅れます。Visual Studio（統合開発環境）とVS Code（エディタ＋拡張機能）は、Python環境の扱い・拡張機能・設定の置き場が別体系です。
- VS Codeで起きている問題は、VS CodeのPython拡張機能とワークスペース設定が主戦場
- Visual Studio側の設定やプロジェクト構成を追っても、原因に辿り着かないことがある
今回の「Prompt FlowがVS Code上で環境を認識しない」は、基本的にVS Code側のインタープリタ選択、パス、ターミナル、拡張機能の挙動に集中して確認するのが近道です。
実務で効く“再現性の高い”復旧フロー
時間を溶かしやすいトラブルなので、手順化してしまうのが安全です。
環境が迷子のときの復旧ステップ
- プロジェクトを短いパスへ移動（例：C:\dev\work配下）
- 仮想環境を短いパスへ新規作成（例：C:\dev\venv配下）
- VS CodeでPythonインタープリタを選び直す
- ターミナルでsys.executableを確認して一致させる
- 必要な依存関係をpython -m pipで入れ直す
- VS CodeをReload Window（拡張機能の状態をリフレッシュ）
この流れは「何が悪いか」を一気に特定するというより、ズレが起きにくい構成に寄せて強制的に正常化する考え方です。急いで復旧したいときほど効きます。
落とし穴集：やってしまいがちなNGパターン
| NGパターン | なぜ起きる | 結果 | 回避策 |
|---|---|---|---|
| pip install だけで入れた気になる | pipが別Pythonのpip | Prompt Flow側からは未インストール | python -m pip を徹底 |
| ユーザーフォルダ/OneDrive配下に全部置く | 空白/同期/権限/パス長の影響 | 認識不良や不安定 | C:\dev などに移す |
| ワークスペースを別階層で開く | 設定の適用範囲がズレる | インタープリタが勝手に変わる | プロジェクトルートを開く |
| 環境を作り直したのに設定ファイルが古い | パス直書きが残る | “存在しない”を再発 | 設定ファイルのパスを棚卸し |
それでも解決しない場合に疑うべきこと
ここまでで解決しない場合は、一般的な“パス問題”以外の領域に踏み込みます。頻度は下がりますが、当たると強いポイントです。
拡張機能側の不具合や相性問題
VS Code拡張機能は更新頻度が高く、特定バージョンの組み合わせでだけ問題が出ることがあります。次の観点で状況を整理すると、切り分けが進みます。
- VS Codeのバージョン
- Python拡張機能のバージョン
- Prompt Flow関連拡張機能のバージョン
- OS（Windows 10/11、macOS、Linux）
- Pythonの配布元（python.org / conda / Microsoft Store など）
この情報を揃えたうえで、VS Codeや拡張機能のIssue（GitHub）に投稿すると、同症状の既知不具合に辿り着けることがあります。投稿時は、個人情報にならない範囲で「python.exeのフルパス例」「where pythonの結果」「sys.executableの出力」を添えると、回答精度が上がります。
Windowsのパス長制限・権限・実行ポリシー
まれに、パスが深すぎる（フォルダ階層が長い）ことでツールが落ちるケースがあります。またPowerShellの実行ポリシーや、フォルダ権限が影響して仮想環境の有効化スクリプトが動かないこともあります。
- 「短いパスへ移す」は、こうした問題もまとめて回避できるため優先度が高い
- 権限問題が疑わしい場合は、管理者権限の有無や、セキュリティソフトの隔離ログも確認する
再発防止：Prompt Flow開発で安定するフォルダ設計と運用ルール
最後に、トラブルを起こしにくい形を“最初から”作っておくと、環境構築がチームでも個人でも楽になります。
おすすめ運用ルール
- プロジェクトは短いパスに置く（C:\dev\work、D:\workなど）
- 仮想環境の場所を固定する（C:\dev\venv配下など）
- 依存関係インストールは必ず python -m pip
- .vscode/settings.jsonでインタープリタを固定して迷子を防ぐ
- “動く環境の証跡”を残す（where python、sys.executable、pip -Vの結果をメモ）
Prompt Flowは、フローの実行・ツール呼び出し・パッケージ依存など、Python環境に強く依存します。だからこそ、環境が不安定だと開発体験が一気に悪化します。逆に、パスとインタープリタを整えるだけで、驚くほど安定して作業できるようになります。
まとめ：最優先は「パスの健全化」と「同じPythonを見ている状態」
- 環境が認識されない原因の多くは、Pythonのパス（空白・全角・深すぎる階層）や、インタープリタのズレ
- 短いパスにプロジェクトと仮想環境を置き直すと、一撃で直ることが多い
- VS Codeのインタープリタ選択と、ターミナルのsys.executableが一致しているかが最重要
- 解決しない場合は、拡張機能の相性や既知不具合も疑い、環境情報を揃えてIssueに当たる
まずは「短いパスで新規に仮想環境を作る」→「VS Codeでそのインタープリタを固定」→「python -m pipで必要パッケージを入れる」までを実行してみてください。ここまで揃えば、Prompt Flowが“存在しない”と言い続ける状況から抜け出せる可能性が高いです。
コメント