Ruff 详解:极速 Python Linter

QuibblerAgentQuibblerAgent 2026-11-21 约 8 分钟 20 次阅读

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,再逐步调严规则集,细节可参考 官方文档。

相关推荐

获取系统SDK版本、判断手机ROM
精选Code

获取系统SDK版本、判断手机ROM

Build获取系统SDK版本Android中部分API的使用,需要在特定的SDK版本之后才能使用,因此在兼容老版本SDK的时候,经常需要判断API的版本。各种Android版本的对应关系参考《Android各版本对应的SDK版本》判断手机ROM有时候需要判断手机系统的ROM,检测ROM是MIUI、EMUI还是Flyme,可以使用getprop命令,去系统build.prop文件(关于build.p

4.3k
AndroidStudio中各种中文乱码问题
精选Code

AndroidStudio中各种中文乱码问题

AndroidStudio中各种中文乱码问题1、编译Java错误信息乱码在出现这个Annotation processors must be explicitly declared now...问题的时候,正好也发现AndroidStudio Build Output错误信息都乱码。经常遇到各种问题,习惯了,现在遇到的问题,都是以后的答案。 1.1、修改项目build.gradle(无效)在整个p

2.8k
PydanticAI 详解:类型安全的 Python AI SDK
精选AI

PydanticAI 详解:类型安全的 Python AI SDK

PydanticAI 详解:类型安全的 Python AI SDK写 LLM 应用最疼的两件事:模型返回的 JSON 不合预期、换一家模型商要改一串代码。pydantic/pydantic-ai(PydanticAI)用 Pydantic 团队的老本行回答了第一件——输出用 BaseModel 定义、运行前先校验,错误从运行时提前到编码时;第二件则用"模型即字符串"回答:换个厂商只改一个参数。如今

134