VS Code 中的 Python 環境

Python Environments 擴充功能將環境與套件管理整合進 Visual Studio Code 的 UI 中。無論您使用的是 venv、uv、conda、pyenv、poetry 還是 pipenv，該擴充功能都提供了一個統一的介面來建立環境、安裝套件及切換直譯器。

核心功能

• 建立、刪除與切換環境
• 安裝與管理套件
• 終端機中已啟用的 Python
• 將環境指派給特定檔案或資料夾（稱為「Python 專案」）

此擴充功能與 Python 擴充功能協同運作，無需任何設定即可開始使用。

快速入門

大多數使用者不需要進行任何設定。該擴充功能會自動探索您的 Python 環境，並在執行程式碼時使用它們。

如果您是基本設定，例如整個工作區使用一個環境：

1. 開啟一個 Python 檔案
2. 檢查狀態列（Status Bar）以查看目前啟用的環境
3. 若要切換環境，請選取狀態列中的環境控制項

需要建立環境嗎？開啟 Python 側邊欄，展開 Environment Managers，然後選取 + 按鈕。擴充功能將引導您完成各個步驟。

使用者介面元件

環境探索

以下環境管理員會被自動偵測

當擴充功能啟用時，探索程序會自動執行。該擴充功能使用 Python Environment Tool (PET) Rust 二進位檔來掃描您系統中的 Python 環境。PET 會透過檢查您的 PATH（例如尋找 conda、pyenv 和 poetry 可執行檔）以及已知的安裝位置來尋找環境管理員，然後搜尋由這些管理員所管理的環境。

若要手動觸發重新整理：

1. 開啟命令面板（Cmd+Shift+P 或 Ctrl+Shift+P）
2. 執行 Python Environments: Refresh All Environment Managers

您也可以點擊 Environment Managers 檢視標頭中的重新整理圖示。

選取重新整理圖示以重新掃描環境。

檢視已發現的環境

已發現的環境會出現在兩個位置：

• Environment Managers 檢視：在 Python 側邊欄中，環境會按管理員類型分組（例如 venv、Conda 等）
• 環境選取：當為專案選擇直譯器時，所有已發現的環境會顯示在統一的清單中

Environment Managers 檢視會將環境按類型分組。

設定搜尋路徑

預設情況下，該擴充功能會使用 Glob 模式 ./**/.venv 搜尋整個工作區中的虛擬環境。這會找出工作區中任何名為 .venv 的資料夾。

若要在自訂位置中探索環境，請更新 python-envs.workspaceSearchPaths 設定。

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

提示:

• 使用 ** 進行遞迴搜尋（例如 ./**/env 會找到任何深度的 env 資料夾）
• 相對路徑會從您的工作區根資料夾開始解析

若要快速開啟搜尋路徑設定：

1. 開啟命令面板
2. 執行 Python Environments: Configure Search Settings

新增自訂的 Glob 模式以搜尋其他位置。

全域搜尋路徑：對於工作區以外的環境（例如共用的 ~/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 詳細輸出會精確顯示發現了哪些環境以及原因。

進階疑難排解適用於下列情境：

• 您需要驗證某個環境是否被偵測到
• 您想了解為什麼環境出現在特定管理員下方
• 您正在除錯路徑解析問題

建立、刪除與管理環境

建立環境

該擴充功能提供兩種建立環境的方式：為了快速的 快速建立 (Quick Create)，以及為了可控性的 自訂建立 (Custom Create)。

快速建立

選取 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 專案是指您想要與特定環境關聯的任何檔案或資料夾。預設情況下，您的整個工作區使用一個環境。專案功能讓您可以將不同的環境指派給不同的資料夾。這對於大型單體儲存庫 (mono-repos)、微服務或跨 Python 版本測試來說至關重要。

為什麼要使用專案？

如果您整個工作區只有一個環境，則不需要明確設定專案。選擇一個直譯器即可。

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

哪些功能使用專案指派？

• 執行與除錯：使用該專案的環境
• 終端機：以該專案的環境啟用
• 測試總管 (Test Explorer)：每個專案都會擁有自己的測試樹狀結構及其自己的直譯器（請參閱 多專案測試）

新增專案

若要將資料夾或檔案視為獨立專案：

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 專案指南以了解範本結構詳細資訊。

深入了解

有關範本、多根目錄工作區、常見情境與疑難排解的詳細指引，請參閱完整的 Python 專案指南。

套件管理

直接從 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 環境中的套件安裝將使用 uv pip 而非一般 pip，這對於大型相依樹狀結構來說顯著更快。

設定與組態

本章節涵蓋所有擴充功能設定、直譯器選取運作方式，以及舊版設定遷移。

直譯器選取優先順序

當您開啟工作區時，擴充功能會依照下列順序檢查來源以決定使用哪個環境：

關鍵原則：使用者配置的設定永遠優先於預設值。如果您沒有明確設定 defaultEnvManager（它擁有內建預設值），擴充功能會跳過它並檢查下一個優先順序。

快取：擴充功能會快取已解析的環境以提升效能，但您的明確設定永遠優先於快取值。您無須擔心過期的快取覆寫您的選擇。

關於直譯器選取行為的更多詳細資訊，請參閱 直譯器選取快速參考。

何時寫入設定

只有在您進行明確變更時，擴充功能才會寫入設定：

這確保了開啟工作區不會將自動產生的項目新增至您的 settings.json。

Python Environments 設定

終端機設定

當您在 VS Code 中開啟終端機時，擴充功能會自動啟用您選取的 Python 環境，以便 python、pip 與相關指令使用正確的直譯器。

終端機啟用類型

開啟特定環境的終端機

您可以開啟一個已啟用任何環境的新終端機：

1. 在 Environment Managers 檢視中找到該環境
2. 按右鍵並選取 Open in Terminal

開啟已啟用任何環境的終端機。

關於詳細疑難排解與啟用運作機制，請參閱 終端機自動啟用說明。

.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 Notebook

Jupyter Notebook 不使用 Python Environments API 進行環境探索。相反地，它們依賴較舊的 Python 擴充功能 API。這意味著 Notebook Kernel 選取器顯示的環境清單可能會與 Environment Managers 檢視中的不同。

後續步驟

• Python 教學課程 - 開始在 VS Code 中使用 Python。
• 除錯 - 學習如何對您的 Python 程式碼進行除錯。
• 測試 - 為您的 Python 專案配置並執行測試。
• 設定參考 - 探索所有 Python 擴充功能設定。