Python 的 lint 环节长期是个性能黑洞:Flake8 加一堆插件跑全仓要几十秒,Black 格式化大项目也要等上一会儿。Ruff 用 Rust 把这两件事合起来重写了,官方定位是"An extremely fast Python linter and code formatter, written in Rust",比现有 linter 和 formatter 快 10~100 倍,一个工具同时替代 Flake8、isort、Black、pyupgrade、autoflake 等一整串工具。项目约 50k Star,MIT 协议,由 Astral 团队(也是 uv 的作者)维护。本文先讲安装与基本用法,再看配置与编辑器集成,最后给出迁移策略。
1、概述与安装
Ruff 是单一二进制,零 Python 依赖却可以直接 pip install,这是它设计上最讨巧的一点——能进 requirements.txt,能在任何 CI 里即装即用。它内置 900 多条规则,复刻了 flake8-bugbear、flake8-simplify 等热门插件的大部分规则集,并且是 Flake8、isort、Black 的 drop-in 替代:迁移成本几乎只有改一行命令。
安装方式按场景任选其一。
pip install ruff
uv tool install ruff@latest
uv add --dev ruff
前两行适合独立安装,第三行适合在 uv 管理的项目里作为开发依赖加入。此外也支持 pipx,或官方脚本 curl -LsSf https://astral.sh/ruff/install.sh | sh 与对应的 PowerShell 命令。
2、核心命令
日常只有两条命令:lint 和格式化。
ruff check
ruff format
ruff check 检查当前目录下所有文件,ruff format 则一次性完成格式化,行为对齐 Black 的输出风格。想只针对特定规则做清理也行,比如清理未使用的 import。
ruff check --select F401 --select F403 --quiet --fix
F401 是未使用导入、F403 是星号导入,加上 --fix 后 Ruff 会自动修复能修的问题。它内置缓存,重复执行近乎零耗时。速度到底是什么量级?用户 Nick Schrock 的评价是:pylint 在 4 核 M1 上跑约 2.5 分钟的代码库,Ruff 全仓扫描约 0.4 秒,约 1000 倍;Bryan Van de Ven 的数据是比 flake8 快约 150~200 倍,全仓从约 20 秒降到约 0.2 秒。这意味着你可以把 lint 放进每次保存、每次提交甚至每次按键,而不觉得卡。
3、配置详解
Ruff 的配置写在 ruff.toml 或 pyproject.toml 的 [tool.ruff] 段,一份典型配置如下。
line-length = 88
indent-width = 4
target-version = "py310"
[lint]
fixable = ["ALL"]
unfixable = []
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
[format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"
逐段解读:顶层的 line-length 与 Black 默认一致,target-version 决定哪些规则启用(比如 py310 以上才会建议新语法)。[lint] 段里 fixable = ["ALL"] 表示所有可自动修复的规则都允许 --fix 动手,dummy-variable-rgx 定义了哪些名字视为合法的占位变量(下划线开头)。[format] 段控制格式化细节:双引号、空格缩进、自动行尾。monorepo 场景下 Ruff 支持层级配置,子目录的配置文件可以覆盖父级,按包精细调规则。
4、编辑器与钩子集成
本地 CI 双保险的常见做法是把 Ruff 挂进 pre-commit。
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.16.10
hooks:
- id: ruff-check
args: [ --fix ]
- id: ruff-format
这份 .pre-commit-config.yaml 片段定义了两个钩子:ruff-check 带上 --fix 在提交前自动修 lint 问题,ruff-format 则保证提交的代码永远格式化过。编辑器侧,VS Code 安装 Ruff 扩展后可获得保存时格式化与实时诊断,其他主流编辑器(Vim、Emacs、Helix 等)也有社区集成。由于 Ruff 单次检查是毫秒级,编辑器里的反馈基本无延迟,这是旧工具链给不了的体验。
5、迁移策略与注意事项
从 Flake8 或 Black 迁移基本无痛:把命令行里的 flake8 换成 ruff check、black 换成 ruff format,输出风格高度兼容。需要留意的点有几个。第一,Ruff 是静态分析,部分依赖类型信息的深度检查(类似 pylint 的某些逻辑检查)不在覆盖范围内,必要时可保留 mypy 做类型检查,两者互补而非互替。第二,规则默认只启用 E4/E7/E9/F 这一小部分,想要更严格的代码质量,需在 [lint] 里显式 select 更多规则集,如 B(bugbear)、I(isort)、UP(pyupgrade)。第三,团队启用 --fix 前建议先约定 unfixable 白名单,避免自动修复改出不期望的行为。
替代关系一目了然。
| 旧工具 | Ruff 对应 |
|---|---|
| flake8 + 插件 | ruff check |
| black | ruff format |
| isort | I 规则集 |
一个二进制换掉三个工具加一堆插件,CI 时长和心智负担同时下降。
6、总结
Ruff 用 Rust 把 Python 的 lint 与格式化提速了一到两个数量级,900+ 规则、自动修复、编辑器与 pre-commit 的成熟集成,让它成为当前 Python 工程化的事实标配之一。对于新项目,建议从第一天起就用 ruff check 加 ruff format 并配置 pre-commit;对于存量项目,建议先做 drop-in 替换跑通 CI,再逐步调严规则集,细节可参考 官方文档。

