提交前跑一遍 flake8,等两分钟,报的全是风格问题,真正的 bug 还得人肉盯。Python 项目一大,代码检查慢得让人不想跑,工具还得攒一串。ruff 用 Rust 重写了整套检查器,官方 README 给的数字是比 flake8 快 10 到 100 倍,今晚就能装上试试。
项目名片
| 项目 | 内容 |
|---|---|
| 仓库 | astral-sh/ruff |
| Star / Fork | 51316 / 2774(2026-11-20 抓取) |
| 技术栈 | Rust(含 Python 脚手架) |
| 许可证 | MIT(LICENSE 原文已核) |
| 最新版本 | 0.17.6(2026-11-19 发布) |
| 默认端口 | 无(命令行工具,无常驻服务) |
| 最近提交 | 2026-11-19(main 分支) |
它解决什么问题
Python 代码检查传统上是拼积木:flake8 查错误,isort 管导入排序,black 管格式化,再加几个插件查安全和复杂度。每一件都要单独装、单独配,配置文件之间还会互相打架,跑一轮等半天,改一次提交前根本没人愿意全跑。ruff 把 linter 和 formatter 合进一个二进制,内置 900 多条规则,覆盖 flake8、pylint、isort 这些工具的常用规则(README:Over 900 built-in rules)。替掉的是那串工具和等待时间;替不掉的是个别插件独有的冷门规则,以及团队攒了多年的存量配置,迁移得逐条对着来。
核心机制
- 检查器用 Rust 实现,直接解析源码建语法树,不做类型推断,换来秒级速度(README:10-100x faster than existing linters)。
- 900 多条规则按来源分组,F 是 Pyflakes、E 和 W 是 pycodestyle、I 是 isort,文档 Rules 页能按组查,报错时每条都带规则 ID 和一句解释。
- 配置走 pyproject.toml 或独立 ruff.toml,默认行宽 88 和 Black 对齐,README 默认配置段原话是 Same as Black。
- 自带 formatter,ruff format 的定位是 Black 的直接替代(Formatter 文档原文:drop-in replacement for Black)。
- 支持行内 # noqa 注释压掉单条告警,还有专门的 RUF100 规则反过来查出没用上的 noqa(Default Rules 页可见 RUF100)。
- 配置文件支持分层和级联,子目录可以有自己的一套规则(README:hierarchical and cascading configuration)。
跑起来
一条命令装好:
pip install ruff
不想动 Python 环境的,用官方独立安装脚本,装到用户目录,不污染现有的解释器:
R=https://astral.sh
curl -LsSf $R/ruff/install.sh | sh
进项目根目录,先跑全量检查再试自动修:
ruff check .
ruff check --fix .
第一条只报问题不动代码;加 --fix 能自动修的直接改,比如删掉没用的 import、调整导入顺序。输出里每条告警都带规则编号,想看某条规则的完整说明,把编号输进文档搜索就行。再跑 ruff format --check . 看格式有没有偏离标准,大项目也只要一秒上下。
从零到能用
- 项目根目录建 pyproject.toml,写最小配置(见下方示例),行宽改成团队自己的标准。
- 跑 ruff check . 看第一轮报错,每条规则 ID 带解释,照着改,改不动的一条一条加进 ignore。
- 跑 ruff check --fix . 让能自动修的先修掉,剩下的手动过一遍,顺手看看哪些规则值得长期开着。
- 跑 ruff format . 统一格式,diff 一遍确认没改坏逻辑,有异议的文件用 # fmt: off 局部豁免。
- 编辑器里装官方 VS Code 插件 astral-sh.ruff,保存即提示,不用来回切终端。
- 想卡提交关口的,用 README 推荐的 ruff-pre-commit 仓库挂 pre-commit hook,示例里的 rev 要和你的版本对上。
最小配置示例(pyproject.toml):
[tool.ruff.lint]
select = ["E", "F", "I"]
line-length = 100
适合谁用 / 别用
适合:任何 Python 项目的开发者,从练习脚本到后端服务都用得上;刚接手老项目的人尤其该装,一轮检查能暴露一堆没人管的隐患。README 明说分层级联配置对 monorepo 友好,秒级速度也适合塞进 CI,不拖流水线。
别用:依赖某个 flake8 冷门插件、ruff 还没实现对应规则的团队,别硬迁,先查文档确认规则覆盖;存量规则配置庞大、没人手逐条核对的,直接全套切换风险大,先挑一个子目录试点跑两周再推开。
三个真实的坑
- 默认规则只开一小部分。README 默认配置段里 select 是注释掉的,注明完整清单见 Default Rules 页。装完跑一遍没报错,不等于代码没毛病,多半是规则没开够,得自己在 select 里把 E、F、I 这些组加进来。
- ruff format 是原地改文件。Formatter 文档写明就地写入,想先看效果用 ruff format --check 或加 --diff 预览,大改动前别裸跑;实在不想被动的代码块,用 # fmt: off 包起来(Formatter 文档 Format suppression 一节)。
- 缓存目录别提交进仓库。ruff 会在当前目录写 .ruff_cache,README 默认配置的 exclude 列表里专门列了它。记得同步写进 .gitignore,不然仓库多一个垃圾目录,同事一拉代码还以为中了招。
小结
回到开头那个等两分钟的 flake8:ruff 把同样的事压进一秒,一个二进制替掉一串工具,检查和格式化一条命令跑完。先从默认规则和 --fix 用起,配置不用一步到位,跑顺了再逐组加规则,提交前的检查习惯才守得住。
参考资料
- 仓库:https://github.com/astral-sh/ruff
- 官方文档:https://docs.astral.sh/ruff
- Formatter 文档:https://docs.astral.sh/ruff/formatter
- 默认规则清单:https://docs.astral.sh/ruff/default-rules
- pre-commit 集成:https://github.com/astral-sh/ruff-pre-commit
默认评论
Halo系统提供的评论