VS Code 中的 Python 环境

Python Environments 扩展将环境和包管理引入 Visual Studio Code 的用户界面。该扩展提供了一个统一的界面，用于创建环境、安装包和切换解释器，无论您是否使用虚拟环境，紫外线，康达，pyenv，诗歌，或皮平输入：.

核心功能：

• 创建、删除和切换环境
• 安装和管理软件包
• 终端中激活的Python
• 将环境分配给特定的文件或文件夹（称为“Python 项目”）

该扩展与Python扩展一起工作，并且无需设置即可开始使用。

快速开始

大多数用户不需要进行任何配置。 扩展会自动发现你的Python环境，并在运行代码时使用它们。

如果你有一个基本的设置，例如整个工作区的一个环境：

1. 打开一个Python文件
2. 查看状态栏以查看当前激活的环境
3. 要切换环境，请在状态栏中选择环境控制

需要创建一个环境？ 打开Python侧边栏，展开 环境管理器，并选择 + 按钮。该扩展将引导您完成不同步骤。

用户界面组件

环境发现

以下环境管理器将自动发现：

当扩展激活时，Discovery 会自动运行。该扩展使用 Python 环境工具 (PET) Rust 二进制文件来扫描您的系统以查找 Python 环境。PET 通过检查您的 PATH 来查找环境管理器（例如，通过查找康达，pyenv，和诗歌可执行文件) 和已知的安装位置，然后搜索由每个环境管理器管理的环境。

手动触发刷新：

1. 打开命令面板 (Cmd+Shift+P或Ctrl+Shift+P)
2. 运行 Python 环境：刷新所有环境管理器

你也可以点击环境管理器视图标题中的刷新图标。

选择刷新图标以重新扫描环境。

查看发现的环境

发现的环境出现在两个地方：

• 环境管理器视图：在Python侧边栏中，环境按管理器类型分组（例如，venv、Conda等）
• 环境选择：在选择项目解释器时，所有发现的环境都会出现在一个统一的列表中

环境经理通过类型查看环境管理组的环境。

配置搜索路径

默认情况下，该扩展会使用 glob 模式在整个工作区中搜索虚拟环境。./**/.venv. 这查找任何名为.venv在你的工作区的任何地方。

要发现自定义位置的环境，请更新python-envs.workspaceSearchPaths设置:

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

提示:

• 使用输入：**用于递归搜索（例如，./**/环境查找任何名为 的文件夹环境在任何深度)
• 相对路径从你的工作区文件夹根目录解析

要快速打开搜索路径设置：

1. 打开命令面板
2. 运行 Python 环境：配置搜索设置

添加自定义 glob 模式以搜索其他位置。

全局搜索路径：对于工作区之外的环境（例如共享的~/envs文件夹)，使用python-envs.全局搜索路径输入：

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

此设置需要绝对路径，并在用户（全局）级别进行配置。

旧版设置：如果您之前使用过python.venvPath或python.venvFolders这些会自动与新的搜索路径合并。请考虑迁移到python-envs.全局搜索路径为了未来的兼容性。

选择一个环境

要使用发现的环境：

• 状态栏：选择Windows底部显示的Python版本
• 命令面板：运行 Python：选择解释器 并从列表中选择

所选环境用于运行代码、调试以及类似IntelliSense的语言特性。

在状态栏中选择Python版本以切换环境。 扩展如何自动选择：当您打开一个工作区而没有明确选择环境时，扩展会按以下顺序自动选择一个：

1. 工作区本地虚拟环境 (.venv，虚拟环境)
2. 全局/系统解释器

要覆盖此优先顺序，请设置python-envs.defaultEnvManager偏爱特定的经理（例如，ms-python.python:conda），或者配置Python 项目以进行每个文件夹的控制。旧版设置仍然受支持。

排除环境发现故障

对于高级故障排除，请直接运行Python环境工具（PET）以查看原始发现输出：

1. 打开命令面板
2. 运行 Python 环境：在终端中运行 Python 环境工具 (PET)...
3. 选择一个选项：
   • 查找所有环境：运行宠物查找 --详细列出所有发现的环境，并输出详细信息
   • 解析环境...：输入一个Python可执行文件的路径，以调试为什么特定环境没有被检测到

PET详细输出显示了发现的环境及其原因。

高级故障排除在以下场景中很有用：

• 您需要验证环境是否正在被检测
• 你想了解某个环境为何出现在特定经理之下
• 您正在调试路径解析问题

创建、删除和管理环境

创建环境

该扩展提供了两种创建环境的方法：快速创建 用于速度，和 自定义创建 用于控制。

快速创建

选择环境管理器视图中的+按钮。扩展执行以下步骤：

• 使用默认管理器（默认为venv，可以通过配置进行更改）python-envs.defaultEnvManager)
• 选择最新的可用Python版本
• 环境名称.venv（或.venv-1，.venv-2如果已经存在一个
• 安装依赖项来自要求.txt或pyproject.toml如果找到
• 选择新的环境为您的工作区

这是获取工作环境的最快方法。

快速创建构建了一个具有合理默认值的环境。

定制创建

为了更多的控制，请运行 Python: 创建环境 从命令面板，并按照提示进行操作：

1. 选择管理器：venv 或 conda
2. 选择Python版本：从发现的解释器（venv）或可用的Python版本（conda）中选择
3. 命名您的环境：输入自定义名称或接受默认值
4. 安装依赖：选择从安装要求.txt，pyproject.toml，或environment.yml

自定义创建允许您配置每个步骤。

使用UV以更快创建

如果uv已安装，该扩展将自动使用它来创建venv和安装包，这比标准工具快得多。用以下方法配置：

{
  "python-envs.alwaysUseUv": 真
}

当始终使用UV启用（默认），uv 管理所有虚拟环境。将其设置为假仅将uv用于明确由uv创建的环境。

支持的经理

删除环境

删除环境：

1. 在环境管理器视图中，找到环境
2. 右键单击并选择删除

删除环境会将环境文件夹从磁盘中移除。任何使用该环境的项目都需要您选择一个新的环境。

Python 项目

一个 Python 项目 是任何与特定环境相关联的文件或文件夹。默认情况下，您的整个工作区使用一个环境。项目允许您将不同的环境分配给不同的文件夹。这对于单库、微服务或在不同 Python 版本之间进行测试是必不可少的。

为什么要使用项目？

如果你的整个工作区只有一个环境，你不需要明确设置项目。选择一个解释器，你就完成了。

工作区
├── Python 项目: backend/
│     └── 环境: .venv (Python 3.12)
│            └── 管理器: venv
│
├── Python 项目: frontend-utils/
│     └── 环境: .venv (Python 3.10)
│            └── 管理器: venv
│
└── Python 项目: ml-pipeline/
       └── 环境: ml-env (Python 3.11)
              └── 管理器: conda

什么使用项目分配？

• 运行和调试：使用项目环境
• 终端：通过项目环境激活
• 测试浏览器：每个项目都有自己的测试树和自己的解释器（见多项目测试）

添加项目

将文件夹或文件视为独立项目：

1. 在资源管理器中右键点击它
2. 选择添加为Python项目

或者，选择 + 在 Python 项目 视图中，并选择以下任一选项：

• 添加现有：手动选择文件/文件夹
• 自动查找：发现包含 pyproject.toml或设置.py

添加现有文件夹或自动发现项目。

分配环境

一旦文件夹成为项目，请为其分配环境：

1. 在Python 项目视图中，点击项目下显示的环境（或“无环境”）
2. 从发现的环境中选择

所选择的环境将用于在该项目中运行或调试文件。

点击环境以更改。

设置如何保存

当您将环境分配给一个项目时，扩展会写入到您的工作区设置.vscode/settings.json):

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

请注意，设置存储的是环境管理器，而不是硬编码的解释器路径。该扩展记住您单独选择的特定环境，并在运行时解析它。这种设计使设置可以共享：

• 没有特定于机器的路径：队友不需要/用户/你的名字/.venv
• 可在系统之间便携：适用于macOS、Windows和Linux
• 在环境重建中幸存：如果你删除并重建.venv它仍然可以使用

与队友分享：

1. 提交.vscode/settings.json到你的仓库
2. 队友克隆并打开工作区
3. 他们创建自己的环境（快速创建在这里非常有效）
4. 该扩展会自动使用每个项目的配置经理

删除项目

右键单击“Python Projects”视图中的项目，选择“Remove Python Project”。这会移除映射。它不会删除任何文件。

从模板创建项目

为了用正确的结构搭建一个新项目，请在命令面板中运行Python Envs: 从模板创建新项目。选择其中一个：

• Package：创建一个文件夹，包含pyproject.toml, 包目录, 和测试
• 脚本：创建一个.py包含内联依赖元数据的文件（PEP 723）

查看完整的Python 项目指南以了解模板结构的详细信息。

了解更多

有关模板、多根工作区、常见场景和故障排除的详细指导，请参阅完整的Python 项目指南。

包管理

直接从 VS Code 安装和卸载 Python 软件包，无需打开终端。

安装软件包

1. 在环境管理器视图中，找到一个环境
2. 右键单击并选择管理程序包
3. 搜索软件包并选择您要安装的包

或者运行 Python Envs: 管理包 从命令面板。

直接从 VS Code 搜索和安装软件包。

从要求文件安装：您还可以从 要求.txt，pyproject.toml，或environment.yml当系统提示时，选择文件，扩展程序将自动安装所有列出的依赖项。

卸载软件包

1. 展开 环境管理器 视图以查看已安装的包
2. 右键点击一个包并选择卸载包

按环境分类的包管理器

该扩展会根据您的环境自动使用适当的包管理器：

要覆盖默认设置，请设置python-envs.默认包管理器输入：.

更快的安装速度与UV

如果 uv 已安装并且 python-envs.alwaysUseUv启用（默认），在venv环境中包的安装使用uv 管而不是常规的皮普, 对于大型依赖树，这要显著快得多。

设置和配置

本节涵盖所有扩展设置、解释器选择的工作原理以及旧版设置的迁移。

解释器选择优先级

当你打开一个工作区时，扩展程序通过按顺序检查这些来源来确定使用哪个环境：

基本原理：用户配置的设置始终优先于默认设置。如果您没有明确设置默认环境管理器（它有内置默认值），扩展跳过它并检查下一个优先级。

缓存：该扩展为了性能会缓存解析的环境，但您的显式设置始终优先于缓存的值。您永远无需担心过期的缓存会覆盖您的选择。

关于解释器选择行为的更多详细信息，请参见解释器选择快速参考。

当设置被写入

该扩展仅在您进行明确更改时才会写入设置：

这确保打开工作区不会在你的文件中添加自动生成的条目。settings.json输入：.

Python 环境设置

终端设置

当你在 VS Code 中打开一个终端时，扩展会自动激活你选择的 Python 环境，以便Python，皮普，以及相关命令使用正确的解释器。

终端激活类型：

为特定环境打开终端：

您可以打开一个新的终端，激活任何环境：

1. 在环境管理器视图中，找到环境
2. 右键单击并选择 在终端中打开

打开任何环境激活的终端。

有关详细的故障排除和激活原理，请参见终端自动激活解析。

支持 .env 文件

注入环境变量从一个环境变量文件将文件输入到你的终端：

1. 创建一个环境变量文件在你的工作区根目录下文件或指定一个自定义路径python.envFile
2. 设置python.terminal.useEnvFile到真

# .env
API_KEY=你的秘密密钥
DATABASE_URL=postgres://localhost/我的数据库

变量在终端创建时注入。这对于不应提交到源代码控制的开发凭证很有用。

遗留设置

这些设置仍然受支持，但有更新的替代设置：

设置作用域参考

设置的配置位置不同，其行为也会有所不同：

关键见解：工作区搜索路径必须在工作区或文件夹级别（而不是用户级别）设置，因为它相对于工作区文件夹。

可扩展性

Python Environments 扩展旨在具有可扩展性。任何环境或包管理器都可以构建一个扩展，插入到 Python 侧边栏中，与内置管理器并列出现。这意味着生态系统可以发展以支持新工具，而无需等待此扩展的更新。

社区成员正在为其他环境管理器构建扩展，例如Pixi扩展。

已知限制

Pylance 和 多项目工作区

Pylance 不支持在同一个工作区中使用不同解释器的多个 Python 项目。即使您使用 Python 项目 配置不同的文件夹各自的环境，Pylance 仍会为整个工作区使用一个解释器——通常是与工作区根目录关联的那一个。要为不同的文件夹使用不同的解释器，请将它们添加为工作区文件夹，在 多根工作区 中（文件 > 将文件夹添加到工作区），因为 Pylance 为每个工作区文件夹独立运行。

Jupyter 笔记本

Jupyter notebooks 不使用 Python Environments API 来发现环境。相反，它们依赖于较旧的 Python 扩展 API。这意味着 notebook kernel 选择的环境可能与 环境管理器 视图不同。

下一步

• Python 教程 - 在 VS Code 中开始使用 Python。
• 调试 - 学习如何调试你的Python代码。
• 测试 - 配置和运行您的Python项目的测试。
• 设置参考 - 探索所有 Python 扩展设置。