参加你附近的 ，了解 VS Code 中的 AI 辅助开发。

VS Code 中的 Python 环境

Python 中的“环境”是 Python 程序运行的上下文，由解释器和任意数量的已安装包组成。

注意：如果您想更熟悉 Python 编程语言，请查阅更多 Python 资源。

Python 环境的类型

全局环境

默认情况下，任何安装的 Python 解释器都在其自己的全局环境中运行。例如，如果您在新终端中运行python、python3或py（取决于您安装 Python 的方式），您就在该解释器的全局环境中运行。您安装或卸载的任何包都会影响全局环境和您在该环境中运行的所有程序。

提示：在 Python 中，最佳实践是创建特定于工作区的环境，例如，使用本地环境。

本地环境

您可以为工作区创建两种类型的环境：虚拟环境和 conda 环境。这些环境允许您安装包，而不会影响其他环境，从而隔离工作区的包安装。

虚拟环境

虚拟环境是一种创建环境的内置方式。虚拟环境会创建一个文件夹，其中包含特定解释器的副本（或符号链接）。当您将包安装到虚拟环境时，它们将进入此新文件夹，从而与其他工作区使用的其他包隔离。

注意：虽然可以将虚拟环境文件夹作为工作区打开，但这样做不建议，并可能导致使用 Python 扩展时出现问题。

Conda 环境

conda 环境是使用conda包管理器管理的 Python 环境（请参阅Conda 入门）。选择 conda 环境还是虚拟环境取决于您的包需求、团队标准等。

Python 环境工具

下表列出了与 Python 环境相关的各种工具

工具 定义和目的
pip 安装和更新包的 Python 包管理器。它默认随 Python 3.9+ 安装（除非您使用的是基于 Debian 的操作系统；在这种情况下，请安装python3-pip）。
venv 允许您管理不同项目的独立包安装，默认随 Python 3 安装（除非您使用的是基于 Debian 的操作系统；在这种情况下，请安装python3-venv）
conda 随Miniconda安装。它可用于管理包和虚拟环境。通常用于数据科学项目。

创建环境

使用“创建环境”命令

要在 VS Code 中使用虚拟环境或 Anaconda 创建本地环境，您可以按照以下步骤操作：打开命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)），搜索Python: 创建环境命令，然后选择它。

该命令显示环境类型列表：Venv或Conda。

Create Environment dropdown

如果您使用 Venv 创建环境，该命令会显示可用作新虚拟环境基础的解释器列表。

Virtual environment interpreter selection

如果您使用 Conda 创建环境，该命令会显示可用于您项目的 Python 版本列表。

Conda environment Python version selection

选择所需的解释器或 Python 版本后，通知将显示环境创建进度，并且环境文件夹将出现在您的工作区中。

Create environment status notification

注意：该命令还将安装项目文件夹中 requirements/dependencies 文件（例如requirements.txt、pyproject.toml或environment.yml）中概述的必要包。它还会将.gitignore文件添加到虚拟环境，以帮助防止您意外地将虚拟环境提交到源代码管理。

在终端中创建虚拟环境

如果您选择手动创建虚拟环境，请使用以下命令（其中“.venv”是环境文件夹的名称）

# macOS/Linux
# You may need to run `sudo apt-get install python3-venv` first on Debian-based OSs
python3 -m venv .venv

# Windows
# You can also use `py -3 -m venv .venv`
python -m venv .venv

注意：要了解有关venv模块的更多信息，请阅读 Python.org 上的虚拟环境的创建。

当您创建新的虚拟环境时，VS Code 中将显示一个提示，允许您为工作区选择它。

Python environment prompt

提示：请务必更新您的源代码管理设置，以防止意外提交您的虚拟环境（例如在.gitignore中）。由于虚拟环境不可移植，因此通常没有必要提交它们供他人使用。

在终端中创建 conda 环境

Python 扩展会自动检测现有的 conda 环境。我们建议您将 Python 解释器安装到您的 conda 环境中，否则在您选择环境后，系统将为您安装一个。例如，以下命令创建一个名为env-01的 conda 环境，其中包含 Python 3.9 解释器和几个库

conda create -n env-01 python=3.9 scipy=0.15.0 numpy

注意：有关 conda 命令行的更多信息，您可以阅读Conda 环境。

附加说明

  • 如果在 VS Code 运行时创建新的 conda 环境，请使用Python: 选择解释器窗口右上角的刷新图标；否则您可能无法在那里找到该环境。

    Conda environment refresh icon

  • 为了确保从 shell 角度正确设置环境，请使用 Anaconda 提示符并激活所需的环境。然后，您可以通过输入code .命令启动 VS Code。一旦 VS Code 打开，您可以通过使用命令面板或单击状态栏来选择解释器。

  • 尽管 VS Code 的 Python 扩展目前没有与 conda environment.yml文件直接集成，但 VS Code 本身就是一个出色的 YAML 编辑器。

  • 如果默认 shell 设置为 PowerShell，则 conda 环境无法在 VS Code 集成终端中自动激活。要更改 shell，请参阅集成终端 - 终端配置文件。

  • 您可以手动指定用于激活conda可执行文件的路径（版本 4.4+）。为此，请打开命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）并运行首选项：打开用户设置。然后，将用户设置的 Python 扩展部分中的python.condaPath设置为适当的路径。

使用 Python 解释器

选择并激活环境

Python 扩展会尝试查找并选择它认为最适合工作区的环境。如果您希望选择特定环境，请从命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）使用Python: 选择解释器命令。

Python: Select Interpreter command

注意：如果 Python 扩展未找到解释器，它会发出警告。在 macOS 12.2 及更早版本上，如果您使用 OS 安装的 Python 解释器（因为它已知存在兼容性问题），该扩展还会发出警告。在任何一种情况下，您都可以通过在用户设置中将python.disableInstallationCheck设置为true来禁用这些警告。

Python: 选择解释器命令显示可用全局环境、conda 环境和虚拟环境的列表。（有关详细信息，包括这些环境类型之间的区别，请参阅扩展查找环境的位置部分。）例如，下图显示了几个 Anaconda 和 CPython 安装以及一个 conda 环境和一个位于工作区文件夹中的虚拟环境（env）

List of interpreters

注意：在 Windows 上，VS Code 可能需要一些时间才能检测到可用的 conda 环境。在此过程中，您可能会在环境路径之前看到“(cached)”。该标签表示 VS Code 当前正在处理该环境的缓存信息。

如果您在 VS Code 中打开了一个文件夹或工作区，并从列表中选择了一个解释器，Python 扩展将在内部存储该信息。这可确保在您重新打开工作区时使用相同的解释器。

Python 扩展使用选定的环境来运行 Python 代码（使用Python: 在终端中运行 Python 文件命令）、在编辑器中打开.py文件时提供语言服务（自动完成、语法检查、代码检查、格式化等），以及使用终端: 创建新终端命令打开终端。在后一种情况下，VS Code 会自动激活选定的环境。

提示：要阻止自动激活选定的环境，请将"python.terminal.activateEnvironment": false添加到您的settings.json文件（它可以作为现有设置的兄弟放置在任何位置）。

提示：如果激活命令生成消息“Activate.ps1 未进行数字签名。您无法在当前系统上运行此脚本。”，那么您需要暂时更改 PowerShell 执行策略以允许脚本运行（请参阅 PowerShell 文档中的关于执行策略）：Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

注意：默认情况下，VS Code 在调试代码时使用为您的工作区选择的解释器。您可以通过在调试配置的python属性中指定不同的路径来覆盖此行为。请参阅选择调试环境。

选定的解释器版本将显示在状态栏的右侧。

Status Bar showing a selected interpreter

状态栏也反映了未选择解释器的情况。

Status bar showing no selected Python interpreter

在任何一种情况下，单击状态栏的此区域都是Python: 选择解释器命令的便捷快捷方式。

提示：如果您在 VS Code 识别虚拟环境方面遇到任何问题，请提交问题，以便我们帮助确定原因。

手动指定解释器

如果 VS Code 未自动找到您要使用的解释器，您可以在文件系统上浏览解释器或手动提供其路径。

您可以通过运行Python: 选择解释器命令并选择解释器列表顶部显示的输入解释器路径...选项来执行此操作

Enter interpreter path option on the interpreters list

然后，您可以直接在文本框中输入 Python 解释器的完整路径（例如，“.venv/Scripts/python.exe”），或者您可以选择查找...按钮并浏览您的文件系统以找到您希望选择的 python 可执行文件。

Enter path or browse for an interpreter

如果您想手动指定在首次打开工作区时使用的默认解释器，您可以为python.defaultInterpreterPath设置创建或修改一个条目。

注意：为工作区选择解释器后，对python.defaultInterpreterPath设置的更改不会生效；一旦为工作区选择初始解释器，对该设置的任何更改都将被忽略。

此外，如果您想为所有 Python 应用程序设置默认解释器，您可以在用户设置中手动添加python.defaultInterpreterPath的条目。为此，请打开命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）并输入首选项：打开用户设置。然后，将用户设置的 Python 扩展部分中的python.defaultInterpreterPath设置为适当的解释器。

扩展如何自动选择环境

如果未指定解释器，则 Python 扩展会按照以下优先级顺序自动选择版本最高的解释器

  1. 直接位于工作区文件夹下的虚拟环境。
  2. 与工作区相关但全局存储的虚拟环境。例如，位于工作区文件夹外部的Pipenv或Poetry环境。
  3. 全局安装的解释器。例如，在/usr/local/bin、C:\\python38等中找到的解释器。

注意：选择的解释器可能与终端中python所指的解释器不同。

如果 Visual Studio Code 未自动找到您的解释器，您可以手动指定解释器。

扩展查找环境的位置

扩展会自动在以下位置查找解释器，不分先后顺序

  • 标准安装路径，例如/usr/local/bin、/usr/sbin、/sbin、c:\\python36等。
  • 直接位于工作区（项目）文件夹下的虚拟环境。
  • 位于由python.venvPath设置标识的文件夹中的虚拟环境（请参阅通用 Python 设置），该文件夹可以包含多个虚拟环境。扩展在venvPath的一级子文件夹中查找虚拟环境。
  • 位于virtualenvwrapper的~/.virtualenvs文件夹中的虚拟环境。
  • 由pyenv、Pipenv和Poetry创建的解释器。
  • 位于WORKON_HOME标识的路径中的虚拟环境（由virtualenvwrapper使用）。
  • conda env list找到的 Conda 环境。没有解释器的 Conda 环境将在选择后为其安装一个解释器。
  • 在工作区文件夹下direnv的.direnv文件夹中安装的解释器。

环境和终端窗口

使用Python: 选择解释器后，右键单击文件并选择Python: 在终端中运行 Python 文件时，将应用该解释器。除非您将python.terminal.activateEnvironment设置更改为false，否则当您使用终端: 创建新终端命令时，环境也会自动激活。

请注意，从激活了特定 Python 环境的 shell 启动 VS Code 不会自动在默认集成终端中激活该环境。

注意：如果 PowerShell 设置为集成 shell，则无法在集成终端中自动激活 conda 环境。请参阅集成终端 - 终端配置文件了解如何更改 shell。

使用Python: 选择解释器命令更改解释器不会影响已打开的终端面板。因此，您可以在拆分终端中激活单独的环境：选择第一个解释器，为其创建终端，选择不同的解释器，然后使用终端标题栏中的拆分按钮（⌘\ (Windows, Linux Ctrl+Shift+5)）。

选择调试环境

默认情况下，调试器将使用通过 Python 扩展选择的 Python 解释器。但是，如果在launch.json的调试配置中指定了python属性，则它具有优先级。如果未定义此属性，它将回退到使用为工作区选择的 Python 解释器路径。

有关调试配置的更多详细信息，请参阅调试配置。

环境变量

环境变量定义文件

环境变量定义文件是一个文本文件，其中包含environment_variable=value形式的键值对，并使用#进行注释。不支持多行值，但允许引用以前定义的环境变量。环境变量定义文件可用于调试和工具执行（包括代码检查器、格式化程序、IntelliSense 和测试工具）等场景，但不适用于终端。

注意：环境变量定义文件不一定跨平台。例如，虽然 Unix 在环境变量中将:用作路径分隔符，但 Windows 使用;。对此类操作系统差异没有进行标准化，因此您需要确保任何环境定义文件都使用与您的操作系统兼容的值。

默认情况下，Python 扩展会在当前工作区文件夹中查找并加载名为.env的文件，然后应用这些定义。该文件由用户设置中的默认条目"python.envFile": "${workspaceFolder}/.env"标识（请参阅通用 Python 设置）。您可以随时更改python.envFile设置以使用不同的定义文件。

注意：环境变量定义文件并非在所有可以使用环境变量的情况下都使用。除非 Visual Studio Code 文档另有说明，否则这些文件仅根据其定义影响某些场景。例如，扩展在解析设置值时不使用环境变量定义文件。

调试配置还包含一个envFile属性，该属性也默认为当前工作区中的.env文件（请参阅调试 - 设置配置选项）。此属性允许您轻松设置用于调试目的的变量，这些变量会替换默认.env文件中指定的变量。

例如，在开发 Web 应用程序时，您可能希望在开发服务器和生产服务器之间轻松切换。您可以使用单独的定义文件来替代将不同的 URL 和其他设置直接编码到应用程序中。例如

dev.env 文件

# dev.env - development configuration

# API endpoint
MYPROJECT_APIENDPOINT=https://my.domain.com/api/dev/

# Variables for the database
MYPROJECT_DBURL=https://my.domain.com/db/dev
MYPROJECT_DBUSER=devadmin
MYPROJECT_DBPASSWORD=!dfka**213=

prod.env 文件

# prod.env - production configuration

# API endpoint
MYPROJECT_APIENDPOINT=https://my.domain.com/api/

# Variables for the database
MYPROJECT_DBURL=https://my.domain.com/db/
MYPROJECT_DBUSER=coreuser
MYPROJECT_DBPASSWORD=kKKfa98*11@

然后您可以将python.envFile设置设置为${workspaceFolder}/prod.env，然后将调试配置中的envFile属性设置为${workspaceFolder}/dev.env。

注意：当使用多种方法指定环境变量时，请注意存在优先级顺序。launch.json文件中定义的所有env变量将覆盖.env文件（由python.envFile设置指定，用户或工作区）中包含的变量。同样，launch.json文件中定义的env变量将覆盖launch.json中指定的envFile中定义的环境变量。

PYTHONPATH 变量的使用

PYTHONPATH环境变量指定 Python 解释器应查找模块的其他位置。在 VS Code 中，PYTHONPATH 可以通过终端设置（terminal.integrated.env.*）和/或在.env文件中设置。

当使用终端设置时，PYTHONPATH 会影响用户在终端中运行的任何工具，以及扩展为用户执行的任何通过终端路由的操作，例如调试。但是，在这种情况下，当扩展执行的操作未通过终端路由时，例如使用代码检查器或格式化程序，则此设置不会影响模块查找。

后续步骤

  • 编辑代码 - 了解 Python 的自动完成、IntelliSense、格式设置和重构。
  • 调试 - 了解如何在本地和远程调试 Python。
  • 测试 - 配置测试环境以及发现、运行和调试测试。
  • 设置参考 - 探索 VS Code 中所有与 Python 相关的设置。

更多 Python 资源

09/11/2025