psf/black

项目介绍

Black 是一个有明确立场、尽量减少可选项的 Python 代码格式化工具。它不参考文件原有排版，而是按同一套稳定风格重写整个文件，让不同项目的代码阅读体验一致，并尽量生成最小的 diff，便于代码评审。适用对象是需要自动统一 Python 风格的个人开发者与团队，也支持格式化 Jupyter Notebook。

默认情况下，Black 会检查格式化前后的代码是否生成等价 AST，这一步会拖慢处理速度；如果对结果有信心，可用 --fast 跳过。风格遵循 PEP 8，变更受稳定性策略约束，因此版本升级通常不会带来大范围格式变动。

快速使用

运行 Black 需要 Python 3.11 及以上版本。先安装：

pip install black

如需同时格式化 Jupyter Notebook，再安装扩展：

pip install "black[jupyter]"

按默认风格处理文件或目录：

black {source_file_or_directory}

如果直接作为脚本执行失败，可改用模块方式：

python -m black {source_file_or_directory}

文件会被原地改写。不想安装 Python 的用户，可以从 GitHub 最新 Release 获取用 PyInstaller 构建的独立可执行文件。

配置方式

Black 可以从 pyproject.toml 读取项目级默认值，主要用于自定义 --include 与 --exclude / --force-exclude / --extend-exclude 模式。它本身不要求配置，默认风格已与许多使用 Black 的项目一致；文件配置的完整说明见使用与配置文档。

使用约束

Black 运行时要求 Python 3.11 或更高版本。它刻意限制风格选项，并对边界情况的处理方式和 AST 等价检查有详细文档；遇到看似异常的格式化结果，应先阅读当前风格文档再判断是否为缺陷。项目采用 MIT 许可证。如果要在 README 中展示代码风格标签，可直接使用项目提供的 Markdown 或 reST 片段。

HotRepo 点评

在 2026-11-06 的 Python 语言日榜中，Black 当日新增 12 个 Star、位列该语言榜第 17，仓库总量为 42,118 Star 和 2,965 Fork。这只是单日快照，说明它仍在 Python 榜单中保持可见度，而不是增长趋势。对于一个 2018 年发布、刻意收窄配置面的格式化工具，更值得关注的是它仍出现在 Python 日榜上，同时团队通过项目配置继续采用它的风格。