VS Code 中的 Python 环境

Python Environments 扩展将环境和包管理带入 Visual Studio Code 的界面。该扩展提供了一个统一的界面，用于创建环境、安装包和切换解释器，无论你是否使用解释器文,紫外线,康达,Pyenv,诗歌，或者PInv.

核心功能：

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

该扩展可以和 Python 扩展一起工作，且无需设置即可开始。

快速入门

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

如果你有一个基本的配置，比如整个工作区都有一个环境：

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

需要营造环境吗？打开Python侧边栏，展开环境管理器，然后选择+按钮。扩展会带你完成不同的步骤。

用户界面组件

环境发现

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

当扩展激活时，发现会自动执行。该扩展使用Python Environment Tool（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"]
}

建议：

• 用于递归搜索（例如，**./**/env找到任何名为环境无论深度如何）
• 相对路径是根据你工作区文件夹根节点解析的

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

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

添加自定义球状模式以搜索更多地点。

全局搜索路径：针对工作区外的环境（比如共享环境）~/envs文件夹），使用python-envs.globalSearchPaths:

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

该设置要求绝对路径，并在用户（全局）层面配置。

遗留设置：如果你之前用过python.venvPath或python.venvFolders这些路径会自动与新的搜索路径合并。考虑迁移到python-envs.globalSearchPaths为了未来的兼容性。

选择环境

使用发现环境：

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

所选环境用于运行代码、调试以及IntelliSense等语言功能。

在状态栏中选择Python版本以切换环境。 扩展的自动选择方式：当你在未明确选择环境的情况下打开工作区时，扩展会自动按以下顺序选择一个：

1. 工作区-本地虚拟环境（.venv,文)
2. 全局/系统解释器

要覆盖该优先级顺序，设python-envs.defaultEnvManager优先选择特定的管理者（例如，ms-python.python：conda），或配置Python项目以实现每个文件夹的控制。遗留设置依然支持。

排查环境发现问题

如需高级排查，可以直接运行 Python 环境工具（PET）查看原始发现结果：

1. 打开命令调色板
2. 运行Python环境：在终端中运行Python环境工具（PET）......
3. 选择一个选项：
   • 寻找所有环境：运行宠物发现——冗长列出所有发现的环境及其详细输出
   • Resolve Environment...：输入一条路径到一个 Python 可执行文件，以调试为何某个特定环境未被检测到

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

高级故障排除适用于以下场景：

• 你需要确认环境是否被检测到
• 你想理解为什么某个环境会出现在某个特定的管理者手下
• 你是在调试路径解析问题

创建、删除和管理环境

创建环境

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

快速创建

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

• 使用默认管理器（默认是venv，可以通过以下方式配置python-envs.defaultEnvManager)
• 选择最新的 Python 版本
• 命名环境.venv（或.venv-1,.venv-2如果已经存在的话）
• 安装依赖requirements.txt或pyproject.toml如果被发现
• 为你的工作区选择新环境

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

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

自定义创建

为了更好地控制，可以从命令调色板中运行 Python：创建环境，并逐一作提示：

1. 选择经理：venv或conda
2. 选择 Python 版本：从发现的解释器（venv）或可用的 Python 版本（conda）中选择
3. 给环境命名：输入自定义名称或默认使用
4. 安装依赖：选择安装requirements.txt,pyproject.toml，或者environment.yml

自定义创建允许你配置每一步。

利用紫外线加快创作速度

如果安装了 UV，扩展会自动使用它来创建 venv 和安装包，这比标准工具快得多。配置如下：

{
  "python-envs.alwaysUseUv": true
}

当alwaysUseUv启用（默认），UV管理所有虚拟环境。设置为错误只在UV明确创建的环境中使用紫外线。

支持的经理

删除环境

要删除环境：

1. 在环境经理视图中，查找环境
2. 右键点击并选择删除

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

Python 项目

Python 项目是指你想与特定环境关联的任何文件或文件夹。默认情况下，你的整个工作区都使用一个环境。项目允许你为不同的文件夹分配不同的环境。这对于单仓库、微服务或跨 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

项目作业是怎么用的？

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

添加一个项目

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

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

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

• 添加现有文件：手动选择文件/文件夹
• 自动查找：发现文件夹pyproject.toml或setup.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"
    }
  ]
}

注意设置存储的是环境管理器，而不是硬编码的解释器路径。扩展会记住你单独选择的具体环境，并在运行时解析它。这种设计使场景可共享：

• 没有机器专用路径：队友不需要/用户/yourname/.venv
• 跨系统可移植：适用于macOS、Windows和Linux。
• 环境重建后存活：如果你删除并重建.venv，它依然有效

与队友分享：

1. 提交.vscode/settings.json归你的收车
2. 队友们克隆并打开工作区
3. 他们自己创建环境（快速创建在这里效果很好）
4. 扩展会自动使用每个项目配置的管理器

移除项目

在 Python 项目视图中右键点击一个项目，然后选择“移除 Python 项目”。这样会去除映射。它不会删除任何文件。

从模板创建一个项目

要搭建一个结构正确的新项目，请在命令调色板中运行 Python Envs： 从模板创建新项目。请选择：

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

关于模板结构的详细信息，请参见完整的 Python 项目指南。

了解更多

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

包管理

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

安装包

1. 在环境管理器视图中，找到一个环境
2. 右键点击并选择“管理包”
3. 搜索软件包，选择你想安装的

或者从命令面板里运行 Python Envs： Manage Packages。

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

从需求文件安装：你也可以从以下文件安装包requirements.txt,pyproject.toml，或者environment.yml.提示时，选择文件，扩展名会安装所有列出的依赖。

卸载包

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

按环境分类的包管理器

扩展会自动根据你的环境使用相应的包管理器：

要覆盖默认值，设python-envs.defaultPackageManager.

用紫外线更快安装

如果安装了UV和python-envs.alwaysUseUv是启用的（默认），在 VEN 环境中安装包使用紫外线点而不是普通PIP对于大型依赖树，这要快得多。

设置与配置

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

解释器选择优先级

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

关键原则：用户自定义的设置总是胜过默认设置。如果你没有明确设置defaultEnvManager（它内置默认），扩展跳过该优先级并检查下一个优先级。

缓存：扩展缓存已解析的环境以提升性能，但你的显式设置始终优先于缓存值。你永远不用担心陈旧缓存覆盖你的选择。

有关解释器选择行为的更多细节，请参见解释器选择快速参考。

当设定被写入时

扩展只有在你明确更改设置时才会写入：

这样可以确保打开工作区不会为你的自动生成条目添加settings.json.

Python 环境设置

终端设置

当你在VS Code中打开终端时，扩展会自动激活你选择的Python环境，这样派森,PIP，以及相关命令使用正确的解释器。

终端激活类型：

为特定环境打开终端：

你可以在激活任何环境的情况下打开新的终端：

1. 在环境经理视图中，查找环境
2. 右键点击并选择“在终端中打开”

打开任何环境的终端。

关于详细的故障排查及激活的底层工作原理，请参见《终端自动激活解释》。

.env 文件支持

从.env请提交到您的终端：

1. 创建一个.env文件在你的工作区根目录中，或者指定一个自定义路径，使用python.envFile
2. 赛场python.terminal.useEnvFile到确实如此

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

变量在终端创建时被注入。这对开发凭证非常有用，而这些资质本不该被提交到源码控制。

遗留设定

这些 Python 扩展中的设置仍然被支持，但有更新的对应版本：

设置范围参考

设置的行为会根据配置位置不同而有所不同：

关键见解：workspaceSearchPaths必须设置为工作区或文件夹层面（而非用户层面），因为它是相对于工作区文件夹的。

可扩展性

Python 环境扩展设计为可扩展性。任何环境或包管理器都可以构建一个扩展，插入 Python 侧边栏，与内置管理器并列显示。这意味着生态系统可以发展以支持新工具，而无需等待该扩展的更新。

社区成员正在为额外的环境管理者（如Pixi扩展）建设扩展。

已知的局限性

Pylance 与多项目工作区

Pylance 不支持同一工作区内使用不同解释器的多个 Python 项目。即使你用 Python 项目为不同文件夹配置了不同的环境，Pylance 也会用一个解释器来管理整个工作区——通常是与工作区根连接的那个。要为不同文件夹使用不同的解释器，可以在多根工作区中添加它们作为工作区文件夹（文件>添加到工作区），因为 Pylance 在每个工作区文件夹中独立运行。

Jupyter笔记本

Jupyter 笔记本不使用 Python 环境 API 进行环境发现。相反，他们依赖较早的 Python 扩展 API。这意味着笔记本内核选择可能显示的环境集与环境管理器视图不同。

下一步

• Python 教程——开始使用 VS Code 学习 Python。
• 调试——学会调试你的Python代码。
• 测试——配置并运行你的Python项目测试。
• 设置参考——探索所有 Python 扩展设置。