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 一起安装。它可以用来管理包和虚拟环境。通常用于数据科学项目。

创建环境

使用“创建环境”命令

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

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

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

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

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

注意：该命令还会安装项目文件夹中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 中会显示一个提示，允许您为工作区选择它。

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

在终端中创建 conda 环境

Python 扩展会自动检测现有的 conda 环境。我们建议您在 conda 环境中安装一个 Python 解释器，否则，在您选择环境后，系统会为您安装一个。例如，以下命令会创建一个名为 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: 选择解释器窗口右上角的刷新图标；否则，您可能无法在其中找到该环境。

  

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

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

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

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

使用 Python 解释器

选择并激活环境

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

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

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

注意：在 Windows 上，VS Code 可能需要一些时间才能检测到可用的 conda 环境。在此过程中，您可能会在环境路径之前看到“（缓存）”。该标签表示 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 属性中指定不同的路径来覆盖此行为。请参阅 选择调试环境。

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

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

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

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

手动指定解释器

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

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

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

如果您要手动指定一个默认解释器，该解释器将在您第一次打开工作区时使用，则可以为 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 的一级子文件夹中查找虚拟环境。
• 位于 ~/.virtualenvs 文件夹中用于 virtualenvwrapper 的虚拟环境。
• 由 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 变量将覆盖 python.envFile 设置（用户或工作区）指定的 .env 文件中包含的变量。同样，launch.json 文件中定义的 env 变量将覆盖 launch.json 中指定的 envFile 中定义的环境变量。

PYTHONPATH 变量的使用

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

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

后续步骤

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

更多 Python 资源

• VS Code 中的 Python 入门 - 学习如何在 VS Code 中编辑、运行和调试代码。
• 虚拟环境和包 (Python.org) - 了解有关虚拟环境和包的更多信息。
• 安装 Python 模块 (Python.org) - 学习如何安装 Python 模块。
• Python 教程 (Python.org) - 了解有关 Python 语言的更多信息。