Python 设置参考

Visual Studio Code 的 Python 扩展高度可配置。本页介绍了您可以使用的关键设置。

有关在 VS Code 中作设置的一般信息，请参阅用户和工作空间设置，以及关于预定义变量支持的变量参考。

通用 Python 设置

设置（python.） 默认 描述
condaPath “康达” 通往康达可执行。
defaultInterpretationerPath “Python” 路径指向 Python 扩展首次加载工作区时使用的默认 Python 解释器路径，或包含该 Python 解释器的文件夹路径。可以使用以下变量${workspaceFolder}以及${workspaceFolder}/.venv.使用文件夹路径允许任何与项目合作的人创建环境.venv文件夹，根据他们的作系统设置，而无需指定具体的平台相关路径。该settings.json文件随后可以包含在源代码仓库中。注意：在为工作区选择解释器后对该设置进行的更改，Python 扩展不会应用或考虑。Python 扩展不会自动添加或更改这个设置。
envFile “${workspaceFolder}/.env” 包含环境变量定义的文件的绝对路径。请参见.env文件支持。
实验。启用 确实如此 在 Python 扩展中启用 A/B 实验。如果启用，可能会为您提供拟议的增强和/或功能。
globalModule安装 错误 指定是否仅使用以下设备为当前用户安装包--用户命令行参数（默认），或为全局环境中的所有用户安装（当设置为确实如此).使用虚拟环境时会被忽略。欲了解更多关于--用户参见 pip - 用户安装。
interpreter.info可视化 “onPythonRelated” 控制何时在状态栏显示所选解释器信息。默认情况下，只有当编辑器中打开了与 Python 相关的文件时才会显示。你可以设置为“永远”如果你想让它一直显示在状态栏上，或者“永远不会”完全隐藏它。
pipenvPath “Pipenv” 通往 pipenv 可执行文件的路径，用于激活。
诗歌路径 “诗歌” 指定 Poetry 依赖管理器可执行文件（如安装）的位置。默认值“诗歌”假设可执行文件位于当前路径中。Python 扩展会用这个设置来安装 Poetry 的包，并且有诗歌.lock文件在工作区文件夹中。
REPL.enableREPLSmartSend 确实如此 指定Shift+Enter善用智能发送。Smart Send会查看光标所在的代码，将最小的可运行代码块发送到Python REPL，然后将光标放在下一行代码上。
terminal.activateEnvInCurrentTerminal 错误 指定在激活 Python 扩展时，是否激活当前打开的终端，使用所选虚拟环境。
终端。激活环境 确实如此 表示当新终端创建时，是否通过 Python 命令“选择解释器”自动激活所选环境。例如，当该设置为确实如此当你选择虚拟环境时，扩展会自动执行该环境的激活命令，当你创建新终端时（源环境/bin/activatemacOS/Linux;env\scripts\activate在Windows上）。注意：此设置被 取代python-envs.terminal.autoActivationType当该设置被配置好时。
terminal.executeInFileDir 错误 表示是否在文件目录中运行文件，而不是当前文件夹。
terminal.focus发射后 错误 启动Python终端时是否应该将光标焦点切换到终端。
terminal.launchArgs [] 启动参数，当你用诸如 Python： Run Python File in Terminal 等命令运行文件时，给 Python 解释器。在launchArgs列表中，每个项都是顶层命令行元素，中间用空格分隔（引号值包含空格的值是单个顶层元素，因此是列表中的一个项）。例如，对于--a --b --c {“value1” ： 1， “value2” ： 2}，列表项目应为[“--a”， “--b”、“--c”、“{\”value1\“ ： 1， \”value2\“ ： 2}\”“].注意，VS Code 在调试时忽略了这个设置，因为它会使用你在launch.json.
terminal.useEnvFile 错误 控制环境变量是否注入 env 文件和 python.envFile 设置中的变量到终端。
venvFolders [] 指向创建虚拟环境的文件夹路径。根据所用虚拟化工具的不同，它也可以是项目本身：${workspaceFolder}，或为所有虚拟环境并排的独立文件夹：.\envs,~/.virtualenvs，依此类推。注意：该设置会自动与python-envs.globalSearchPaths.考虑迁移到新环境以获得更多功能。

Python 环境扩展设置

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

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

环境管理设置

Setting （python-envs.） 默认 描述
defaultEnvManager “ms-python.python：venv” 用于创建和管理环境的默认环境管理器。
defaultPackageManager “ms-python.python：pip” 用于在环境中安装包的默认包管理器。
python项目 [] Python 项目列表。每个项目是一个具有以下属性的对象：路径（弦），envManager（弦），packageManager（字符串）。利用它在多根工作区中配置每个文件夹的环境。
workspaceSearchPaths [“./**/.venv”] 用球状模式搜索该工作区中的环境。默认情况下，搜索任何名为.venv在你工作空间的任何地方。注意：此设置必须在工作区或文件夹层面配置，而非用户层面。
全球搜索路径 [] 在所有工作空间中搜索Python环境的绝对路径。用于共享环境文件夹，如~/envs.注意：遗留设置python.venvPath以及python.venvFolders会自动与该设置合并。
alwaysUseUv 确实如此 当设置为确实如此如果有，UV将用于管理所有虚拟环境。当设置为错误， UV 只会管理由 UV 明确创建的虚拟环境。

终端设置

Setting （python-envs.terminal.） 默认 描述
autoActivationType “指挥” 指定扩展如何激活终端中的环境。可用数值：指挥（通过在终端执行命令激活），壳启动（通过 shell 集成或修改终端 shell 启动脚本激活，支持 zsh、fish、pwsh、bash、cmd），不对劲（无自动激活）。注意：此设定优先于此python.terminal.activateEnvironment.
showActivateButton 错误 （实验性）是否要在终端菜单中显示“激活”按钮。

遗留设置迁移

如果你是从旧的 Python 扩展设置迁移过来的，下表显示了映射到新设置的过程：

传承背景 新设定 注释
python.venvPath python-envs.globalSearchPaths或python-envs.workspaceSearchPaths 遗留设置依然有效，并且会自动合并。考虑迁移到使用球状模式。
python.venvFolders python-envs.globalSearchPaths或python-envs.workspaceSearchPaths 遗留设置依然有效，并且会自动合并。
python.terminal.activateEnvironment python-envs.terminal.autoActivationType 设置为“关掉”关闭自动激活。配置后，新设置优先。

调试器设置

通用调试

设置（python.debugpy.） 默认 描述 参见
debugJustMyCode 确实如此 规定调试器是否只步进用户编写的代码。禁用也可以逐步作库代码。 调试

测试设置

一般测试

设置 （python.testing.） 默认 描述 参见
autoTestDiscoverOnSaveEnabled 确实如此 规定保存测试文件时是否启用或禁用自动运行测试发现。 测试
慢性消耗病 无效 指定一个可选的工作目录用于测试。 测试
debugPort 3000 用于调试单元测试的端口号。 测试
promptToconfigure 确实如此 规定如果发现潜在测试，VS Code 是否会提示配置测试框架。 测试

UNITEST框架

设置 （python.testing.） 默认 描述 参见
unittestArgs [“-v”， “-s”、“.”、“-p”、“*test*.py”] 参数传递到 unittest，其中每个顶层元素中间有一个空格，都是列表中独立的一项。 测试
unittestEnabled 错误 规定是否启用了unittest用于测试。 测试

pytest 框架

设置 （python.testing.） 默认 描述 参见
pytestArgs [] 将参数传递给 pytest，其中每个顶层元素中间有一个空格，都是列表中的独立项。在调试安装了pytest-cov的测试时，包括——无冠在这些争论中。 测试
pytestEnabled 错误 指定是否启用pytest进行测试。 测试
pytest路径 “最爱” 通往pytest的路径。如果pytest位于当前环境之外，则使用完整路径。 测试

代码分析设置

IntelliSense 引擎设置

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

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

Python 语言服务器设置

Pylance 语言服务器

语言服务器设置适用于python.languageServer是派伦斯或默认.如果你在语言服务器上遇到困难，请参见语言服务器仓库中的故障排除。

设置（python.analysis.） 默认 描述
aiCodeActions 确实如此 是否启用特定的AI辅助代码动作。需要启用GitHub Copilot聊天扩展。Accepted value 是一个对象，键为代码动作，值为布尔值。可用的代码作：implementAbstractClasses（使代码动作能够实现从抽象类继承的类的方法，利用 GitHub Copilot 的 AI 建议填充方法体。）使用示例：{“implementAbstractClasses”： true}
autoFormatStrings 错误 在字符串中输入“{”时，是否自动加“f”作为前缀。
自动导入补全 错误 控制完工中自动导入的服务。可用值为确实如此以及错误.
autoIndent 确实如此 在输入Python代码时，是否根据语言语义自动调整缩进。公认值为确实如此或错误.
自动搜索路径 确实如此 指示是否根据某些预定义名称自动添加搜索路径（例如SRC).可用值为确实如此以及错误.
completeFunctionParens 错误 在函数补全化中添加括号。公认值为确实如此以及错误.
诊断模式 仅开放文件 指定语言服务器分析哪些代码文件以寻找问题。可用值为工作空间以及仅开放文件.
诊断严重度覆盖 {} 允许用户覆盖单个诊断的严重程度等级。对于每条规则，可用的严重程度等级为错误（红色曲线），警告（黄色曲线），信息（蓝色曲线），以及没有（规则禁用）。有关诊断严重度规则中使用的密钥，请参见下方的诊断严重度规则部分。
enableEditableInstalls 错误 通过解析安装在可编辑模式中的包的导入路径，实现了更好的 IntelliSense 支持（PIP 安装 -e 。）根据PEP 660的定义。
排除 [] 不应包含在分析中的目录或文件路径。这些目录覆盖在python.analysis.include设置，允许排除特定子目录。请注意，这里列出的文件排除如果设置被不在排除列表中的源文件引用或导入，仍可能包含在分析中。路径可能包含通配字符，如（目录或多层目录）、（零个或多个字符的序列），或者***?（单个角色）。如果没有指定排除路径，Pylance 会自动排除以下路径：**/node_modules,**/__pycache__,.git以及任何虚拟环境目录。
额外路径 [] 指定了导入解析的额外搜索路径。接受以字符串形式指定的路径，若有多条路径则用逗号分隔。例如：[“路径1”，“路径2”].
importFormat 绝对的 定义了自动导入模块时的默认格式。公认值为绝对的或相关关系.
包括 [] 分析中应包含的目录或文件路径。如果没有指定路径，Pylance 默认使用包含工作区根节点的目录。路径可能包含通配字符，如（目录或多层目录）、（零个或多个字符的序列），或者***?（单个角色）。
fixAll（修复所有） [] 运行“全部修正”命令或source.fixAll。代码行动。公认价值观：source.unusedImports（移除打开文件中未使用的导入），source.convertImportFormat（根据python.analysis.importFormat环境）。
includeAliasesFromUserFiles 错误 是否在自动导入建议和添加导入快速修复中包含用户文件的别名符号。禁用后，Pylance会从符号定义处提供导入建议。启用后，它还会从导入符号（即锯齿）的文件中提供导入建议。可用值为确实如此以及错误.
忽略 [] 目录或文件的路径，其诊断输出（错误和警告）应被抑制，即使它们是包含文件或包含文件的传递闭包内。路径可能包含通配字符，如（目录或多层目录）、（零个或多个字符的序列），或者***?（单个角色）。如果没有提供值，则python.linting.ignorePatterns（如果设置了），将被使用。
索引 确实如此 用于指定 Pylance 是否应索引用户文件，以及启动时安装的第三方库，以便在自动导入、快速修复、自动补全等功能中提供更完整的符号集。公认值为确实如此或错误.当设置为确实如此，Pylance 默认索引已安装包的顶层符号（即__all__在下面包装/装__init__.py），以及最多2000个用户文件中的所有符号。当设置为错误Pylance 只会显示已经被引用或用于编辑器之前打开或加载的文件中的符号。
inlayHints.callArgumentNames 不对劲 控制调用参数名称的内嵌提示显示。可用值为不对劲,部分， 和全部.当设置为不对劲，没有任何镶嵌提示。当设置为部分，仅位置和关键词参数的提示被禁用。当设置为全部，所有参数都显示了提示。
inlayHints.functionReturnTypes 错误 是否显示函数返回类型的内嵌提示。公认值为确实如此或错误.
inlayHints.pytestParameters（inlayHints.pytestParameters） 错误 是否要为pytest的固定具参数类型显示内嵌提示。公认值为确实如此或错误.
inlayHints.variableTypes 错误 是否要为变量类型显示镶嵌提示。公认值为确实如此或错误.
languageServerMode 默认 提供预定义配置，以根据开发需求优化 Pylance 的性能。可用值为默认以及光.当设置为默认语言服务器为大多数机器提供足够的功能，同时不会让系统过载。当设置为光它实现了轻量级、内存高效的设置。该模式关闭了多种功能，使 Pylance 更像一个简化的文本编辑器，非常适合不需要全部 IntelliSense 功能且希望 Pylance 尽可能节省资源的用户。在光模式中，以下设置被覆盖：python.analysis.exclude设为 ，["**"]python.analysis.useLibraryCodeForTypes设置为错误,python.analysis.enablePytestSupport设置为错误， 和python.analysis.indexing设置为错误.
logLevel 错误 指定语言服务器应执行的日志层级。随着信息量递增，可能的伐木层级为错误,警告,信息， 和追踪.
nodeArguments “--最大旧空间大小=8192” 直接指定自定义参数，Node.js可执行文件由python.analysis.nodeExecutable.这可以用来分配更多内存或配置Node.js行为。接受一份由Node.js支持的论点列表。每人“arg=值”列表中应用逗号分隔。使用示例：“python.analysis.nodeArguments”： [“--max-old-space-size=8192”]
nodeExecutable（节点可执行文件） "" 指定Node.js可执行文件，使 Pylance 能够分配更多内存。接受值是具有可执行路径的字符串、空字符串或“自动”.当设置为空字符串时，Pylance 将使用 VS Code 的节点可执行文件。当设置为“自动”它会自动下载Node.js。
packageIndexDepths [] 用来覆盖安装包下多少层，按每个包进行索引。默认情况下，只有顶层模块被索引（深度=1）。要索引子模块，每个子模块层级的深度增加1。被接受的值是对象元组，如{“name”：“包名 （str）”， “depth”： “深度扫描（int）”， “includeAllSymbols”： “是否包含所有符号 （bool）”}.如果includeAllSymbols设置为错误，每个包中只有符号__all__包含在内。当它设置为确实如此Pylance 会索引文件中每个模块/顶层符号声明。使用示例：[{“name”： “sklearn”， “depth”： 2， “includeAllSymbols”： true}， {“name”： “matplotlib”， “depth”： 3， “includeAllSymbols”： false}]
stubPath ./打字 指定一个包含自定义类型存根的目录路径。每个包的类型存根文件应置于其独立子目录中。
类型检查模式 不对劲 指定要执行的类型检查分析层级。可用值为不对劲,基础， 和严格.当设置为不对劲不进行类型检查分析;未解决的导入/变量诊断会被生成。当设置为基础非类型检查相关规则（所有规则不对劲以及基本的类型检查规则。当设置为严格所有错误严重度最高的类型检查规则（包括所有不对劲以及基础类别）被使用。
useLibraryCodeForTypes 确实如此 当找不到类型存根时，解析包的源代码。可用值为确实如此以及错误.
用户文件索引限制 2000 设置 Pylance 在工作区中索引的最大用户文件数量。当设置为 -1 时，Pylance 会索引所有文件。请注意，索引文件是一项性能密集的任务。

诊断严重度规则

本节详细介绍了所有可用规则，这些规则可以通过以下方式进行定制。python.analysis.diagnosticSeverityOverrides如下示例所示的设置。

{
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnboundVariable": "information",
    "reportImplicitStringConcatenation": "warning"
  }
}
价值 描述
报告说永远正确 诊断“断言”命题，可能永远断言。这可能是编程错误的信号。
reportCallInDefaultInitializer 在默认值初始化表达式中进行函数调用的诊断。此类调用可以掩盖模块初始化时执行的高成本作。
报告恒定重新定义 用于尝试重新定义全大写、带有下划线和数字的变量的诊断。
reportDuplicateImport 针对导入多个符号或模块的诊断。
reportFunctionMemberAccess 成员访问功能的诊断。
报告一般类型问题 一般类型不一致、不支持作、参数/参数不匹配等的诊断。这涵盖了其他规则未涵盖的所有基本类型检查规则。不包括语法错误。
reportImportCycles 周期性导入链的诊断。这些不是Python中的错误，但确实会减慢类型分析，且常常暗示架构层叠问题。一般来说，应避免使用。
report隐含字符串连接 对两个或多个串字面值相连的诊断，表明隐含的串接。这被认为是不好的做法，常常掩盖了诸如漏失逗号等错误。
reportIncompatibleMethodOverride 针对在基类中以不兼容方式覆盖同名方法的方法（参数数量错误、参数类型不兼容或返回类型不兼容）的方法进行诊断。
reportIncompatibleVariableOverride 针对类变量声明的诊断，这些声明覆盖了基类中同名符号，而该类型与基类符号类型不兼容。
reportInvalidStringEscapeSequence 用于字符串文字中的无效转义序列的诊断。Python 规范指出，此类序列在未来版本中将产生语法错误。
reportInvalidStubStatement 用于诊断不应该出现在存根文件中的语句。
reportInvalidTypeVarUse 函数签名中类型变量不当使用的诊断。
报告缺失进口 用于导入中没有对应导入的 Python 文件或类型存根文件的诊断。
报告失踪模块来源 无对应源文件的导入诊断。当找到类型存根但未找到模块源文件时，表示使用该执行环境时代码可能在运行时失败。类型检查将通过类型存根进行。
reportMissingTypeArgument 诊断用于使用泛类但未提供显式或隐式类型参数的情况。
reportMissingType小作品 对于没有对应类型存根文件（无论是类型文件还是自定义类型存根）的导入进行诊断。类型检查器需要类型存根才能在分析时发挥最佳作用。
reportOptionalCall 用于尝试调用带有可选类型的变量的诊断。
reportOptionalContextManager 用于尝试将可选类型作为上下文管理器（作为 with 语句的参数）进行诊断。
reportOptionalIterable 诊断：尝试将可选类型作为可循环值（例如在for语句中）。
reportOptionalMemberAccess 用于尝试访问带有可选类型的变量成员的诊断。
reportOptionalOperand 尝试将可选类型作为二进制或一元运算符的作数（如 '+'， '=='， 'or'， 'not'） 的诊断。
reportOptionalSubscript 用于尝试下标（索引）带有可选类型变量的诊断。
reportPrivateUsage 对私有或受保护变量或函数错误使用的诊断。受保护类成员以单一下划线开头，且仅可通过子类访问。私有类成员以双重下划线开头，但不以双重下划线结尾，且只能在声明类内访问。在类外声明的变量和函数，如果其名称以单重或双下划线开头，且不能在声明模块外访问，则被视为私有的。_
reportPropertyTypeMismatch（报告属性类型不匹配） 诊断那些传递给设置者的值类型无法映射到获取者返回的值的属性。这种不匹配违反了属性的预期用途，属性本应像变量一样工作。
reportSelfClsParameterName 实例方法中缺失或错误命名的“self”参数和类方法中“cls”参数的诊断。元类中的实例方法（源自“类型”的类）允许使用“cls”作为实例方法。
reportUndefinedVariable 未定义变量的诊断。
reportUnboundVariable 对未绑定和可能无绑定变量的诊断。
reportUnknownArgumentType（报告：不知名论点类型） 用于对未知类型函数或方法调用参数的诊断。
reportUnknownLambdaType 对于未知类型的lambda进行输入或返回参数的诊断。
报告未知成员类型 对类型未知的类或实例变量进行诊断。
reportUnknownParameterType 对于类型未知的函数或方法的输入或返回参数进行诊断。
reportUnknownVariableType 对未知类型的变量进行诊断。
报道 无需演员 对静态判定为不必要的“cast”呼叫进行诊断。此类调用有时表明存在编程错误。
reportUnnecessaryIsInstance “isinstance”或“issubclass”的诊断调用，其中结果静态确定为始终为真或总是假。此类调用通常表明存在编程错误。
reportUnusedCallResult（报告未使用呼叫结果） 对结果未被消耗且非 None 的调用表达式进行诊断。
reportUnusedClass 对一个私有名称（以下划线开头）且未被访问的类进行诊断。
报告未使用协程 用于返回协程且结果未被消耗的调用表达式的诊断。
reportUnusedFunction 对一个私有名称（以下划线开头）但未被访问的函数或方法的诊断。
reportUnusedImport 对导入的符号进行诊断，但该符号在该文件中未被引用。
reportUnusedVariable 未被访问的变量进行诊断。
reportUnsupportedDunderAll 对未支持作的诊断__all__.
报告万用卡导入自图书馆 从外部库导入通配符的诊断。

自动补全设置

设置 （python.autoComplete.） 默认 描述 参见
额外路径 [] 指定加载自动补全数据的额外包的位置。 剪辑

预定义变量

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

  • ${cwd} - 任务执行者启动时当前的工作目录

  • ${workspaceFolder} - VS Code 中打开的文件夹路径

  • ${workspaceRootFolderName} - 在 VS Code 中打开的文件夹名称，且无斜杠 （/）

  • ${workspaceFolderBasename} - 在 VS Code 中打开的文件夹名称，不带斜杠（/）

  • ${file} - 当前已打开的文件

  • ${relativeFile} - 当前已打开的文件相对于workspaceFolder

  • ${relativeFileDirname} - 当前打开文件相对于 的 dirnameworkspaceFolder

  • ${fileBasename} - 当前已打开文件的基址名

  • ${fileBasenameNoExtension} - 当前打开文件的无扩展名的基名

  • ${fileDirname} - 当前打开文件的 dirname

  • ${fileExtname} - 当前已打开文件的扩展名

  • ${lineNumber} - 当前活动文件中选中的行号

  • ${selectedText} - 当前当前正在活动文件中的文本

  • ${execPath} - 运行中的VS Code可执行文件的路径

有关预定义变量和示例使用的更多信息，请参见通用 VS Code 文档中的变量参考。

下一步

  • Python 环境——控制用于编辑和调试的 Python 解释器。
  • 代码编辑——学习自动补全、IntelliSense、格式化和Python重构。
  • 线条打印——启用、配置并应用各种 Python 模板。
  • 调试——学习本地和远程调试Python。
  • 测试——配置测试环境，并发现、运行和调试测试。