在 VS Code 中使用 Python 环境

原文地址：https://code.visualstudio.com/docs/python/environments

本文讨论了 VS Code Python 扩展提供的用于处理 Python 环境的有用功能。Python 中的“环境”是 Python 程序运行的上下文，由解释器和任意数量的已安装包组成。读完本文后，您将对以下内容有一个很好的了解：

• 一般环境概念
• 如何选择环境
• 如何创建虚拟或conda环境
• 如何选择和激活虚拟环境
• 如何使用环境和终端窗口
• Python 扩展在哪里寻找环境
• 环境变量和环境变量定义文件 (.env)

虽然本文提供了有关 Python 环境及其概念的一些信息，但主要是为了了解如何在 VS Code 中使用它们。如果您不熟悉 Python 环境，可以在虚拟环境和包 (Python.org)和安装 Python 模块 (Python.org) 中了解更多信息。

注意：如果您希望在 Visual Studio Code 中开始使用 Python，请参阅教程在 VS Code 中使用 Python。如果您不熟悉Python 语言，Python 教程 (Python.org)也可能会有所帮助。

全局和虚拟环境#

默认情况下，您安装的任何 Python 解释器都在其自己的全局环境中运行，这并不特定于任何一个项目。例如，如果您只是在新的命令提示符下运行python，那么您正在该解释器的全局环境中运行。因此，您安装或卸载的任何软件包都会影响全局环境以及您在该上下文中运行的所有程序。

尽管在全局环境中工作是一种简单的入门方法，但随着时间的推移，该环境会变得杂乱无章，其中包含您为不同项目安装的许多不同软件包。这种混乱使得针对一组具有已知版本的特定软件包彻底测试应用程序变得困难。

出于这个原因，开发人员经常为项目创建一个虚拟环境。虚拟环境是项目中包含特定解释器副本的子文件夹。当您激活虚拟环境时，您安装的任何软件包仅安装在该环境的子文件夹中。然后，当您在该环境中运行 Python 程序时，您就会知道它仅针对那些特定的包运行。。

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

conda环境#

conda 环境是使用conda包管理器管理的 Python 环境（请参阅conda入门(conda.io)）。Conda 可以很好地创建具有相互关联的依赖项以及二进制包的环境。与仅限于项目的虚拟环境不同，conda 环境可在任何给定计算机上全局使用。这种可用性使配置多个不同的 conda 环境变得容易，然后为任何给定项目选择合适的环境。

扩展寻找环境的地方#

该扩展程序会自动在以下位置寻找解析器：

• 标准的安装路径，例如/usr/local/bin，/usr/sbin，/sbin，c:\\python27，c:\\python36，等。
• 直接位于工作区（项目）文件夹下的虚拟环境。
• 位于由python.venvPath设置标识的文件夹中的虚拟环境（请参阅常规设置），其中可以包含多个虚拟环境。该扩展在venvPath.
• 位于virtualenvwrapper~/.virtualenvs文件夹中的虚拟环境。
• 由pyenv、Pipenv和Poetry安装的解释器。
• 位于由WORKON_HOME（由virtualenvwrapper 使用）标识的路径中的虚拟环境。
• 包含 Python 解释器的 Conda 环境。VS Code 不显示不包含解释器的 conda 环境。
• 安装在.direnv的文件夹direnv工作区（项目）文件夹下。

如果 Visual Studio Code 没有自动定位，您也可以手动指定解释器。

注意：一旦触发“选择解释器”流程，将搜索工作区文件夹的pipenv环境。如果找到，则不会搜索或列出其他解释器，因为 pipenv 期望管理所有方面。

该扩展还加载由设置标识的环境变量定义文件python.envFile。此设置的默认值为${workspaceFolder}/.env。

使用环境#

创建虚拟环境#

要创建虚拟环境，请使用以下命令，其中“.venv”是环境文件夹的名称：

# macOS/Linux
# You may need to run sudo apt-get install python3-venv first
python3 -m venv .venv

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

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

创建新的虚拟环境时，将显示提示以允许您为工作区选择它。

这会将 Python 解释器的路径从新的虚拟环境添加到您的工作区设置。然后在通过 Python 扩展安装包和运行代码时将使用该环境。有关在项目中使用虚拟环境的示例，请参阅Python、Django和Flask教程。

提示：当您准备好将应用程序部署到其他计算机时，您可以使用pip freeze > requirements.txt命令创建一个文件requirements.txt。需求文件描述了您在虚拟环境中安装的软件包。使用此文件，就可以使用pip install -r requirements.txt恢复这些包。通过使用需求文件，您无需将虚拟环境本身提交给源代码控制。

创建 conda 环境#

如果环境包含 Python 解释器，Python 扩展会自动检测现有的 conda 环境。例如，以下命令使用 Python 3.4 解释器和几个库创建 conda 环境，然后 VS Code 将显示在可用解释器列表中：

conda create -n env-01 python=3.4 scipy=0.15.0 astroid babel

相反，如果您未能指定解释器，如conda create --name env-00，环境将不会出现在列表中。

有关conda命令行的更多信息，请参阅Conda 环境(conda.io)。

补充笔记：

• 如果在 VS Code 运行时创建新的 conda 环境，请使用Reload Window命令刷新Python显示的环境列表**： Select Interpreter**；否则你可能看不到那里的环境。可能需要很短的时间才会出现；如果您一开始没有看到它，请等待 15 秒，然后再次尝试使用该命令。
• 为了从 shell 的角度确保环境设置良好，一种选择是使用 Anaconda 提示符，在激活的环境下使用code .命令启动 VS Code 。此时，您只需要使用命令面板或单击状态栏来选择解释器。
• 尽管 VS Code 的 Python 扩展目前没有与 conda environment.yml 文件直接集成，但 VS Code 本身是一个很棒的 YAML 编辑器。
• 如果默认 shell 设置为 PowerShell，则无法在 VS Code 集成终端中自动激活 Conda 环境。要更改外壳，请参阅集成终端 - 配置。
• 您可以手动指定用于激活的 conda 可执行文件的路径（版本 4.4+）。为此，请打开命令面板 ( Ctrl+Shift+P ) 并输入Preferences: Open User Settings。然后使用适当的路径设置位于用户设置的 Python 扩展部分中的 python.condaPath。

选择并激活环境#

默认情况下，Python 扩展会查找并使用它在系统路径中找到的第一个 Python 解释器。要选择特定环境，请使用Python：从命令面板中****选择解释器命令( Ctrl+Shift+P )。

注意：如果 Python 扩展找不到解释器，则会发出警告。在 macOS 上，如果您使用的是操作系统安装的 Python 解释器，该扩展还会发出警告，因为您通常希望使用直接安装的解释器。无论哪种情况，您都可以通过在用户设置中设置python.disableInstallationCheck为来禁用这些警告。true

您可以随时切换环境；切换环境可帮助您根据需要使用不同的解释器或库版本测试项目的不同部分。

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

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

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

Python 扩展使用选定的环境来运行 Python 代码（使用Python：在终端中运行 Python 文件命令），当您在终端中打开.py文件时。或使用Terminal: Create New Integrated Terminal命令打开一个终端。在后一种情况下，VS Code 会自动激活所选环境。

提示：为防止自动激活所选环境，请添加 "python.terminal.activateEnvironment": false到您的settings.json文件中（它可以作为现有设置的同级放在任何地方）。

提示：如果激活命令生成消息“Activate.ps1 is not digitally signed. You cannot run this script on the current system.”，则需要临时更改 PowerShell 执行策略以允许脚本运行（请参阅关于执行策略在 PowerShell 文档中）： Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

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

状态栏始终显示当前的解释器。

状态栏也会反映没有选择解释器。

无论哪种情况，单击状态栏的这个区域都是Python的便捷快捷方式**：选择解释器**命令。

提示：如果您在 VS Code 识别虚拟环境时遇到任何问题，请在扩展存储库中提出问题，以便我们帮助确定原因。

手动指定解释器#

如果 VS Code 没有自动定位您要使用的解释器，您可以浏览文件系统上的解释器或手动提供它的路径。

您可以通过运行Python: Select Interpreter命令并单击显示在解释器列表顶部的**Enter interpreter path…**选项来执行此操作：

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

如果要手动指定在首次打开工作区后将使用的默认解释器，可以使用Python 可执行文件的完整路径创建或修改python.defaultInterpreterPath工作区中的设置条目settings.json。

例如：

• Windows：

  {
    "python.defaultInterpreterPath": "c:/python39/python.exe"
  }
  

• macOS/Linux：

  {
    "python.defaultInterpreterPath": "/home/python39/python"
  }
  

您还可以使用python.defaultInterpreterPath指向虚拟环境，例如：

• Windows：

  {
    "python.defaultInterpreterPath": "c:/dev/ala/venv/Scripts/python.exe"
  }
  

• macOS/Linux：

  {
    "python.defaultInterpreterPath": "/home/abc/dev/ala/venv/bin/python"
  }
  

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

此外，如果您想为所有 Python 应用程序设置默认解释器，您可以在用户设置中手动添加一个条目python.defaultInterpreterPath。为此，请打开命令面板 ( Ctrl+Shift+P ) 并输入Preferences: Open User Settings。然后使用适当的解释器设置python.defaultInterpreterPath，它位于用户设置的 Python 扩展部分。

您还可以使用语法在路径设置中使用环境变量${env:VARIABLE}。例如，如果您创建了一个以解释器路径命名的变量PYTHON_INSTALL_LOC，则可以使用以下设置值：

"python.defaultInterpreterPath": "${env:PYTHON_INSTALL_LOC}",

注意：变量替换仅在 VS Code 设置文件中受支持，在.env环境文件中不起作用。

通过使用环境变量，您可以轻松地在路径不同的操作系统之间转移项目，只需确保先在操作系统上设置环境变量即可。

环境和终端窗口#

使用Python: Select Interpreter 后，当右键单击文件并选择Python: Run Python File in Terminal时应用该解释器。当您使用“**终端：创建新的集成终端”**命令时，环境也会自动激活，除非您将python.terminal.activateEnvironment设置更改为false。

但是，从已激活特定 Python 环境的 shell 启动 VS Code 不会在默认集成终端中自动激活该环境。使用终端：在 VS Code 运行后创建新的集成终端命令。

**注意：**如果 PowerShell 设置为集成 shell，则无法在集成终端中自动激活 conda 环境。有关如何更改外壳的信息，请参阅集成终端 - 配置。

您对终端内激活的环境所做的任何更改都是持久的。例如，conda install <package>在激活 conda 环境的情况下从终端使用会将软件包永久安装到该环境中。类似地，pip install在激活了虚拟环境的终端中使用会将包添加到该环境中。

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

选择调试环境#

默认情况下，调试器将使用您选择的带有 Python 扩展的 Python 解释器。但是，如果您python在 的调试配置中有一个属性，launch.json则会改用该解释器。更具体地讲，VS代码会给优先于python所选择的调试配置的性能launch.json。如果未定义，则它将使用您为工作区选择的 Python 解释器的路径。

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

环境变量#

环境变量定义文件#

环境变量定义文件是一个简单的文本文件，包含格式为 的键值对environment_variable=value，#用于注释。不支持多行值，但值可以引用系统中或文件中更早版本中已定义的任何其他环境变量。有关更多信息，请参阅变量替换。环境变量定义文件可用于调试和工具执行等场景（包括linter、格式化程序、IntelliSense 和测试工具），但不适用于终端。

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

调试配置还包含一个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。

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

变量替换#

在定义文件中定义环境变量时，您可以通过以下通用语法使用任何现有环境变量的值：

<VARIABLE>=...${env:EXISTING_VARIABLE}...

where...表示值中使用的任何其他文本。花括号是必需的。

在此语法中，以下规则适用：

• 变量按照它们在.env文件中出现的顺序进行处理，因此您可以使用之前在文件中定义的任何变量。
• 单引号或双引号不影响替换值并包含在定义的值中。例如，如果值VAR1是abcedfg，则VAR2='${env:VAR1}'分配值'abcedfg'给VAR2。
• 该$角色可以用一个反斜杠转义，如\$。
• 您可以使用递归替换，例如PYTHONPATH=${env:PROJ_DIR}:${env:PYTHONPATH}(wherePROJ_DIR是任何其他环境变量)。
• 您只能使用简单的替换；${_${env:VAR1}_EX}不支持诸如此类的嵌套。
• 语法不受支持的条目保持原样。

使用 PYTHONPATH 变量#

在PYTHONPATH环境变量指定其他地点在Python解释器应该寻找模块。在 VS Code 中，可以通过终端设置 (terminal.integrated.env.*) 和/或在.env文件中设置 PYTHONPATH 。

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

当使用.env文件设置 PYTHONPATH 时，它将影响扩展代表您所做的任何事情以及调试器执行的操作，但不会影响在终端中运行的工具。

如果需要，您可以使用这两种方法设置 PYTHONPATH。

何时使用 PYTHONPATH 的一个示例是，如果您在src文件夹中有源代码并在tests文件夹中有测试。但是，在运行测试时，src除非您对相对路径进行硬编码，否则这些测试通常无法访问模块。

为了解决这个问题，你可以src通过.env在你的 VS Code 工作区中创建一个文件来添加到 PYTHONPATH的路径。

PYTHONPATH=src

然后python.envFile在您的settings.json文件中设置指向.env您刚刚创建的文件。例如，如果该.env文件位于您的工作区根目录中，则您的settings.json设置如下所示：

"python.envFile": "${workspaceFolder}/.env"

PYTHONPATH 的值可以包含多个由os.pathsep以下分隔的位置：;Windows 上的分号 ( ) 和:Linux/macOS 上的冒号 ( )。无效的路径被忽略。如果您发现 PYTHONPATH 的值没有按预期工作，请确保在操作系统的位置之间使用正确的分隔符。例如，在 Windows 上使用冒号分隔位置，或在 Linux/macOS 上使用分号分隔位置会导致 PYTHONPATH 的值无效，该值将被忽略。

注：PYTHONPATH并没有指定一个Python的路径解释本身。有关 PYTHONPATH 的其他信息，请阅读PYTHONPATH 文档。

下一步#

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