VS Code での Python 環境

Python Environments 拡張機能は、Visual Studio Code の UI に環境およびパッケージ管理機能をもたらします。この拡張機能は、venv、uv、conda、pyenv、poetry、pipenv のいずれを使用しているかに関係なく、環境の作成、パッケージのインストール、インタープリターの切り替えを行うための統合インターフェースを提供します。

主な機能

• 環境の作成、削除、切り替え
• パッケージのインストールと管理
• ターミナルでの Python 自動有効化
• 特定のファイルやフォルダーへの環境の割り当て（「Python プロジェクト」と呼びます）

この拡張機能は Python 拡張機能 と連携して動作し、セットアップなしで使い始めることができます。

クイックスタート

ほとんどのユーザーは設定を行う必要はありません。 拡張機能は自動的に Python 環境を検出し、コード実行時にそれらを使用します。

ワークスペース全体で 1 つの環境を使用するような基本的なセットアップの場合

1. Python ファイルを開く
2. ステータスバーを確認して、現在アクティブな環境を確認する
3. 環境を切り替えるには、ステータスバーの環境コントロールを選択する

環境を作成する必要がありますか？ Python サイドバーを開き、Environment Managers を展開して、+ ボタンを選択してください。拡張機能が手順を案内します。

ユーザーインターフェースコンポーネント

環境の検出

以下の環境マネージャーが自動的に検出されます

検出は拡張機能の起動時に自動的に実行されます。この拡張機能は、システム内の Python 環境をスキャンする Python Environment Tool (PET) Rust バイナリを使用します。PET は PATH をチェック（例: conda、pyenv、poetry 実行ファイルの検索）し、既知のインストール先を確認することで環境マネージャーを特定し、各マネージャーによって管理されている環境を検索します。

手動で更新をトリガーするには

1. コマンドパレットを開く (Cmd+Shift+P または Ctrl+Shift+P)
2. Python Environments: Refresh All Environment Managers を実行する

Environment Managers ビューのヘッダーにある更新アイコンをクリックすることもできます。

更新アイコンを選択して環境を再スキャンします。

検出された環境を表示する

検出された環境は 2 つの場所に表示されます

• Environment Managers ビュー: Python サイドバー内で、環境がマネージャーの種類（venv, Conda など）ごとにグループ化されます
• 環境の選択: プロジェクトのインタープリターを選択する際、検出されたすべての環境が統合リストに表示されます

Environment Managers ビューは環境を種類ごとにグループ化します。

検索パスの構成

デフォルトでは、拡張機能はグロブパターン ./**/.venv を使用して、ワークスペース全体から仮想環境を検索します。これにより、ワークスペース内のどこにある .venv という名前のフォルダーでも検出されます。

カスタムの場所にある環境を検出するには、python-envs.workspaceSearchPaths 設定を更新します

{
  "python-envs.workspaceSearchPaths": ["./**/.venv", "./envs/**", "./my-custom-env"]
}

ヒント:

• 再帰検索には ** を使用します（例: ./**/env は任意の深さにある env という名前のフォルダーを検索します）
• 相対パスはワークスペースフォルダーのルートからのパスとして解決されます

検索パス設定を素早く開くには

1. コマンドパレットを開く
2. Python Environments: Configure Search Settings を実行する

カスタムのグロブパターンを追加して、追加の場所を検索します。

グローバル検索パス: ワークスペース外の環境（共有の ~/envs フォルダーなど）については、python-envs.globalSearchPaths を使用します

{
  "python-envs.globalSearchPaths": ["/Users/yourname/envs", "/opt/shared-envs"]
}

この設定には絶対パスが必要であり、ユーザー（グローバル）レベルで構成されます。

レガシー設定: 以前に python.venvPath や python.venvFolders を使用していた場合、これらは新しい検索パスと自動的に統合されます。将来の互換性を考慮して、python-envs.globalSearchPaths への移行を検討してください。

環境を選択する

検出された環境を使用するには

• ステータスバー: ウィンドウ下部に表示されている Python バージョンを選択する
• コマンドパレット: Python: Select Interpreter を実行し、リストから選択する

選択された環境は、コードの実行、デバッグ、IntelliSense などの言語機能に使用されます。

ステータスバーで Python バージョンを選択して環境を切り替えます。 拡張機能の自動選択について: 環境を明示的に選択せずにワークスペースを開いた場合、拡張機能は次の順序で自動的に環境を選択します

1. ワークスペースローカルの仮想環境 (.venv, venv)
2. グローバル/システムインタープリター

この優先順位を上書きするには、python-envs.defaultEnvManager を設定して特定のマネージャー（例: ms-python.python:conda）を優先させるか、フォルダーごとに制御するために Python プロジェクト を構成してください。レガシー設定も引き続きサポートされています。

環境検出のトラブルシューティング

詳細なトラブルシューティングを行うには、Python Environment Tool (PET) を直接実行して生の検出結果を確認します

1. コマンドパレットを開く
2. Python Environments: Run Python Environment Tool (PET) in Terminal... を実行する
3. オプションを選択
   • Find All Environments: pet find --verbose を実行し、詳細な出力とともに検出されたすべての環境をリストします
   • Resolve Environment...: Python 実行ファイルへのパスを入力し、特定の環境が検出されない理由をデバッグします

PET の詳細出力には、どの環境が、なぜ検出されたのかが正確に表示されます。

高度なトラブルシューティングは、次のようなシナリオに役立ちます

• 環境が検出されているかどうかを確認する必要がある
• 環境が特定のマネージャーの下に表示される理由を理解したい
• パス解決の問題をデバッグしている

環境の作成、削除、管理

環境を作成する

この拡張機能には、高速な「クイック作成」と制御性の高い「カスタム作成」の 2 つの方法があります。

クイック作成

Environment Managers ビューの + ボタンを選択します。拡張機能は次の手順を実行します

• デフォルトのマネージャーを使用します（デフォルトは venv、python-envs.defaultEnvManager で変更可能）
• 利用可能な最新の Python バージョンを選択します
• 環境に .venv (すでに存在する場合は .venv-1, .venv-2) という名前を付けます
• 存在する場合は requirements.txt または pyproject.toml から依存関係をインストールします
• ワークスペースの新しい環境を選択します

これが、動作する環境を素早く構築する方法です。

クイック作成は、適切なデフォルト値で環境を構築します。

カスタム作成

より細かく制御するには、コマンドパレットから Python: Create Environment を実行し、プロンプトに従ってください

1. マネージャーの選択: venv または conda
2. Python バージョンの選択: 検出されたインタープリター (venv) または利用可能な Python バージョン (conda) から選択
3. 環境に名前を付ける: カスタム名を入力するか、デフォルトを受け入れる
4. 依存関係のインストール: requirements.txt、pyproject.toml、または environment.yml からインストールするかを選択

カスタム作成では、各ステップを構成できます。

より高速な作成のために uv を使用する

uv がインストールされている場合、拡張機能は venv の作成とパッケージのインストールに自動的に使用します。これは標準ツールよりも大幅に高速です。次の設定で構成してください。

{
  "python-envs.alwaysUseUv": true
}

alwaysUseUv が有効（デフォルト）の場合、uv がすべての仮想環境を管理します。false に設定すると、uv で作成された環境に対してのみ uv を使用します。

サポートされているマネージャー

環境を削除する

環境を削除するには

1. Environment Managers ビューで、該当する環境を見つけます
2. 右クリックして Delete を選択します

環境を削除すると、ディスク上の環境フォルダーが削除されます。この環境を使用していたプロジェクトは、新しい環境を選択する必要があります。

Python プロジェクト

Python プロジェクト とは、特定の環境に関連付けたい任意のファイルやフォルダーのことです。デフォルトでは、ワークスペース全体で 1 つの環境が使用されます。プロジェクトを使用すると、異なるフォルダーに異なる環境を割り当てることができます。これは、モノレポ、マイクロサービス、または複数の Python バージョンでのテストにおいて不可欠です。

プロジェクトを使う理由

ワークスペース全体で環境が 1 つしかない場合は、プロジェクトを明示的にセットアップする必要はありません。インタープリターを選択するだけで完了です。

Workspace
├── Python Project: backend/
│     └── Environment: .venv (Python 3.12)
│            └── Manager: venv
│
├── Python Project: frontend-utils/
│     └── Environment: .venv (Python 3.10)
│            └── Manager: venv
│
└── Python Project: ml-pipeline/
       └── Environment: ml-env (Python 3.11)
              └── Manager: conda

プロジェクト割り当ては何に使用されるか

• 実行とデバッグ: プロジェクトの環境を使用
• ターミナル: プロジェクトの環境でアクティブ化
• テストエクスプローラー: 各プロジェクトが独自のインタープリターを持つ独自のテストツリーを取得（マルチプロジェクトテスト を参照）

プロジェクトを追加する

フォルダーやファイルを個別のプロジェクトとして扱うには

1. エクスプローラーで右クリックします
2. Add as Python Project を選択します

または、Python Projects ビューで + を選択し、次のいずれかのオプションを選びます

• Add Existing: 手動でファイル/フォルダーを選択
• Auto Find: pyproject.toml や setup.py を持つフォルダーを検出

既存のフォルダーを追加するか、プロジェクトを自動検出します。

環境を割り当てる

フォルダーがプロジェクトになったら、環境を割り当てます

1. Python Projects ビューで、プロジェクトの下に表示されている環境（または「No environment」）をクリックします
2. 検出された環境から選択します

選択された環境は、そのプロジェクト内のファイルを実行またはデバッグするたびに使用されます。

環境をクリックして変更します。

設定の保存方法

プロジェクトに環境を割り当てると、拡張機能はワークスペース設定 (.vscode/settings.json) に書き込みます

{
  "python-envs.pythonProjects": [
    {
      "path": "backend",
      "envManager": "ms-python.python:venv"
    },
    {
      "path": "ml-service",
      "envManager": "ms-python.python:conda"
    }
  ]
}

設定にはハードコードされたインタープリターのパスではなく、環境マネージャー が保存されることに注目してください。拡張機能は、どの環境を選択したかを個別に記憶し、実行時に解決します。この設計により、設定の共有が容易になります

• マシン固有のパスなし: チームメンバーが /Users/yourname/.venv を持つ必要はありません
• システム間でポータブル: macOS、Windows、Linux で動作
• 環境再作成後も保持: .venv を削除して再作成しても動作します

チームメイトとの共有

1. .vscode/settings.json をリポジトリにコミットします
2. チームメイトがワークスペースをクローンして開きます
3. 各自で環境を作成します（クイック作成が最適です）
4. 拡張機能は各プロジェクトの設定されたマネージャーを自動的に使用します

プロジェクトを削除する

Python Projects ビューでプロジェクトを右クリックし、Remove Python Project を選択します。これによりマッピングが削除されます。ファイルは削除されません。

テンプレートからプロジェクトを作成する

適切な構造で新しいプロジェクトを雛形作成するには、コマンドパレットから Python Envs: Create New Project from Template を実行します。次から選択します

• Package: pyproject.toml、パッケージディレクトリ、テストを含むフォルダーを作成
• Script: インライン依存関係メタデータ (PEP 723) を含む単一の .py ファイルを作成

テンプレート構造の詳細については、完全な Python Projects ガイド を参照してください。

詳細情報

テンプレート、マルチルートワークスペース、一般的なシナリオ、トラブルシューティングの詳細なガイダンスについては、完全な Python Projects ガイド を参照してください。

パッケージ管理

ターミナルを開かずに、VS Code から直接 Python パッケージをインストールおよびアンインストールします。

パッケージをインストールする

1. Environment Managers ビューで環境を見つけます
2. 右クリックして Manage Packages を選択します
3. パッケージを検索し、インストールしたいものを選択します

または、コマンドパレットから Python Envs: Manage Packages を実行します。

VS Code から直接パッケージを検索およびインストールします。

要件ファイルからのインストール: requirements.txt、pyproject.toml、または environment.yml からパッケージをインストールすることもできます。求められたらファイルを選択すると、拡張機能はリストされているすべての依存関係をインストールします。

パッケージをアンインストールする

1. Environment Managers ビューで環境を展開して、インストールされているパッケージを表示します
2. パッケージを右クリックして Uninstall Package を選択します

環境別のパッケージマネージャー

拡張機能は環境に基づいて適切なパッケージマネージャーを自動的に使用します

デフォルトを上書きするには、python-envs.defaultPackageManager を設定します。

uv を使用した高速インストール

uv がインストールされており、python-envs.alwaysUseUv が有効（デフォルト）の場合、venv 環境でのパッケージインストールは通常の pip ではなく uv pip を使用します。これは、大規模な依存関係ツリーにおいて大幅に高速です。

設定と構成

このセクションでは、すべての拡張機能設定、インタープリター選択の仕組み、およびレガシー設定の移行について説明します。

インタープリター選択の優先順位

ワークスペースを開くと、拡張機能は以下の順序でソースをチェックし、使用する環境を決定します

原則: ユーザーが構成した設定が常にデフォルトに優先されます。defaultEnvManager を明示的に設定していない場合（組み込みのデフォルト値がある場合）、拡張機能はそれをスキップして次の優先順位を確認します。

キャッシュ: 拡張機能はパフォーマンスのために解決された環境をキャッシュしますが、明示的な設定が常にキャッシュされた値より優先されます。古いキャッシュが選択内容を上書きすることを心配する必要はありません。

インタープリター選択の動作の詳細については、Interpreter Selection Quick Reference を参照してください。

設定が書き込まれるタイミング

拡張機能は、明示的な変更を行った場合にのみ設定を書き込みます

これにより、ワークスペースを開くたびに自動生成されたエントリが settings.json に追加されることを防ぎます。

Python Environments 設定

ターミナル設定

VS Code でターミナルを開くと、拡張機能は自動的に選択した Python 環境をアクティブ化し、python、pip および関連コマンドが正しいインタープリターを使用するようにします。

ターミナルのアクティブ化タイプ

特定の環境でターミナルを開く

任意の環境をアクティブにした状態で新しいターミナルを開くことができます

1. Environment Managers ビューで、該当する環境を見つけます
2. 右クリックして Open in Terminal を選択します

任意の環境をアクティブにしてターミナルを開きます。

詳細なトラブルシューティングとアクティブ化の仕組みについては、Terminal Auto-Activation Explained を参照してください。

.env ファイルのサポート

.env ファイルからターミナルに環境変数を注入するには

1. ワークスペースのルートに .env ファイルを作成するか、python.envFile でカスタムパスを指定します
2. python.terminal.useEnvFile を true に設定します

# .env
API_KEY=your-secret-key
DATABASE_URL=postgres:///mydb

変数はターミナルの作成時に注入されます。これは、ソース管理にコミットすべきではない開発用の資格情報に便利です。

レガシー設定

これらの Python 拡張機能の設定は引き続きサポートされていますが、新しい代替設定があります

設定範囲リファレンス

設定は構成場所によって動作が異なります

ヒント: workspaceSearchPaths はワークスペースフォルダーからの相対パスであるため、ワークスペースまたはフォルダーレベル（ユーザーレベルではなく）で設定する必要があります。

拡張性

Python Environments 拡張機能は拡張性を考慮して設計されています。任意の環境やパッケージマネージャーが Python サイドバーに接続する拡張機能を構築し、組み込みのマネージャーと並べて表示できます。つまり、この拡張機能の更新を待たずに、新しいツールをサポートするようにエコシステムを成長させることができます。

コミュニティメンバーは、Pixi Extension のような追加の環境マネージャー向けの拡張機能を構築しています。

既知の制限事項

Pylance とマルチプロジェクトワークスペース

Pylance は、同一ワークスペース内での異なるインタープリターを持つ複数の Python プロジェクトをサポートしていません。Python プロジェクト を使用して異なるフォルダーに別々の環境を構成しても、Pylance はワークスペース全体で単一のインタープリター（通常はワークスペースルートに関連付けられたもの）を使用します。異なるフォルダーに異なるインタープリターを使用するには、それらを マルチルートワークスペース (File > Add Folder to Workspace) 内のワークスペースフォルダーとして追加してください。Pylance はワークスペースフォルダーごとに独立して実行されるためです。

Jupyter ノートブック

Jupyter ノートブックは、環境の検出に Python Environments API を使用しません。代わりに、以前の Python 拡張機能 API に依存しています。つまり、ノートブックのカーネル選択には Environment Managers ビューとは異なる環境セットが表示される場合があります。

次のステップ

• Python チュートリアル - VS Code での Python の使用を開始する。
• デバッグ - Python コードをデバッグする方法を学ぶ。
• テスト - Python プロジェクトのテストを構成および実行する。
• 設定リファレンス - すべての Python 拡張機能の設定を探索する。