VSCode格式化Python代码？安装Black插件与设置【必看】-VSCode-PHP中文网

black 在 vscode 中不自动格式化 python 的根本原因是：python 解释器路径未指向安装 black 的环境、python.formatting.provider 未显式设为 "black"、项目根目录下缺少含 [tool.black] 的 pyproject.toml——三者必须同时满足且顺序正确。

vscode格式化python代码？安装black插件与设置【必看】

Black 在 VSCode 里不自动格式化 Python，90% 是因为解释器没对上、provider 没设对、或 pyproject.toml 不在根目录且缺 [tool.black] ——三者必须同时满足，少一个都不行。

Python 解释器路径必须和 black 安装环境一致

VSCode 不会跨环境找 black，它只在你当前选中的 python.defaultInterpreter 对应的环境里执行 python -m black。终端里能跑 black --version，不代表 VSCode 能用。

按 Ctrl+Shift+P（Mac 为 Cmd+Shift+P），运行 Python: Select Interpreter，确认路径指向你装了 black 的环境（如 ./venv/bin/python 或 ~/miniconda3/envs/myenv/bin/python）
在 VSCode 集成终端里运行 python -m black --version，有输出才算真正可用；若报 ModuleNotFoundError: No module named 'black'，就立刻在这个环境下重装：pip install black
用 conda 的话，别只在 base 环境装 black，必须先 conda activate myenv 再 pip install black

`python.formatting.provider` 必须显式设为 `black`

VSCode 默认不设这个字段，也不会 fallback 到 black，哪怕你装了插件、甚至装了 ms-python.black-formatter 扩展。它只认 python.formatting.provider 这个开关。

Python 3.14.2

Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。

下载

打开 Preferences: Open Settings (JSON)，加这三行（注意方括号和逗号）：
"python.formatting.provider": "black"
"editor.formatOnSave": true
"[python]": { "editor.formatOnSave": true }
删掉 python.formatting.blackArgs 这类冗余配置——除非你真要覆盖 pyproject.toml 里的设置，否则它大概率被忽略，还容易拼错成 python.formatting.blackargs（小写 a）导致静默失效
别信“自动识别”：设成 auto 时 VSCode 会按 black → yapf → autopep8 顺序找，多环境时极易误判

`pyproject.toml` 必须在项目根目录且含 `[tool.black]`

VSCode 的 Python 扩展只认工作区根目录下的 pyproject.toml，且必须包含合法的 [tool.black] 段。写成 .black、black.toml、或放在 src/ 里，它直接无视。

最小可用配置示例（存为项目根目录下的 pyproject.toml）：
[tool.black]
line-length = 88
skip-string-normalization = true
include = '\.pyi?$'
exclude = '''/( \.git | __pycache__ | venv )/'''
python.formatting.blackArgs 只能传额外参数（比如 --diff），不能覆盖 line-length 或 exclude ——这些全由 pyproject.toml 控制
改完配置后，必须执行 Ctrl+Shift+P → Developer: Reload Window，否则旧缓存会让新规则不生效

最容易被忽略的是：VSCode 的 Python 扩展根本不读 black 插件的配置项，也不管你装了多少个 formatter 插件；它只依赖 python.defaultInterpreter + python.formatting.provider + 根目录下有效的 pyproject.toml 这三样东西。缺一不可，且顺序不能乱。