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。
如果你使用 Venv 创建环境,该命令会显示可用作新虚拟环境基础的解释器列表。
如果你使用 Conda 创建环境,该命令会显示可用于项目的 Python 版本列表。
选择所需的解释器或 Python 版本后,将显示一个通知,显示环境创建的进度,并且环境文件夹将出现在你的工作区中。
注意:该命令还将安装项目文件夹中
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 环境。我们建议你将 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: 选择解释器窗口右上角的刷新图标;否则你可能无法在那里找到该环境。
-
要确保从 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 扩展部分中的python.condaPath
设置为适当的路径。
使用 Python 解释器
选择并激活环境
Python 扩展会尝试查找并选择它认为最适合工作区的环境。如果你希望选择特定的环境,请从命令面板(⇧⌘P (Windows、Linux Ctrl+Shift+P))中使用 Python: 选择解释器命令。
注意:如果 Python 扩展未找到解释器,它会发出警告。在 macOS 12.2 及更早版本上,如果你使用操作系统安装的 Python 解释器,扩展也会发出警告,因为它已知存在兼容性问题。在任何一种情况下,你都可以通过在用户设置中将
python.disableInstallationCheck
设置为true
来禁用这些警告。
Python: 选择解释器命令会显示可用全局环境、conda 环境和虚拟环境的列表。(有关详细信息,包括这些环境类型之间的区别,请参阅扩展查找环境的位置部分。)例如,下图显示了多个 Anaconda 和 CPython 安装以及一个 conda 环境和一个位于工作区文件夹中的虚拟环境(env
)
注意:在 Windows 上,VS Code 检测可用 conda 环境可能需要一些时间。在此过程中,你可能会在环境路径之前看到“(cached)”字样。该标签表示 VS Code 当前正在使用该环境的缓存信息。
如果你在 VS Code 中打开了一个文件夹或工作区,并且从列表中选择了一个解释器,Python 扩展将会在内部存储该信息。这确保了当你重新打开工作区时将使用相同的解释器。
选定的环境由 Python 扩展用于运行 Python 代码(使用 Python: 在终端中运行 Python 文件命令)、在你编辑器中打开 .py
文件时提供语言服务(自动补全、语法检查、代码检查、格式化等),以及使用 终端:创建新终端命令打开终端。在后一种情况下,VS Code 会自动激活选定的环境。
提示:要阻止自动激活选定环境,请将
"python.terminal.activateEnvironment": false
添加到你的settings.json
文件(它可以放置在任何位置,作为现有设置的同级)。
提示:如果 activate 命令生成消息“Activate.ps1 is not digitally signed. You cannot run this script on the current system.”(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 扩展会按以下优先级顺序自动选择版本最高的解释器
- 直接位于工作区文件夹下的虚拟环境。
- 与工作区相关但全局存储的虚拟环境。例如,位于工作区文件夹外部的 Pipenv 或 Poetry 环境。
- 全局安装的解释器。例如,在
/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
形式的键值对,其中 #
用于注释。不支持多行值,但允许引用先前定义的环境变量。环境变量定义文件可用于调试和工具执行(包括 linter、格式化程序、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 会影响用户在终端中运行的任何工具,以及扩展通过终端为用户执行的任何操作,例如调试。但是,在这种情况下,当扩展执行的操作不是通过终端路由的(例如使用 linter 或格式化程序)时,此设置将不会对模块查找产生影响。
后续步骤
- 编辑代码 - 了解 Python 的自动完成、IntelliSense、格式设置和重构。
- 调试 - 了解如何在本地和远程调试 Python。
- 测试 - 配置测试环境以及发现、运行和调试测试。
- 设置参考 - 探索 VS Code 中所有与 Python 相关的设置。
更多 Python 资源
- VS Code Python 入门 - 了解如何在 VS Code 中编辑、运行和调试代码。
- 虚拟环境和包 (Python.org) - 了解有关虚拟环境和包的更多信息。
- 安装 Python 模块 (Python.org) - 了解如何安装 Python 模块。
- Python 教程 (Python.org) - 了解有关 Python 语言的更多信息。