Ruff：一个工具终结你的Python代码洁癖

一、Python开发者的工具地狱如果你维护过一个中大型Python项目大概率经历过这样的场景flake8 做静态检查black 管格式化isort 理导入顺序pydocstyle 查文档字符串pyupgrade 做语法现代化升级autoflake 清未使用的导入……一个 pre-commit 钩子里塞了五六种工具CI 流水线跑一次代码检查要等几十秒甚至几分钟本地改一行代码按下保存后等着各种工具排队运行。这还不算版本兼容问题。flake8 和 black 偶尔对同一行代码有不同看法配置项散落在 setup.cfg、pyproject.toml、.flake8 三个文件里改一条规则要在好几个地方同步。新成员入职光配开发环境就要折腾半小时。有没有一个工具能把这些全干掉还比它们加起来快100倍这就是 Ruff。二、Ruff 是什么Ruff 是 Astral 公司用 Rust 写的高性能 Python linter 和 formatter开源MIT 协议2022 年发布至今 GitHub star 数已超 35k。它要解决的核心问题很直白你不再需要 flake8、black、isort、pydocstyle、pyupgrade、autoflake 中的任何一个一个 ruff 命令全部搞定而且快到让你怀疑它到底有没有在干活。FastAPI 创始人 Sebastián Ramírez 的原话是Ruff is so fast that sometimes I intentionally introduce an error just to make sure its still running.三、核心优势拆解3.1 性能碾压级的快Ruff 到底有多快看一组实测对比项目Django 源码约 60 万行 Python工具单次扫描耗时相对 Ruff 的倍数Ruff0.12 秒1xFlake814.3 秒~120xPylint42.8 秒~357xBlack格式化2.1 秒~18xRuff formatter0.18 秒1xDagster 创始人 Nick Schrock 分享过在他们 25 万行的代码库上Pylint 需要 2.5 分钟Ruff 只用0.4 秒。快的秘密有两个层面语言层面Rust 零成本抽象 无 GC 编译到原生代码直接避免了 Python 解释器开销。Flake8 底层其实是 Python 进程每个检查插件都在 Python 虚拟机里跑一遍 AST而 Ruff 在 Rust 里一次性构建 AST 后批量执行所有规则。架构层面增量缓存 多线程并行。改了一个文件只检查那一个没改的直接读缓存跳过。配合 --watch 模式每次保存瞬间出结果。3.2 规则库800 条开箱即用Ruff 重新实现了几乎所有主流 Flake8 插件的规则按字母前缀分类前缀来源/类别规则数举例E/Wpycodestyle71E501行太长FPyflakes58F841未使用变量Bflake8-bugbear68B006可变默认参数Iisort20I001导入顺序SIMflake8-simplify30SIM108用三元表达式UPpyupgrade46UP006用 list 替代 typing.ListNpep8-naming32N801类名应大写开头Dpydocstyle70D100模块缺文档字符串你可以按需启用想要严格的类型注解检查加 ANN。想做安全审计加 Sbandit。想强制写 docstring加 D。一条 select 配置搞定不用装七个插件。3.3 自动修复能力Ruff 不是只告诉你哪里错了的唠叨工具。大量规则支持 --fix 自动修复而且分两个安全等级安全修复safe fix绝对不会改变代码语义。比如删掉未使用的导入 import os、把 list() 改成 []、修复缩进对齐。不安全修复unsafe fix可能会改变行为需要你确认。比如删除未使用的变量 x expensive_call()——删了变量函数调用也不执行了。运行 ruff check --fix 只应用安全修复加上 --unsafe-fixes 才上第二档。这个设计很聪明你可以在 CI 里只跑安全修复在本地手动确认后再跑不安全修复。3.4 统一格式化器v0.1.0 起 Ruff 内置了自己的格式化器目标是 99.9% 兼容 Black 的输出风格同时快 10-30 倍。关键特性与 linter 共享配置不会出现linter 说要这样、formatter 偏要那样的冲突。因为两个功能跑在同一套 AST 上。2026 Style Guidev0.15.0 引入了更激进的格式化风格如 lambda 体自动加括号、Python 3.14 的 except 元组去括号向前兼容未来 Python 语法。行宽、引号风格、缩进等全部可配置行为与 Black 一致但更多控制权。3.5 编辑器集成体验VS Code 官方扩展 charliermarsh.ruff 在保存时自动运行 Ruff错误红色波浪线 一键修复。JetBrains 系PyCharm、Neovim、Emacs 也都有成熟集成。最直观的感受保存文件后 100ms 内IDE 里所有格式问题和 lint 警告全部更新。不再像以前用 flake8 那样改完一行等两秒才看到红线冒出。四、适用场景场景一新项目一杆到底从项目第一天就把 Ruff 引入配置好 pyproject.tomlpre-commit 一挂团队成员零成本上手。场景二老项目迁移剃头接手一个几万行的老代码库代码风格参差不齐。用 Ruff 的 --fix 一次性批量修复再配置 CI 阻止新增问题。迁移成本极低在 pyproject.toml 里加一段配置CI 脚本里加一行 ruff check。场景三Monorepo 分层管理Ruff 支持分层配置。根目录一个宽松的 ruff.toml子包如 src/api/ruff.toml、src/cli/ruff.toml可以覆盖或收紧规则。每个团队管自己的风格互不打架。场景四CI/CD 快速门禁把你的 CI lint 步骤从 30 秒缩减到 0.5 秒。对频繁提交的分支来说这个差距会滚雪球式放大。配上一个 --exit-zero甚至可以在 PR 评论里建议式提示而非硬性阻断。场景五pre-commit 钩子零感知# .pre-commit-config.yaml repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.15.0 hooks: - id: ruff args: [--fix] - id: ruff-formatgit commit 时自动运行快到你感觉不到它的存在——不再有提交代码先去倒杯水的体验。五、从零上手10 分钟配置指南5.1 安装Ruff 是单个二进制安装方式非常多# 推荐通过 uv 安装uv 也是 Astral 出品Python 包管理器 uv tool install rufflatest # 传统方式 pip install ruff # 给项目加开发依赖 uv add --dev ruff # macOS/Linux 直接装二进制 brew install ruff # Windows powershell -c irm https://astral.sh/ruff/install.ps1 | iex验证ruff --version # ruff 0.15.05.2 最小化配置在项目根目录创建 ruff.toml也可以写在 pyproject.toml 的 [tool.ruff] 下# ruff.toml # 目标 Python 版本 target-version py312 # 行宽与 Black 一致 line-length 100 # ──── Linter 配置 ──── [lint] # 启用哪些规则组 select [ E, # pycodestyle 错误 W, # pycodestyle 警告 F, # Pyflakes B, # flake8-bugbear I, # isort导入排序 N, # pep8-naming命名规范 UP, # pyupgrade语法现代化 SIM, # flake8-simplify简化建议 C4, # flake8-comprehensions ] # 忽略特定规则按项目需要调整 ignore [ E501, # 行太长交给 formatter 处理 ] # ──── Formatter 配置 ──── [format] quote-style double indent-style space docstring-code-format true5.3 常用命令速查# Lint 检查 ruff check # 检查当前目录 ruff check --fix # 自动修复 ruff check --fix --unsafe-fixes # 含不安全修复 ruff check --watch # 监听模式文件变动自动检查 ruff check --statistics # 按规则统计问题数量 # 格式化 ruff format # 格式化当前目录 ruff format --check # 仅检查不修改CI 用 ruff format --diff # 显示差异不应用 # 查看某条规则的说明 ruff rule E501 # 查看 E501 详情 # 仅检查指定文件/目录 ruff check src/models/user.py ruff check src/5.4 实战工作流日常开发配好 VS Code 扩展 ruff.toml保存即检查。提交前运行 ruff check --fix ruff format自动化清理。CI 流水线GitHub Actions 示例name: Lint on: [push, pull_request] jobs: ruff: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: astral-sh/ruff-actionv3 with: args: check - uses: astral-sh/ruff-actionv3 with: args: format --check5.5 渐进式迁移从 Flake8Black 迁到 Ruff如果你已有项目在用 Flake8 Black isort迁移分三步走第一步对齐规则# 先生成当前 flake8 正在使用的规则列表 flake8 --selectE,W,F,B --formatjson . old_issues.json # 用 ruff check --statistics 对比差异 ruff check --statistics把差异规则按需加入 ignore 或 select。第二步一次性批量修复ruff check --fix --unsafe-fixes # 先修 lint ruff format # 再格式化建议在一个独立分支上执行方便 code review 对比 diff。第三步替换 CI 和 pre-commit删掉 .flake8、pyproject.toml 里的 isort 配置把 CI 脚本里的 flake8 black --check isort --check 换成两行 ruff check ruff format --check。迁移完成后的收益非常直观以 Django 规模的项目为例CI lint 步骤从~22 秒降至 ~0.3 秒。六、Ruff vs 同类方案维度RuffFlake8 插件Black isort Pylint安装复杂度单二进制5-10 个 pip 包3 个 pip 包配置文件1个 tomlsetup.cfg .flake8 tox.inipyproject.toml .pylintrcLint 速度Django 规模0.12s14s42sFormatter 速度0.18s不适用2.1s仅 Black内置规则数800100基础400自动修复安全/不安全双档有限有限规则冲突处理无同 AST常有常有编辑器体验保存即检查有延迟明显延迟社区生态快速增长成熟但停滞成熟七、实践建议与注意事项建议新项目直接上 Ruff——没有历史包袱一开始就严格配置 select养成好习惯。老项目用 --fix 一次性剃头然后在 CI 中只跑 ruff check不加 --fix阻断新增问题。善用 per-file-ignores。比如测试文件里放宽某些规则[lint.per-file-ignores] tests/**/*.py [D100, S101] # 测试不需要模块文档字符串允许 assert配合 uv 做全链路 Rust 化uv 管理依赖 Ruff 管理代码质量两个工具都来自 Astral协作零摩擦。注意事项Ruff 的规则实现是重新实现而非调用原版极少数边界情况可能与 Flake8 行为有微小差异。迁移后建议跑一轮完整对比。Formatter 稳定版已发布v0.1.0 起但不保证与 Black 的每一个空格位置完全一致。对格式极其敏感的场景先用 ruff format --diff 预览。部分冷门 Flake8 插件尚未被 Ruff 重写。如果你的项目严重依赖某个小众插件先检查 Ruff 是否已覆盖对应规则前缀。Ruff 用了三年时间2022-2025从又一个 linter成长为 Python 代码质量的事实标准工具链。它证明了用 Rust 重写 Python 工具不是噱头而是从架构层面真正改变了开发者的日常体验——把原本需要排队等十几秒的检查压缩到在你松开拓键之前就已完成。如果你还没试过给你的主项目跑一次 pip install ruff ruff check --statistics看看它会检出什么大概率你会立刻把 .flake8 删掉。