Black插件在Sublime Text中本质是调用已安装的black命令，需先在终端确认black --version可用，并手动配置绝对路径；路径错误、环境不匹配或未装black是插件不生效的根本原因。
Black插件在Sublime Text里根本不能直接安装
Sublime Text本身不支持直接 pip install black，也没有官方维护的 Black 插件包。所谓“安装Black插件”，实际是配置 Sublime Text 调用系统已安装的 black 可执行文件——它必须提前在命令行能跑通 black --version，否则后续所有自动格式化都会静默失败。
常见错误现象：Unable to find command "black" 或保存后无反应，大概率是路径没对上，不是插件没装好。
- 先在终端运行
which black（macOS/Linux）或where black（Windows），确认可执行文件位置 - 如果用 pyenv、conda 或 Poetry 管理环境，
black很可能只在特定 shell 里可用；Sublime Text 启动时不会继承这些 shell 的 PATH，得手动指定路径 - 不要依赖 Package Control 搜索到的同名插件（如
Black Formatter），多数已弃用或仅兼容旧版 Sublime Text 3
用Sublime Text自带的build system调用black最稳
不用额外装插件，靠 Sublime Text 原生 .sublime-build 配置就能完成格式化，且兼容 Sublime Text 4，启动快、无冲突。
操作步骤：
立即学习“Python免费学习笔记（深入）”；
- 菜单栏选择 Tools → Build System → New Build System…
- 清空默认内容，粘贴以下配置（注意把
/path/to/black替换成你真实路径，比如/Users/you/.pyenv/shims/black或C:\Users\you\AppData\Local\Programs\Python\Python311\Scripts\black.exe）：
{
"cmd": ["/path/to/black", "$file"],
"selector": "source.python",
"working_dir": "$file_path",
"variants": [
{
"name": "Black (check only)",
"cmd": ["/path/to/black", "--check", "--diff", "$file"]
}
]
}
保存为 Black.sublime-build（自动存进 Packages/User/）。之后按 Ctrl+B（Win/Linux）或 Cmd+B（macOS）即可格式化当前文件；Ctrl+Shift+B 可选 Black (check only) 预览变更而不写入。
保存时自动格式化需手动改设置，且有陷阱
Sublime Text 默认不支持“保存即格式化”，得靠第三方插件 SublimeOnSaveHook 或修改 Preferences.sublime-settings 触发 build system。但后者有严重限制：它会阻塞保存流程，一旦 black 报错（比如语法错误），文件就卡在未保存状态。
- 推荐方案：装
SublimeOnSaveHook（Package Control 可搜到），然后在Preferences → Package Settings → SublimeOnSaveHook → Settings里加：
{
"on_save": [
{
"command": "build",
"args": {"build_system": "Black"}
}
]
}
- 务必勾选
"show_panel_on_build": false，否则每次保存都弹出 build panel 干扰编码 - 如果项目用了
pyproject.toml配置black选项（如line-length = 88），确保该文件在$file_path目录或其父级目录中，black才会自动读取
Windows下路径空格和反斜杠容易导致build失败
Windows 用户最容易栽在这里：Python 安装路径含空格（如 C:Program FilesPython311Scriptslack.exe）或用了反斜杠 ，Sublime Text 的 build system 会直接解析失败，报错 [Errno 2] No such file or directory。
- 解决方法一：用短路径（DOS 8.3 格式），例如
C:Progra~1Python311Scriptslack.exe（用dir /x查看） - 解决方法二：改用正斜杠，并用双引号包裹整个路径（JSON 允许）：
"cmd": ["C:/Program Files/Python311/Scripts/black.exe", "$file"] - 避免用 PowerShell 的
black.ps1脚本——Sublime Text 的 build system 默认调用 cmd，不识别 ps1
路径问题不解决，其他所有配置都白搭。建议先在 CMD 里手动跑通 "C:Program FilesPython311Scriptslack.exe" --version 再配 Sublime。
