Python 设置参考

Visual Studio Code 的 Python 扩展非常灵活可配置。本页描述了您可以使用的 key 设置。

有关在 VS Code 中使用设置的常规信息，请参阅用户和工作区设置，以及变量参考，了解预定义变量支持的信息。

常规 Python 设置

设置 (python.)	默认	描述
conda路径	`"conda"`	通往`康达`可执行文件。
默认解释器路径	`"python"`	路径到Python扩展首次加载工作区时要使用的默认Python解释器，或包含Python解释器的文件夹的路径。可以使用变量如`${工作区文件夹}`和`${工作区文件夹}/.venv`使用路径到文件夹允许任何与项目合作的人都可以在该文件夹中创建环境`.venv`文件夹根据其操作系统，而不是必须指定具体的平台依赖路径。`settings.json` 文件随后可以包含在源代码存储库中。注意：在为工作区选择解释器之后对这个设置所做的更改将不会被应用或被Python扩展考虑。Python扩展不会自动添加或更改这个设置。
环境文件	`"${workspaceFolder}/.env"`	包含环境变量定义的文件的绝对路径。请参阅.env文件支持。
实验启用	`真`	启用Python扩展中的A/B实验。如果启用，您可能会收到建议的改进和/或功能。
全局模块安装	`假`	指定是否仅使用当前用户安装软件包`--用户`命令行参数（默认值），或在全局环境中为所有用户安装（当设置为`真`). 在使用虚拟环境时会被忽略。有关更多信息请参见`--用户` 论证，见 pip - 用户安装。
解释器信息可见性	`"onPythonRelated"`	控制何时在状态栏上显示所选的解释器信息。默认情况下，只有在编辑器中打开与Python相关的文件时才会显示。您可以将其设置为`"总是"`如果你希望它总是显示在状态栏上，或`“从不”`完全隐藏它。
pipenv路径	`"pipenv"`	用于激活的pipenv可执行文件的路径。
诗歌之路	`“诗歌”`	指定诗歌依赖管理器可执行文件的位置，如果已安装。默认值 `“诗歌”`假定可执行文件在当前路径中。Python 扩展使用此设置在 Poetry 可用时安装软件包，并且有`poetry.lock`工作区文件夹中的文件。
REPL启用REPL智能发送	`真`	指定是否`输入：Shift+Enter`利用 Smart Send。Smart Send 会查看光标所在的位置，将最小的可运行代码块发送到 Python REPL，然后将光标移动到下一行代码。
终端在当前终端激活环境	`假`	指定在激活Python扩展时是否使用所选的虚拟环境激活当前打开的终端。
终端.激活环境	`真`	指示是否在创建新终端时自动激活您选择的环境，使用Python: 选择解释器命令。例如，当此设置为`真` 并且您选择一个虚拟环境时，该扩展会在创建新终端时自动运行环境的激活命令 (`源 env/bin/activate`在 macOS/Linux；`env\scripts\激活` 在Windows上）。注意：此设置已被 `python-envs.terminal.autoActivationType`当该设置配置时。
终端在文件目录中执行	`假`	指示是否在文件所在目录而不是当前文件夹中运行文件。
终端.启动后聚焦	`假`	是否在启动Python终端时将光标焦点切换到终端。
终端.启动参数	`[]`	当您使用命令Python: 在终端中运行Python文件运行文件时传递给Python解释器的启动参数。在`启动参数`列表，每个项目是一个顶级命令行元素，由空格分隔（包含空格的引值是一个顶级元素，因此在列表中是一个项目）。例如，对于参数`--a --b --c {"value1": 1, "value2": 2}`，列表项应该是`["--a", "--b", "--c", "{\"value1\" : 1, \"value2\" : 2}"]`注意，VS Code 在调试时会忽略此设置，因为它会使用你在选择的调试配置中的参数。`launch.json`输入：.
终端使用环境文件	`假`	控制是否将 env 文件和 python.envFile 设置中的环境变量注入到终端中。
venv文件夹	`[]`	虚拟环境创建的文件夹路径。根据使用的虚拟化工具，可能是项目本身：`${工作区文件夹}`, 或者将所有虚拟环境放在并排的单独文件夹中：`.环境`，`~/.virtualenvs`，等等。注意：此设置会自动合并到`python-envs.全局搜索路径`考虑迁移到新环境以获得额外功能。

Python 环境扩展设置

Python Environments 扩展在 VS Code 用户界面中提供环境和包管理。这些设置控制环境的发现、创建和终端激活。

有关环境管理的更多信息，请参见Python 环境.

环境管理设置

设置 (python 环境)	默认	描述
默认环境管理器	`"ms-python.python:venv"`	默认的环境管理器用于创建和管理环境。
默认包管理器	`"ms-python.python:pip"`	在环境中安装软件包的默认包管理器。
python项目	`[]`	Python 项目列表。每个项目都是具有以下属性的对象：`路径`(字符串),`环境管理器`(字符串),`包管理器`(string)。在多根工作区中使用此功能来配置每个文件夹的环境。
工作区搜索路径	`["./**/.venv"]`	在该工作区中搜索环境的全局模式。默认情况下，搜索任何名为的文件夹`.venv` 在你的工作区的任何地方。注意：此设置必须在工作区或文件夹级别进行配置，而不是用户级别。
全局搜索路径	`[]`	绝对路径以在所有工作区中搜索Python环境。用于共享环境文件夹，例如`~/envs`. 注意：旧版设置 `python.venvPath`和`python.venvFolders`自动与此设置合并。
始终使用UV	`真`	当设置为`真`, uv 将被用来管理所有可用的虚拟环境。当设置为 `假`uv 只能管理由 uv 显式创建的虚拟环境。

终端设置

设置 (python-envs.终端.)	默认	描述
自动激活类型	`"命令"`	指定扩展如何在终端中激活环境。可用值：`命令`（在终端中执行命令激活）`启动外壳`（通过 shell 集成激活或通过修改终端 shell 启动脚本激活，支持 zsh、fish、pwsh、bash、cmd）`关` (无自动激活) 注意：此设置优先于`python.terminal.activateEnvironment`输入：.
显示激活按钮	`假`	（实验性）是否在终端菜单中显示“激活”按钮。

遗留设置迁移

如果您正在从较旧的 Python 扩展设置迁移，以下表格显示了到新设置的映射：

遗产设定	新设置	笔记
`python.venvPath`	`python-envs.全局搜索路径`或`python-envs.workspaceSearchPaths`	遗留设置仍然有效并会自动合并。考虑迁移到使用 glob 模式。
`python.venvFolders`	`python-envs.全局搜索路径`或`python-envs.workspaceSearchPaths`	遗留设置仍然有效并会自动合并。
`python.terminal.activateEnvironment`	`python-envs.terminal.autoActivationType`	设置为`"关"`禁用自动激活。新设置在配置时优先使用。

调试器设置

一般调试

设置 (python.debugpy.)	默认	描述	另见
调试仅我的代码	`真`	指定调试器是否仅应逐步执行用户编写的代码。禁用后，您可以逐步执行库代码。	调试

测试设置

一般测试

设置 (python.testing.)	默认	描述	另见
自动测试发现启用时保存	`真`	指定在保存测试文件时是否启用或禁用自动运行测试发现。	测试
当前工作目录	无	为测试指定一个可选的工作目录。	测试
调试端口	`3000`	用于unittest测试调试的端口号。	测试
提示配置	`真`	指定 VS Code 在发现潜在测试时是否提示配置测试框架。	测试

单元测试框架

设置 (python.testing.)	默认	描述	另见
单元测试参数	`["-v", "-s", ".", "-p", "test.py"]`	传递给unittest的参数，每个用空格分隔的顶级元素都是列表中的一个单独项。	测试
单元测试启用	`假`	指定是否启用unittest进行测试。	测试

pytest 框架

设置 (python.testing.)	默认	描述	另见
pytest参数	`[]`	传递给pytest的参数，每个顶级元素由空格分隔，分别成为列表中的一个项目。在安装pytest-cov的情况下调试测试时，包括`--不覆盖`在这些论点中。	测试
pytest已启用	`假`	指定是否启用pytest进行测试。	测试
pytest路径	`"pytest"`	路径到pytest。如果pytest位于当前环境之外，请使用完整路径。	测试

代码分析设置

IntelliSense 引擎设置

注意： 如果你从未更改过语言服务器设置，你的语言服务器将通过“默认”设置值设置为 Pylance。

设置 (python.)	默认	描述
语言服务器	默认	定义语言服务器的类型（默认，Pylance，Jedi，和 None）。

Python 语言服务器设置

Pylance 语言服务器

语言服务器设置在以下情况下适用python.语言服务器是Pylance或默认如果你在语言服务器上遇到语言问题，请参阅语言服务器中的故障排除部分。

设置 (python.analysis.)	默认	描述
人工智能代码操作	真	是否启用特定的AI辅助代码操作。需要启用GitHub Copilot Chat扩展。接受的值是一个对象，以代码操作为键，以布尔值为值。可用的代码操作：`实现抽象类`（使用 GitHub Copilot 的 AI 建议来实现从抽象类继承的类的方法，从而实现代码操作）。用法示例：`{"implementAbstractClasses": true}`
自动格式化字符串	假	在字符串中输入"{"时，是否自动以"f"开头。
自动导入完成	假	控制在完成中提供自动导入。可用值为`真`和`假`输入：.
自动缩进	真	是否在输入Python代码时根据语言语义自动调整缩进。接受的值为`真`或`假`输入：.
自动搜索路径	真	指示是否根据一些预定义名称自动添加搜索路径（例如`源`)。可用的值是`真`和`假`输入：.
完成函数括号	假	为函数补全添加括号。接受的值是`真`和`假`输入：.
诊断模式	只打开文件	指定语言服务器分析哪些代码文件以查找问题。可用值为`工作区`和`只打开文件`输入：.
诊断严重性覆盖	输入：{}	允许用户覆盖单个诊断的严重程度级别。对于每一条规则，可用的严重程度级别是`错误`(红色波浪线)`警告`(黄色波浪线)`信息`(蓝色波浪线) 和`无`（规则已禁用）。有关用于诊断严重性规则的密钥的信息，请参见诊断严重性规则部分。
启用可编辑安装	`假`	通过解决在可编辑模式下安装的包的导入路径，提高了IntelliSense支持（`pip install -e .`) 如 PEP 660中所定义。
排除	[]	不希望包含在分析中的目录或文件的路径。这些会覆盖在下面列出的目录`python分析包含`设置，允许特定子目录被排除。请注意，此列表中的文件`排除`设置如果被未在排除列表中的源文件引用/导入，仍然可能包含在分析中。路径可能包含通配符，例如`*`(a 目录或多个目录级别)`输入：`(a sequence of zero or more characters), or`？`（单个字符）。如果未指定排除路径，Pylance 会自动排除以下内容：`/node_modules`，`/__pycache__`，`.git`和任何虚拟环境目录。
额外路径	[]	指定额外的搜索路径用于导入解析。接受以字符串形式指定的路径，如果有多条路径，则用逗号分隔。例如：`["路径 1","路径 2"]`输入：.
导入格式	绝对的	定义自动导入模块时的默认格式。接受的值是`绝对的`或`相对的`输入：.
包括	[]	目录或文件的路径，应该包含在分析中。如果未指定路径，Pylance 将默认为包含工作区根目录的目录。路径可以包含通配符字符，例如 ``(a 目录或多个目录级别)`输入：`(a sequence of zero or more characters), or`？`（一个字符）。
修复所有	`[]`	在运行 Fix All 命令时要运行的代码操作列表`源.修复全部`代码操作。接受的值：`源.未使用导入`(移除当前打开文件中所有未使用的导入)`源.转换导入格式`（根据转换进口）`python分析导入格式`设置)。
包含用户文件中的别名	假	是否包括用户文件中的别名符号在自动导入建议和添加导入快速修复中。禁用时，Pylance 将从符号定义的位置提供导入建议。启用时，它还会从导入符号的文件（即别名）中提供导入建议。可用值为`真`和`假`输入：.
忽略	[]	路径的目录或文件，其诊断输出（错误和警告）应被抑制，即使它们是包含文件或在包含文件的传递闭包内。路径可能包含通配符字符，例如 ``(a 目录或多个目录级别)`输入：`(a sequence of zero or more characters), or`？`(单个字符)。如果未提供值，则为`python.检查忽略模式`（如果设置）将被使用。
索引	真	用于指定Pylance在启动时是否应该索引用户文件以及已安装的第三方库，以在自动导入、快速修复、自动完成等功能中提供更完整的符号集。接受的值是`真`或`假`当设置为`真`默认情况下，Pylance 会索引已安装包的顶级符号（即，符号在`__all__`在`包/__init__.py`)，以及来自多达2000个用户文件的所有符号。当设置为`假`Pylance将仅显示在之前由编辑器打开或加载的文件中已引用或使用的符号。
inlayHints.callArgumentNames	关	控制显示嵌入式提示以显示调用参数名称。可用值为`关`，`部分`，和`全部`当设置为`关`不显示镶嵌提示。当设置为`部分`, 提示已禁用位置仅参数和关键字仅参数。当设置为`全部`所有参数的提示都显示出来。
inlayHints.functionReturnTypes	假	是否显示函数返回类型的嵌入式提示。接受的值是`真`或`假`输入：.
inlayHints.pytestParameters	假	是否显示 pytest fixture 参数类型嵌入式提示。接受的值是`真`或`假`输入：.
inlayHints.变量类型	假	是否显示变量类型的嵌入式提示。接受的值为`真`或`假`输入：.
语言服务器模式	默认	提供预定义配置，以根据开发需求优化 Pylance 的性能。可用值为`默认`和`光`当设置为`默认`语言服务器为大多数机器提供了足够的功能，而不会使系统过载。当设置为`光`这使得设置更加轻量且内存高效。此模式禁用各种功能，使 Pylance 的功能更像一个精简的文本编辑器，对于不需要完整的 IntelliSense 功能并希望 Pylance 尽可能节省资源的人来说，这是一个理想的选择。`光`模式下，以下设置将被覆盖：`python分析排除`设置为`['**']`，`python分析.使用库代码进行类型定义`设置为`假`，`python分析启用pytest支持`设置为`假`，和`python分析索引`设置为`假`输入：.
日志级别	`错误`	指定语言服务器的日志记录级别。可能的日志记录级别按提供的信息量从低到高排列如下：`错误`，`警告`，`信息`，和`追踪`输入：.
节点参数	`" --max-old-space-size=8192 "`	指定直接传递给由定义的自定义Node.js可执行文件的自定义参数`python分析节点可执行文件`这可以用来分配更多内存或配置Node.js行为。接受Node.js支持的参数列表。每个`"参数=值"`在列表中用逗号分隔。用法示例：`"python.analysis.nodeArguments": ["--max-old-space-size=8192"]`
节点可执行文件	`"`	指定要使用的Node.js可执行文件，这使Pylance能够分配更多的内存。接受的值是带有可执行文件路径的字符串、空字符串或`"自动"`当设置为空字符串时，Pylance 将使用 VS Code 的 node 可执行文件。当设置为`"自动"`，它将自动下载Node.js。
包索引深度	[]	用于覆盖每个已安装包下索引的级别。默认情况下，仅索引顶级模块（深度 = 1）。要索引子模块，请为每个需要索引的子模块级别增加1。接受的值是像这样的对象元组`{"name": "包名称 (str)", "depth": "扫描深度 (int)", "includeAllSymbols": "是否包括所有符号 (bool)"}`如果`包含所有符号`设置为`假`，每个包中的仅符号`__all__`包括。当它设置为`真`Pylance 将会索引文件中的每个模块/顶级符号声明。用法示例：`[{"名称": "sklearn", "深度": 2, "包含所有符号": true}, {"名称": "matplotlib", "深度": 3, "包含所有符号": false}]`
stub路径	./typings	指定一个包含自定义类型stub的目录路径。每个包的类型stub文件应放在其自己的子目录中。
类型检查模式	关	指定要执行的类型检查分析级别。可用值为`关`，`基本`，和`严格`当设置为`关`不进行类型检查分析；生成未解析的导入/变量诊断。当设置为`基本`非类型检查相关的规则（所有规则在`关`)，同时使用基本类型检查规则。当设置为`严格`所有类型检查规则在最高的错误严重性（包括所有规则在内）`关`和`基本`类别) 被使用。
使用库代码进行类型	真	解析包的源代码，当找不到类型提示时。可用的值是`真`和`假`输入：.
用户文件索引限制	2000	设置Pylance在工作区中索引的用户文件的最大数量。当设置为-1时，Pylance将索引所有文件。请注意，索引文件是一个性能密集型任务。

诊断严重性规则

本节详细介绍了所有可用的规则，这些规则可以使用python分析诊断严重程度覆盖设置如以下示例所示。

{
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnboundVariable": "信息",
    "reportImplicitStringConcatenation": "警告"
  }
}

价值	描述
报告断言始终为真	用于“assert”语句的诊断，该语句可能永远成立。这可能表明存在编程错误。
报告呼叫默认初始化器	在默认值初始化表达式中对函数调用的诊断。此类调用可能会隐藏在模块初始化时执行的昂贵操作。
报告常量重新定义	用于检测尝试重新定义变量的诊断，这些变量的名称全部使用大写字母和下划线及数字。
报告重复导入	诊断导入的符号或模块被导入多次。
报告函数成员访问	对函数成员访问的诊断。
报告一般类型问题	用于检测一般类型不一致、不支持的操作、参数/参数不匹配等问题的诊断。这涵盖了所有基本的类型检查规则，不包括其他规则涵盖的类型。它不包括语法错误。
报告导入循环	循环导入链的诊断信息。这些不是Python的错误，但它们确实会减慢类型分析速度，并且通常表明存在架构层叠问题。通常应避免这些问题。
报告隐式字符串连接	对两个或多个连续的字符串字面值进行诊断，表明发生了隐式连接。这被认为是一种不良实践，并且经常隐藏诸如缺少逗号之类的错误。
报告不兼容的方法覆盖	诊断以检测以不兼容的方式（参数数量错误、参数类型不兼容或返回类型不兼容）覆盖基类中同名方法的方法。
报告不兼容的变量覆盖	诊断用于类变量声明覆盖基类中同名符号但类型与基类符号类型不兼容的情况。
报告无效的字符串转义序列	诊断在字符串字面量中使用的无效转义序列。Python 规范指出，这些序列将在未来的版本中产生语法错误。
报告无效的代理语句	诊断应在stub文件中出现的语句。
报告无效类型变量使用	函数签名中类型变量使用不当的诊断。
报告缺少的导入	对于没有对应导入的Python文件或类型提示文件的导入的诊断。
报告缺少模块源	对于没有对应源文件的导入进行诊断。当找到类型stub但未找到模块源文件时，会发生这种情况，表明在使用此执行环境时代码可能在运行时失败。类型检查将使用类型stub进行。
报告缺少类型参数	当使用泛型类时没有提供显式或隐式类型参数时的诊断。
报告缺少类型模拟	对于没有对应类型stub文件（无论是typeshed文件还是自定义类型stub）的导入进行诊断。类型检查器需要类型stub来尽最大努力进行分析。
报告可选调用	诊断尝试调用具有Optional类型的变量。
报告可选上下文管理器	诊断尝试将可选类型用作上下文管理器（作为 with 语句的参数）。
报告可选可迭代对象	诊断尝试将可空类型（Optional type）用作可迭代值（例如在 for 语句中）。
报告可选成员访问	诊断尝试访问具有Optional类型的变量的成员。
报告可选操作数	诊断尝试将可选类型用作二元或一元运算符（如‘+’，‘==’，‘or’，‘not’）的运算数。
报告可选下标	对尝试使用Optional类型对变量进行下标（索引）操作的诊断。
报告私人使用	用于检测私有或受保护变量或函数的错误使用情况。受保护的类成员以单下划线开头。`输入：_`只能被子类访问。私有类成员以双下划线开头，但不以双下划线结尾，只能在声明类内部访问。类外部声明的变量和函数，如果它们的名字以单下划线或双下划线开头，则被认为是私有的，不能在声明模块外部访问。
报告属性类型不匹配	诊断那些setter所传递的值的类型无法赋值给getter返回的值的属性。这种不匹配违反了属性的预期用途，属性应该像变量一样工作。
报告自我类参数名称	诊断实例方法中缺少或名称错误的“self”参数，以及类方法中缺少或名称错误的“cls”参数。元类（继承自“type”的类）中的实例方法允许使用“cls”。
报告未定义变量	未定义变量的诊断。
报告未绑定变量	对未绑定和可能未绑定变量的诊断。
报告未知参数类型	用于函数或方法的调用参数的诊断，这些函数或方法具有未知类型。
报告未知的 Lambda 类型	对具有未知类型的lambda的输入或返回参数的诊断。
报告未知成员类型	用于类或实例变量的诊断，这些变量的类型未知。
报告未知参数类型	用于具有未知类型的功能或方法的输入或返回参数的诊断信息。
报告未知变量类型	对具有未知类型的变量进行诊断。
报告不必要的转换	对那些静态确定为不必要的'cast'调用的诊断。这样的调用有时表明存在编程错误。
报告不必要的 isinstance	用于“isinstance”或“issubclass”调用的诊断，其结果在静态分析时确定为始终为真或始终为假。此类调用通常指示编程错误。
报告未使用的调用结果	对那些结果不被消费且不是None的调用表达式的诊断。
报告未使用类	对一个具有私有名称（以下划线开头）且未被访问的类进行诊断。
报告未使用的协程	用于返回Coroutine且其结果未被消费的调用表达式的诊断。
报告未使用函数	对一个具有私有名称（以下划线开头）且未被访问的函数或方法的诊断。
报告未使用导入	诊断导入的符号在该文件中未被引用。
报告未使用变量	对未访问变量的诊断。
报告不支持的双下划线所有	对不支持的操作的诊断`__all__`输入：.
报告通配符导入库	用于从外部库进行通配符导入的诊断。

自动完成设置

设置 (python自动完成.)	默认	描述	另见
额外路径	`[]`	指定要加载自动完成数据的附加包的位置。	编辑

预定义变量

Python 扩展设置支持预定义变量。类似于 VS Code 的一般设置，变量使用 ${variableName} 语法。具体来说，扩展支持以下变量：

${cwd} - 启动时任务运行器的当前工作目录
${workspaceFolder} - 在 VS Code 中打开的文件夹路径
${workspaceRootFolderName} - 在 VS Code 中打开的文件夹名称，没有任何斜线 (/)
${workspaceFolderBasename} - 在 VS Code 中打开的文件夹名称，没有任何斜杠 (/)
${file} - 当前打开的文件
${relativeFile} - 相对于当前打开的文件 工作区文件夹
${relativeFileDirname} - 当前打开的文件相对于工作区文件夹
${fileBasename} - 当前打开文件的文件名
${fileBasenameNoExtension} - 当前打开的文件的不带扩展名的文件名
${fileDirname} - 当前打开文件的dirname
${fileExtname} - 当前打开文件的扩展名
${lineNumber} - 当前在活动文件中选择的行号
${selectedText} - 当前在活动文件中选择的文本
${execPath} - 运行中的 VS Code 可执行文件的路径

关于预定义变量的更多信息和示例用法，请参阅变量参考在VS Code文档中。

下一步

Python 环境 - 控制用于编辑和调试的 Python 解释器。
编辑代码 - 了解Python的自动完成、IntelliSense、格式化和重构。
代码检查 - 启用、配置和应用各种Python代码检查工具。
调试 - 学习如何在本地和远程调试Python。
测试 - 配置测试环境并发现、运行和调试测试。