ruff：一个工具替掉 black + flake8 + isort + pyupgrade

这一章是纯阅读章节，没有练习题。

ruff 是命令行工具，浏览器里的 Pyodide 跑不起来。这一章我们把概念、用法、配置讲清楚，各位在自己本地装好 Python 环境之后实际跑一遍就能掌握。

各位还记不记得 2022 年那会儿，开一个 Python 新项目，光「保证代码风格统一」这件事就要装一堆东西：

• black：自动格式化代码，管缩进、换行、引号
• flake8：检查语法错误、未使用变量、命名不规范
• isort：把 import 语句按字母顺序、按分组重新排列
• pyupgrade：把老语法升级到新版本，比如 Dict[str, int] 改成 dict[str, int]
• pydocstyle：检查 docstring 写得规不规范
• bandit：扫一扫有没有安全漏洞

六个工具，六份配置文件，六套规则，每个工具自己装一遍，CI 上每个跑一遍，commit 之前每个调一遍。配一个新项目的 lint 流水线，光研究这些工具怎么互相不打架就能花掉半天。

直到 2022 年底，Astral 公司——就是上一章那个写 uv 的 Astral——丢出来一个叫 ruff 的东西。这家公司有个特点：用 Rust 重写 Python 工具链，并且比原版快 10 到 100 倍。

ruff 一上来就把 flake8、isort、pyupgrade、pydocstyle、bandit 这些工具的规则一口气全实现了，后来又补上了 format 子命令，把 black 的功能也吃掉了。一个二进制文件，一份配置，一套命令。

到 2024 年，ruff 已经是 Python 社区的事实标准，Pandas、FastAPI、Pydantic、Hugging Face Transformers、Apache Airflow 都换了过去。到 2026 年的今天，各位开新项目，几乎不会再有人推荐用 flake8 + black + isort 这套老组合了。

这一章学完之后，各位应该能：

1. 在新项目里五分钟内配好 ruff
2. 看懂别人 pyproject.toml 里那一坨 [tool.ruff] 配置
3. 把 ruff 接进 pre-commit、CI、编辑器
4. 把老项目从 black + flake8 + isort 平滑迁移过来

老办法到底烦在哪

先回忆一下老办法是怎么个用法。一个比较「正经」的项目，根目录下通常会出现这些配置：

my-project/
├── pyproject.toml         # 部分工具的配置
├── setup.cfg              # flake8 必须放这里（或单独的 .flake8）
├── .flake8                # flake8 配置（可选）
├── .isort.cfg             # isort 配置（可选）
├── .pre-commit-config.yaml
└── ...

每个工具有自己偏好的配置文件位置：

• black 看 pyproject.toml 的 [tool.black]
• flake8 死活不支持 pyproject.toml，只能用 .flake8 或 setup.cfg
• isort 可以放 pyproject.toml、.isort.cfg、setup.cfg，看心情
• pyupgrade 没配置文件，全靠命令行参数

这就埋了第一个坑——配置散落各处，新人接手项目，光找配置文件就要找半天。

第二个坑是工具之间会打架。最经典的就是 black 和 flake8 冲突。black 默认行宽 88 字符，flake8 默认行宽 79 字符。两个不调一致，black 格式化完，flake8 就报 E501 line too long。

isort 和 black 也会打架。isort 默认按某种风格排 import，black 不一定接受，要给 isort 加上 --profile black 才能一致。

第三个坑是慢。一个中型项目，跑 flake8 . 几秒到几十秒；跑 black . 几秒到十几秒；跑 isort . 也要几秒。CI 上串起来跑一遍，几十秒就没了。本地保存文件时想跑一遍 lint，慢到没法接进编辑器。

ruff 是个啥

ruff 是 Astral 公司开源的 Python 代码检查 + 格式化工具。两个关键属性：

1. 用 Rust 写的。Python 工具用 Python 写，速度天花板就在那里。换成 Rust，速度能上一两个数量级
2. 一个工具替掉一堆。flake8、black、isort、pyupgrade、pydocstyle、bandit、pylint 的部分规则、autoflake，全部内置

看一下 ruff 官方公布的速度对比。在 CPython 项目（约 25 万行代码）上跑：

这速度有什么用？两点重要：

1. 保存文件时实时跑 lint 成为可能。编辑器里每次 Ctrl+S，ruff 后台跑一遍，几乎感觉不到延迟
2. CI 时间短。从前 lint 阶段要 30 秒，现在 1 秒就过了

「那它支持多少规则？」截至 2026 年，ruff 已经实现了 800 多条规则，覆盖了 flake8 主线 + 几十个 flake8-* 插件 + isort + pyupgrade + pydocstyle + pylint 的一部分 + bandit 的一部分。换句话说，几乎所有主流 Python lint 工具的能力，ruff 都吃下来了。

常用规则集一览

ruff 用「字母前缀」给规则分组：

完整清单官方文档里有，叫「Rules」页面，规则号、说明、是否能自动修都列得清清楚楚。

ruff vs black + flake8 + isort 对照表

一个常见坑：和 mypy 的关系

很多童鞋会问：「ruff 能替代 mypy 吗？」

不能。

ruff 是 lint + formatter，做的是「代码风格、常见错误模式」检查。mypy 是类型检查器，做的是「这个变量传给那个函数，类型对不对」这种全局类型推导。两者是不同维度的工具，互补使用。

正确的姿势：

• 用 ruff 管风格、import、明显 bug、语法升级
• 用 mypy 或者 pyright 管类型

CI 上两个都跑：

- run: ruff check .
- run: ruff format --check .
- run: mypy .

ruff 倒是有几条规则（前缀 ANN）会做粗浅的类型注解检查，比如「这个函数没有写 return 类型」。但是它不会真正去推导类型一致性，复杂的类型问题还是要靠 mypy。

安装与第一次跑

老规矩，推荐用 uv 装：

uv add --dev ruff

--dev 的意思是「装到开发依赖组」，发布生产环境时不会带上。ruff 是开发工具，只在开发和 CI 时用，所以放 --dev 最合适。

如果项目还没用 uv，用 pip 装也行：

pip install ruff

或者用 pipx 装成全局命令：

pipx install ruff

装完之后，验证一下：

ruff --version

输出类似：

ruff 0.8.0

第一次跑

进项目目录，跑一下：

ruff check .

这条命令会扫描当前目录下所有 .py 文件，按默认规则检查。各位第一次跑大概率会看到一堆告警：

foo.py:3:1: F401 [*] `os` imported but unused
foo.py:8:5: E731 Do not assign a `lambda` expression, use a `def`
bar.py:12:80: E501 Line too long (95 > 79)

格式很清晰：文件名:行:列: 规则号 描述。规则号前面如果带个 [*]，说明这条规则可以自动修复。

要让 ruff 自动修，加 --fix：

ruff check --fix .

跑完之后，os imported but unused 这种问题，ruff 直接把那行 import os 删掉了。

格式化代码用另一个子命令：

ruff format .

这条命令的行为基本和 black . 一样——把整个项目的代码风格统一到一致的缩进、引号、换行规则。

把这两条命令加在一起，就是日常 commit 之前的标准流程：

ruff check --fix . && ruff format .

先 lint 再 format，齐活。

自动修复实战

ruff check --fix . 能修哪些东西？挑几个常见的看看。

F401：未使用的 import

import os
import sys

print(sys.version)

ruff check --fix 之后：

import sys

print(sys.version)

os 没用上，直接删掉。

E711：和 None 比较应该用 is

if x == None:
    print("x 是 None")

修复后：

if x is None:
    print("x 是 None")

为什么要改？因为 == 会触发 __eq__ 方法，有些类的 __eq__ 实现得稀奇古怪（比如 numpy 数组），跟 None 比较会出意想不到的结果。is None 是身份比较，永远只看「是不是同一个对象」，绝对安全。

C408：不必要的 list/dict/tuple 调用

empty = list()
d = dict()
t = tuple()

修复后：

empty = []
d = {}
t = ()

list() 和 [] 等价，但是 list() 要去全局名字空间里查 list 这个名字、再调用，慢一点。直接写字面量更快也更短。

UP006：用新版类型注解

from typing import List, Dict

def foo(x: List[int]) -> Dict[str, int]:
    pass

修复后（target-version = "py39" 以上）：

def foo(x: list[int]) -> dict[str, int]:
    pass

Python 3.9+ 已经支持直接用 list[int] 写类型注解，不用再从 typing 里 import 了。

UP008：用 super() 不要带参数

class Foo(Bar):
    def __init__(self):
        super(Foo, self).__init__()

修复后：

class Foo(Bar):
    def __init__(self):
        super().__init__()

Python 3 里 super() 不传参数就够了，老 Python 2 风格的 super(Foo, self) 是历史包袱。

I001：import 排序

import sys
from my_project import utils
import os
import requests

修复后：

import os
import sys

import requests

from my_project import utils

ruff 把 import 按「标准库 → 第三方 → 第一方」分成三组，每组之间空一行，组内按字母序排。这等同于跑了一遍 isort。

不安全修复

有些修复 ruff 不会默认做，因为可能改变行为。比如把 dict() 改成 {}——99% 情况下等价，但是如果你的代码里 dict 这个名字被覆盖了，行为就变了。这种修复叫「unsafe fix」，要加 --unsafe-fixes 才会做：

ruff check --fix --unsafe-fixes .

各位如果心里没底，先 ruff check --fix . 跑安全的，再用 --unsafe-fixes 单独跑一遍并 review 改动。

ruff format：black 替代品

ruff format . 干的事跟 black . 几乎一样：

• 行宽默认 88
• 字符串默认双引号
• 缩进 4 空格
• 函数参数过长自动换行
• 字典、列表、set 字面量按一致风格排版

格式化前：

def foo(a,b,c, d ):
    return  {  'name':a,'age':b,'list':[1,2,3]  }

ruff format . 之后：

def foo(a, b, c, d):
    return {"name": a, "age": b, "list": [1, 2, 3]}

Astral 在文档里明确写过「ruff format 与 black 99.9% 兼容」，各位从 black 迁过来不用担心代码风格突变。

ruff format 也支持 --check 模式，只检查不改：

ruff format --check .

如果有文件需要格式化，命令返回非零 exit code，CI 上可以拿来卡住「忘了 format 就提交」的 PR。