Black 在 PyCharm 中的集成方式（内置、BlackConnect、外部工具、文件监视器）怎么选

Black 在 PyCharm 中的集成方式（内置、BlackConnect、外部工具、文件监视器）怎么选

【免费下载链接】blackThe uncompromising Python code formatter项目地址: https://gitcode.com/GitHub_Trending/bl/black

如果你已经在用 PyCharm，希望不离开 IDE 就能用 Black 格式化 Python 文件，需要先解决一个选择问题：官方文档 docs/integrations/editors.md 中 "PyCharm/IntelliJ IDEA" 一节列出了四种接入方式，它们的安装成本、触发方式各不相同。本文按文档逐条给出每种方式的完整配置步骤，并基于文档给出的定位说明帮你确定该走哪一条。

四种方式都要求先安装 Black（pip install black或其带dextra 的变体），差异在于 PyCharm 侧的接入配置。

四种方式怎么选

先按文档给出的定位和触发模型缩小范围：

选择逻辑可以归纳为：PyCharm 版本在 2023.2 及以上、只想最少配置，走内置集成；格式化频繁、在意每次启动 Black 进程的开销，走 BlackConnect 本地服务器；想手动对当前文件执行格式化命令，走外部工具；希望文件变化时自动格式化，走文件监视器。

下面按推荐程度依次给出每种方式的操作步骤。

方式一：内置集成（PyCharm 2023.2 及以后）

这是文档标注最简单的路径，前提是 PyCharm 版本为 2023.2 或更高。

1. 安装 Black：

   $ pip install black

2. 打开Preferences or Settings -> Tools -> Black，按文档说法在此按你的喜好完成 Black 的配置（"configure Black to your liking"）。

文档对该方式的说明仅到此为止：它依赖 PyCharm 自带的 Black 集成，不需要额外插件，也没有需要手工填写路径的步骤。如果你的 PyCharm 满足版本要求，可以先走这条路。

方式二：BlackConnect 本地服务器（blackd）

文档定位这是四种方式中格式化最快的一种：插件会拉起blackd（Black 的 HTTP 服务器），"to avoid the startup cost on subsequent formats"，即避免后续每次格式化都承担进程启动成本。blackd的详细协议见 docs/usage_and_configuration/black_as_a_server.md。

1. 安装带dextra 的 Black（blackd默认不随 Black 一起打包，有额外依赖，必须这样安装）：

   $ pip install 'black[d]'

2. 安装 BlackConnect IntelliJ IDEs 插件（在 IDE 的插件市场安装即可）。

3. 打开插件配置：

   • macOS：PyCharm -> Preferences -> Tools -> BlackConnect
   • Windows / Linux / BSD：File -> Settings -> Tools -> BlackConnect

4. 在Local Instance (shared between projects)区域：

   • 勾选Start local blackd instance when plugin loads；
   • 点击Path输入框旁边的Detect按钮。文档预期"the plugin should detect theblackdexecutable"——如果 Detect 能识别到blackd可执行文件，说明第 1 步安装可用；识别不到时回头检查pip install 'black[d]'是否装进了当前 IDE 使用的解释器环境。

5. 在Trigger Settings区域勾选Trigger on code reformat，启用用 Black 做代码重格式化。

6. 格式化当前打开的文件：选择Code -> Reformat Code，或用它对应的快捷键。

7. 可选：希望每次保存都运行 Black，则在Trigger Settings中再勾选Trigger when saving changed files。

另外需要知道一条限制：blackd没有针对滥用的安全防护，文档明确警告它只应作为本地服务运行（"It is intended for local use only"），不要把它暴露为可公网访问的服务器。

如果想脱离插件单独确认blackd本身工作正常，可以按服务器文档给出的命令手动验证（以下代码块照抄自文档）：

blackd --bind-port 9090 & # or let blackd choose a port curl -s -XPOST "localhost:9090" -d "print('valid')"

blackd对格式化请求的响应码含义（来自服务器文档的协议一节）：HTTP 204表示输入已符合格式，响应体为空；HTTP 200表示需要格式化，响应体是格式化后的代码；HTTP 400表示输入有语法错误；HTTP 500表示其他格式化错误。

方式三：外部工具（External Tool）

这条路径把black配置成 PyCharm 的一个外部工具，通过菜单项手动对当前打开的文件执行格式化。

1. 安装 Black：

   $ pip install black

2. 找到black的安装位置。

   macOS / Linux / BSD：

   $ which black /usr/local/bin/black # possible location

   Windows：

   $ where black C:\Program Files\Python313\Scripts\black.exe # possible location

   上面两行输出是文档给出的"可能的安装位置"示例，你的实际输出会因安装环境不同而变化，以你本机命令的真实输出为准。

   文档特别说明：如果 PyCharm 已经识别了你使用的虚拟环境，这一步可以省略，此时black的路径直接写$PyInterpreterDirectory$/black（$PyInterpreterDirectory$是 PyCharm 的配置变量，指代当前项目解释器的安装目录）。

3. 打开外部工具设置：

   • macOS：PyCharm -> Preferences -> Tools -> External Tools
   • Windows / Linux / BSD：File -> Settings -> Tools -> External Tools

4. 点击+图标新增一个外部工具，字段值如下：

   • Name:Black
   • Description:Black is the uncompromising Python code formatter.
   • Program: 第 2 步得到的black路径（虚拟环境场景下为$PyInterpreterDirectory$/black）
   • Arguments:"$FilePath$"

   其中"$FilePath$"是文档原样给出的参数，格式化时将展开为当前文件的完整路径。

5. 格式化当前打开的文件：选择Tools -> External Tools -> black。

   • 可选：在Preferences or Settings -> Keymap -> External Tools -> External Tools - Black下设置键盘快捷键，之后直接按键触发。

方式四：文件监视器（File Watcher）

这条路径让 Black 在 Python 文件变化时自动运行，无需手动触发。

1. 安装 Black：

   $ pip install black

2. 找到black的安装位置，命令与虚拟环境场景下的处理方式同方式三第 2 步（which black/where black，或使用$PyInterpreterDirectory$/black），此处不再重复。

3. 确认已安装 File Watchers 插件（文档要求 "Make sure you have the File Watchers plugin installed"）。

4. 打开Preferences or Settings -> Tools -> File Watchers，点击+添加一个新的监视器，字段值如下：

   • Name:Black
   • File type:Python
   • Scope:Project Files
   • Program: 第 2 步得到的black路径
   • Arguments:$FilePath$
   • Output paths to refresh:$FilePath$
   • Working directory:$ProjectFileDir$

   这里出现的$FilePath$、$ProjectFileDir$都是文档原样给出的 PyCharm 监视器配置变量，分别表示被监视文件的路径和项目文件目录，保持原样填入即可。

5. 在 Advanced Options 中做两项取消勾选：

   • 取消Auto-save edited files to trigger the watcher
   • 取消Trigger the watcher on external changes

配置完成后，项目内的 Python 文件发生变化时，监视器会按上面的 Program 和 Arguments 调用black处理该文件，并刷新对应的输出路径。

限制与注意事项

• 内置集成仅适用于 PyCharm 2023.2 及以后的版本，文档给出的版本边界就是这个，低版本 PyCharm 只能选择后三种方式之一。
• BlackConnect 方式依赖blackd，必须用pip install 'black[d]'安装；且blackd仅限本地使用，不要暴露到公网。
• 外部工具和文件监视器两种方式都需要手工提供black的可执行路径，除非 PyCharm 识别到了你的虚拟环境，此时统一使用$PyInterpreterDirectory$/black。
• 文档标题为 "PyCharm/IntelliJ IDEA"，上述四种方式的设置路径（Preferences与Settings菜单差异除外）同样适用于 IntelliJ IDEA。

各方式的完整字段与命令以 docs/integrations/editors.md 的 "PyCharm/IntelliJ IDEA" 一节为准，blackd的请求头、协议细节见 docs/usage_and_configuration/black_as_a_server.md。

【免费下载链接】blackThe uncompromising Python code formatter项目地址: https://gitcode.com/GitHub_Trending/bl/black