Ruff：Rust 驱动的 Python 检查与格式化工具
一个用 Rust 写的 Python 检查和格式化工具，把 Flake8、Black、isort 合到一起并明显提速。
GitHub astral-sh/ruff 更新 2026-11-07 分支 main 星标 50.7K 分叉 2.6K
Rust Python pyproject.toml Flake8 Black VS Code

🧭 决策指南

为什么现在热： 材料显示 Ruff 在 2026-11-07 日增 169 星、总计 50,691 星；README 同时强调 Rust 实现、10-100 倍速度、超过 900 条规则和 Python 3.15 兼容性，最新版本为 0.17.4。这些功能与近期版本信息可以解释关注度，但材料无法证明单一的上榜原因。

适合，如果你

  • 你维护 Python 项目，当前同时使用 Flake8、Black 和 isort。
    README 的项目定位明确列出可替换 Flake8、Black、isort，并宣称 drop-in parity。
  • 你的 Monorepo 需要 pyproject.toml、层级配置和缓存来减少重复分析。
    README 功能列表写明 pyproject.toml 支持、hierarchical and cascading configuration，以及 built-in caching。
  • 你希望把检查接入 VS Code、pre-commit 或 GitHub Actions。
    README Usage 章节分别给出了 VS Code、ruff-pre-commit 和 ruff-action 的集成说明。

不适合，如果你

  • 你的目标代码不是 Python，或不需要 Python 3.15 兼容性与 Python linting。
    核心描述将 Ruff 定义为 Python linter and code formatter，README 也围绕 Python 文件命令展开。
  • 你必须确认每个现有 Flake8 插件的兼容行为，但当前材料没有逐项说明。
    README 只提到 flake8-bugbear 等插件的 native re-implementations，并未列出全部插件兼容矩阵。

前置条件

  • Ruff 可通过 pip 安装：`pip install ruff`。
  • README 提供 Python 3.15 compatibility，但未提供最低 Python 版本。
  • 可使用 `uvx [email protected]` 直接运行指定版本。
  • 需要接入 GitHub Actions 时，README 示例使用 `ubuntu-latest` 与 `astral-sh/ruff-action@v3`。

第一步命令（README 原文）

uvx [email protected] check   # Lint all files in the current directory.

要注意

  • 使用 `--fix` 会自动修改代码，例如删除未使用的导入。
    README 功能列表明确写有 Fix support，并以 automatically remove unused imports 为例。
  • 固定版本集成需同步 0.17.4，例如 pre-commit 使用 `rev: v0.17.4`。
    README 安装命令和 pre-commit 示例均使用 0.17.4。
  • README 的速度数字来自声明和案例，不能当作所有项目都达到 10-100 倍。
    README 同时写有 10-100x、Dagster 250k LOC 的 0.4 秒案例和 Bokeh 的约 150-200x 案例。

替代方案

  • Flake8：当项目必须继续使用既有 Flake8 配置或插件链时，Flake8 更直接。
    README
  • Black：当团队只需要 Black 的格式化职责，而不想引入 Ruff 的 linting 与规则集合时，Black 更聚焦。
    README
  • isort：当工作流只要求独立的 import sorting 工具时，isort 更贴合该单一职责。
    README

材料未说明

  • README 未提供 Ruff 支持的最低 Python 版本。
  • README 未给出 10-100x 性能声明的硬件、代码规模和基准方法。
  • README 未提供 Flake8 插件的完整兼容矩阵。
  • README 省略的 Configuration 和 Rules 章节未在材料中展开具体配置键与规则启用方式。
  • 材料未说明从 Flake8、Black 或 isort 迁移时是否存在行为差异和配置转换工具。

💡 深度解析

6
适合 我现在要维护 Flake8 及其插件、isort、Black、pydocstyle、pyupgrade 和 autoflake，能否用 Ruff 统一检查、格式化和部分自动修复？
适合读者： 维护同时使用 Flake8、isort、Black、pydocstyle、pyupgrade 和 autoflake 的 Python 项目，并希望减少工具链维护工作的工程师

适合，因为 Ruff 明确把这些 Python 工具的大部分工作收敛到一个 Rust 原生可执行文件和统一接口中。

  • README 表示 Ruff 可替代 Flake8（含数十个插件）、Black、isort、pydocstyle、pyupgrade 和 autoflake。
  • 它提供超过 900 项内置规则，并原生重新实现包括 flake8-bugbear 在内的常用 Flake8 插件规则。
  • ruff check 负责检查并支持自动修复，例如移除未使用的导入；ruff format 提供格式化能力。
  • README 同时声明其目标是与 Flake8、isort 和 Black 保持 drop-in parity，但这不等于所有插件边界行为完全一致，因此迁移仍需核对现有 CI 结果。
  • README："Ruff can be used to replace Flake8 (plus dozens of plugins), Black, isort, pydocstyle, pyupgrade, autoflake, and more"
  • README："Over 900 built-in rules"
  • README："Fix support, for automatic error correction (e.g., automatically remove unused imports)"
  • README："Drop-in parity with Flake8, isort, and Black"
pip install ruff
材料未说明：README 未列出该项目当前使用的全部 Flake8 第三方插件及其规则覆盖率。；README 未说明迁移后每条既有规则与 Ruff 规则之间的逐项对应关系。
适合 我需要让 VS Code、本地 pre-commit 和 GitHub Actions 使用同一套 Python 检查与格式化流程，Ruff 能否覆盖这三个入口？
适合读者： 希望在 VS Code、pre-commit 和 GitHub Actions 中统一 Python 检查流程的工程师

适合，因为 README 为 VS Code、pre-commit 和 GitHub Actions 都提供了第一方或官方集成示例。

  • README 明确提供 VS Code 扩展，并链接到其他编辑器的集成说明。
  • ruff-pre-commit 示例同时配置 ruff-check 和 ruff-format，其中检查钩子可带 --fix。
  • GitHub Actions 示例使用 astral-sh/ruff-action@v3，并在 push 与 pull_request 上运行。
  • 这些入口共享 Ruff 的 check 和 format 命令，但 README 没有说明 VS Code、钩子和 CI 是否会自动读取完全相同的工作目录、版本或配置；示例中的 pre-commit 版本还需要与 CI 版本策略协调。
  • README："First-party editor integrations for VS Code and more"
  • README：`ruff-pre-commit` 示例包含 `ruff-check` 和 `ruff-format`
  • README：GitHub Actions 示例使用 `astral-sh/ruff-action@v3`
  • README：GitHub Actions 触发条件为 `push` 和 `pull_request`
pipx install ruff
材料未说明：README 未说明 VS Code 扩展如何处理多个嵌套 `pyproject.toml` 配置。；README 未给出本地 Ruff 版本、pre-commit rev 与 GitHub Action 版本不一致时的行为。
适合 我维护的是 Apache Airflow、Pandas 或 SciPy 这类大型 Python 代码库，提交钩子和 CI 都要求快速反馈，Ruff 是否值得替换现有检查器？
适合读者： 维护 Apache Airflow、Apache Superset、FastAPI、Hugging Face、Pandas 或 SciPy 这类大型 Python 代码库的工程师

适合，尤其适合把大型仓库的检查放进提交钩子、编辑器和 CI，因为 README 将速度、缓存和大仓库支持作为直接能力。

  • Ruff 使用 Rust 编写，README 声称相比 Flake8 和 Black 等工具快 10 到 100 倍。
  • 内置缓存会避免重新分析未变化文件，适合增量检查。
  • README 明确称其为 Monorepo-friendly，并支持层级化、级联式配置；命令也能递归处理当前目录及子目录。
  • 它提供 ruff-pre-commit、VS Code 及其他编辑器集成，并列出 Apache Airflow、Pandas、SciPy 等大型项目的使用案例。不过 README 没有给出这些项目的仓库规模、实际耗时或 CI 节省比例。
  • README："10-100x faster than existing linters (like Flake8) and formatters (like Black)"
  • README："Built-in caching, to avoid re-analyzing unchanged files"
  • README："Monorepo-friendly, with hierarchical and cascading configuration"
  • README：使用案例列表包含 Apache Airflow、Pandas、SciPy
uvx [email protected] check   # Lint all files in the current directory.
材料未说明：README 未提供目标代码库的文件数量、当前检查耗时或迁移后的实测性能。；README 未说明现有 CI 是否依赖 Ruff 尚未覆盖的项目专有检查。
适合 我的项目目标版本是 Python 3.15，我希望同时执行静态检查、自动修复和代码格式化；Ruff 是否能作为主要 Python 质量工具？
适合读者： 需要支持 Python 3.15、同时想用格式化和静态检查覆盖代码质量的 Python 项目维护者

适合承担主要的 Python 风格与静态检查工作，但不能单独覆盖类型检查、测试、安全扫描或业务语义分析。

  • README 明确声明兼容 Python 3.15，满足该目标版本的工具兼容性要求。
  • ruff check 用于 lint，支持自动错误修复；README 的例子是自动移除未使用导入。
  • ruff format 可递归格式化当前目录，也可针对路径或 .py 文件执行。
  • Ruff 的定位是 linter 和 formatter，而不是完整程序验证平台；README 没有声称它替代类型检查器、测试框架或安全工具，因此这些能力仍需另行确认和保留。
  • README："Python 3.15 compatibility"
  • README：`ruff check` 用于 lint
  • README：`ruff format` 用于格式化当前目录、路径或 `.py` 文件
  • 项目描述："An extremely fast Python linter and code formatter, written in Rust."
uvx [email protected] format  # Format all files in the current directory.
材料未说明：README 未说明 Python 3.15 下所有 900 多条规则的具体支持边界。；README 未说明 Ruff 与项目现有类型检查器、测试框架或安全扫描工具的集成方式。
适合 我的 Monorepo 有多个 Python 子项目，不同目录需要继承或覆盖不同规则；Ruff 的配置发现和级联机制能否满足这个约束？
适合读者： 维护包含多个 Python 子项目和不同目录规则的 Monorepo 工程师

适合，因为 Ruff 明确针对 Monorepo 提供层级化和级联式配置，但目录边界与继承结果仍需按项目结构确认。

  • README 将 Ruff 标记为“Monorepo-friendly”，并链接到配置文件发现文档。
  • pyproject.toml 是其明确支持的项目配置入口，可把规则、格式化和目标 Python 版本集中管理。
  • README 的命令支持对当前目录及所有子目录递归检查，也支持直接指定路径、通配的 .py 文件或参数文件。
  • 这能覆盖多目录执行和配置继承需求，但 README 摘录没有展示父子配置冲突时的具体优先级，也没有说明不同子项目是否必须分别运行命令。
  • README："Monorepo-friendly, with hierarchical and cascading configuration"
  • README："pyproject.toml support"
  • README："Lint all files in the current directory (and any subdirectories)"
  • README：`ruff check path/to/code/` 和 `ruff check @arguments.txt` 用法
ruff check path/to/code/
材料未说明：README 摘录未说明嵌套配置文件的精确优先级、合并规则和覆盖语法。；README 未说明 Monorepo 中跨目录共享配置与独立项目配置的推荐组织方式。
视情况 我的 Python 项目依赖特定 Flake8 第三方插件，而且 CI 必须与现有结果完全一致；我能否直接用 Ruff 替换整套检查链？
适合读者： 依赖特定 Flake8 第三方插件、并要求迁移后检查结果与原 CI 完全一致的 Python 项目维护者

视情况，因为 Ruff 覆盖了大量常见规则，但 README 的兼容性表述并不保证所有第三方插件和边界行为完全等价。

  • Ruff 原生重新实现了流行 Flake8 插件规则，并提供超过 900 项内置规则，说明常见插件迁移有较大覆盖面。
  • README 声称与 Flake8、isort 和 Black 达到 drop-in parity，但没有承诺覆盖每一个第三方插件、插件版本组合或项目自定义检查。
  • Ruff 的目标是通过单一接口整合更多功能，而不是保证旧工具每个诊断编号、默认行为和修复结果逐项相同。
  • 因此，若“完全一致”是硬约束，直接替换不适合；若插件属于已实现范围，则可以考虑迁移，但具体覆盖率需要从现有配置逐项核对。
  • README："Over 900 built-in rules, with native re-implementations of popular Flake8 plugins, like flake8-bugbear"
  • README："Drop-in parity with Flake8, isort, and Black"
  • README："Ruff aims to be orders of magnitude faster than alternative tools while integrating more functionality behind a single, common interface"
  • 项目洞察：Ruff 与 Flake8、isort、Black 在所有边界案例、插件行为和版本组合下不一定完全等价
ruff check
材料未说明：README 未列出目标项目所依赖的具体 Flake8 插件是否全部已有 Ruff 对应规则。；README 未定义“drop-in parity”覆盖的诊断编号、默认配置、修复行为和版本范围。；README 未说明如何自动比较旧工具与 Ruff 的完整 CI 输出。

✨ 核心亮点

  • README 声称比 Flake8 和 Black 快 10-100 倍
  • 内置超过 900 条规则，并支持自动修复未使用导入
  • Rust 单一工具覆盖 Flake8、Black 与 isort

🔧 工程化

  • ruff check 检查 Python 文件，ruff format 统一代码格式
  • 支持 pip、uv、pipx、Homebrew 和 Conda 安装
  • 通过 pyproject.toml 与层级配置支持 Monorepo
  • 提供 VS Code、pre-commit 和 GitHub Action 集成

⚠️ 风险

  • README 省略 Configuration 和 Rules 章节，迁移细节无法确认
  • 10-100 倍性能是 README 声称，基准环境与测试方法未说明
  • README 未说明现有 Flake8 插件的逐项兼容边界

👥 适合谁？

  • 维护 Python 项目并使用 Flake8、Black 或 isort 的团队
  • 需要 VS Code、pre-commit 或 GitHub Action 检查的开发者
  • 维护 Apache Airflow、FastAPI 或 Pandas 类大型代码库的团队