Ruff

文档 | 游乐场

一个极其快速的 Python 代码检查器和代码格式化工具，使用 Rust 编写。

从零开始对 CPython 代码库进行代码检查。

• ⚡️ 比现有检查器（如 Flake8）和格式化工具（如 Black）快 10-100 倍
• 🐍 可通过 pip 安装
• 🛠️ pyproject.toml 支持
• 🤝 Python 3.14 兼容性
• ⚖️ 与 Flake8、isort 和 Black 的即插即用等效性
• 📦 内置缓存，以避免重新分析未更改的文件
• 🔧 修复支持，用于自动错误纠正（例如，自动移除未使用的导入）
• 📏 超过 900 条内置规则，包含对流行 Flake8 插件（如 flake8-bugbear）的原生重新实现
• ⌨️ 针对 VS Code 和 更多 的第一方 编辑器集成
• 🌎 对 Monorepo 友好，支持 分层和级联配置

Ruff 旨在比替代工具快几个数量级，同时通过单一、通用的接口集成更多功能。

Ruff 可用于替代 Flake8（外加数十个插件）、 Black、isort、 pydocstyle、pyupgrade、 autoflake 等，同时执行速度比任何单个工具都快数十倍或数百倍。

Ruff 的开发极其活跃，并被用于以下主要开源项目：

• Apache Airflow
• Apache Superset
• FastAPI
• Hugging Face
• Pandas
• SciPy

……以及更多项目。

Ruff 由 Astral 支持，该公司是 uv 和 ty 的创造者。

阅读发布 文章，或 最初的项目 公告。

用户评价

Sebastián Ramírez，FastAPI 的创造者：

Ruff 的速度如此之快，以至于我有时会在代码中故意添加一个 bug，只是为了确认它确实在 运行并检查代码。

Nick Schrock，Elementl 的创始人， GraphQL 的联合创造者：

为什么 Ruff 是一个改变游戏规则的工具？主要是因为它几乎快了 1000 倍。字面意思。不是笔误。在 我们最大的模块（dagster 本身，25 万行代码）上，pylint 大约需要 2.5 分钟，在我的 M1 上并行使用 4 个核心。对 整个 代码库运行 ruff 只需 0.4 秒。

Bryan Van de Ven，Bokeh 的联合创造者， Conda 的原始作者：

在我的机器上，Ruff 比 flake8 快约 150-200 倍，扫描整个仓库只需约 0.2 秒，而不是 约 20 秒。这对本地开发来说是一个巨大的生活质量提升。它足够快，以至于我将其添加为实际的提交钩子，这太棒了。

Timothy Crosley， isort 的创建者：

我刚把我的第一个项目切换到了 Ruff。目前唯一的缺点：它太快了，我简直不敢相信 它真的在工作，直到我故意引入了一些错误。

Tim Abbott，Zulip 的首席开发者（也见此处）：

这简直快得离谱…… ruff 太棒了。

目录

更多详情，请参阅文档。

1. Getting Started
2. Configuration
3. Rules
4. Contributing
5. Support
6. Acknowledgements
7. Who's Using Ruff?
8. License

入门指南

更多详情，请参阅文档。

安装

Ruff 可在 PyPI 上以 ruff 的形式获取。

直接调用 Ruff，使用 uvx:

uvx ruff check   # Lint all files in the current directory.
uvx ruff format  # Format all files in the current directory.

或者使用 uv（推荐）、pip 或 pipx 安装 Ruff：

# With uv.
uv tool install ruff@latest  # Install Ruff globally.
uv add --dev ruff            # Or add Ruff to your project.

# With pip.
pip install ruff

# With pipx.
pipx install ruff

从版本 0.5.0 开始，Ruff 可以通过我们的独立安装程序进行安装：

# On macOS and Linux.
curl -LsSf https://astral.sh/ruff/install.sh | sh

# On Windows.
powershell -c "irm https://astral.sh/ruff/install.ps1 | iex"

# For a specific version.
curl -LsSf https://astral.sh/ruff/0.16.2/install.sh | sh
powershell -c "irm https://astral.sh/ruff/0.16.2/install.ps1 | iex"

你还可以通过 Homebrew、Conda 以及 多种其他包管理器 安装 Ruff。

用法

要将 Ruff 用作 linter，请尝试以下任一方法：

ruff check                          # Lint all files in the current directory (and any subdirectories).
ruff check path/to/code/            # Lint all files in `/path/to/code` (and any subdirectories).
ruff check path/to/code/*.py        # Lint all `.py` files in `/path/to/code`.
ruff check path/to/code/to/file.py  # Lint `file.py`.
ruff check @arguments.txt           # Lint using an input file, treating its contents as newline-delimited command-line arguments.

或者，将 Ruff 作为格式化器运行：

ruff format                          # Format all files in the current directory (and any subdirectories).
ruff format path/to/code/            # Format all files in `/path/to/code` (and any subdirectories).
ruff format path/to/code/*.py        # Format all `.py` files in `/path/to/code`.
ruff format path/to/code/to/file.py  # Format `file.py`.
ruff format @arguments.txt           # Format using an input file, treating its contents as newline-delimited command-line arguments.

Ruff 也可以用作 pre-commit 钩子，通过 ruff-pre-commit：

- repo: https://github.com/astral-sh/ruff-pre-commit
  # Ruff version.
  rev: v0.16.2
  hooks:
    # Run the linter.
    - id: ruff-check
      args: [ --fix ]
    # Run the formatter.
    - id: ruff-format

Ruff 也可以作为 VS Code 扩展 或与 其他各种编辑器 一起使用。

Ruff 也可以通过 ruff-action 作为 GitHub Action 使用：

name: Ruff
on: [ push, pull_request ]
jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v3

配置

Ruff 可以通过 pyproject.toml、ruff.toml 或 .ruff.toml 文件进行配置（参见： 配置，或 设置 以获取所有配置选项的完整列表）。

要查看已启用规则的完整列表，请参阅 默认规则。

如果未指定，Ruff 的默认配置等同于以下 ruff.toml 文件：

# Exclude a variety of commonly ignored directories.
exclude = [
    ".bzr",
    ".direnv",
    ".eggs",
    ".git",
    ".git-rewrite",
    ".hg",
    ".ipynb_checkpoints",
    ".mypy_cache",
    ".nox",
    ".pants.d",
    ".pyenv",
    ".pytest_cache",
    ".pytype",
    ".ruff_cache",
    ".svn",
    ".tox",
    ".venv",
    ".vscode",
    "__pypackages__",
    "_build",
    "buck-out",
    "build",
    "dist",
    "node_modules",
    "site-packages",
    "venv",
]

# Same as Black.
line-length = 88
indent-width = 4

# Assume Python 3.10
target-version = "py310"

[lint]
# select = [...]  # See the Default Rules page for the full listing.
ignore = []

# Allow fix for all enabled rules (when `--fix`) is provided.
fixable = ["ALL"]
unfixable = []

# Allow unused variables when underscore-prefixed.
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"

[format]
# Like Black, use double quotes for strings.
quote-style = "double"

# Like Black, indent with spaces, rather than tabs.
indent-style = "space"

# Like Black, respect magic trailing commas.
skip-magic-trailing-comma = false

# Like Black, automatically detect the appropriate line ending.
line-ending = "auto"

请注意，在 pyproject.toml 中，每个章节标题前都应加上 tool.ruff。例如，[lint] 应替换为 [tool.ruff.lint]。

某些配置选项可以通过专用的命令行参数提供，例如与规则启用和禁用、文件发现以及日志级别相关的参数：

ruff check --select F401 --select F403 --quiet

其余配置选项可以通过一个通用的 --config 参数提供：

ruff check --config "lint.per-file-ignores = {'some_file.py' = ['F841']}"

要启用最新的 lint 规则、格式化样式更改、接口更新等，请通过 在配置文件中设置 preview = true 或在命令行上传递 --preview 来启用 预览模式。预览模式启用了一组不稳定 的功能，这些功能在稳定之前可能会发生变化。

有关 Ruff 顶级命令的更多信息，请参阅 ruff help，或分别参阅 ruff help check 和 ruff help format 以了解有关 lint 和格式化命令的更多信息。

规则

Ruff 支持超过 900 条 lint 规则，其中许多规则借鉴自 Flake8、 isort、pyupgrade 等流行工具。无论规则的来源如何，Ruff 都以 Rust 作为第一方功能重新实现了每一条规则。

默认情况下，Ruff 启用 F、E、B、UP 和 RUF 类别的规则， 以及许多其他规则，但会省略与格式化程序使用重叠的任何样式规则，例如 ruff format 或 Black。

如果你刚开始使用 Ruff，默认规则集是一个很好的起点：它 无需任何配置即可捕获各种常见错误（如未使用的导入）。请参阅 Default Rules 以获取完整列表。

除了默认规则外，Ruff 重新实现了部分最流行的 Flake8 插件及相关代码 质量工具，包括：

• autoflake
• eradicate
• flake8-2020
• flake8-annotations
• flake8-async
• flake8-bandit (#1646)
• flake8-blind-except
• flake8-boolean-trap
• flake8-bugbear
• flake8-builtins
• flake8-commas
• flake8-comprehensions
• flake8-copyright
• flake8-datetimez
• flake8-debugger
• flake8-django
• flake8-docstrings
• flake8-eradicate
• flake8-errmsg
• flake8-executable
• flake8-future-annotations
• flake8-gettext
• flake8-implicit-str-concat
• flake8-import-conventions
• flake8-logging
• flake8-logging-format
• flake8-no-pep420
• flake8-pie
• flake8-print
• flake8-pyi
• flake8-pytest-style
• flake8-quotes
• flake8-raise
• flake8-return
• flake8-self
• flake8-simplify
• flake8-slots
• flake8-super
• flake8-tidy-imports
• flake8-todos
• flake8-type-checking
• flake8-use-pathlib
• flynt (#2102)
• isort
• mccabe
• pandas-vet
• pep8-naming
• pydocstyle
• pygrep-hooks
• pylint-airflow
• pyupgrade
• tryceratops
• yesqa

有关支持规则的完整列表，请参阅 Rules。

贡献

欢迎贡献，并深表感谢。要开始参与，请查看 贡献指南。

你也可以加入我们的 Discord。

支持

遇到问题？请查看 GitHub 上的现有问题， 或随时 提交新问题。

你也可以在 Discord 上寻求帮助。

致谢

Ruff 的 linter 借鉴了 Python 生态系统中许多其他工具的 API 和实现细节， 尤其是 Flake8、Pyflakes、 pycodestyle、pydocstyle、 pyupgrade 和 isort。

在某些情况下，Ruff 包含了对应工具的“直接”Rust 移植。 我们感谢这些工具的维护者所做的工作，以及他们为 Python 社区带来的所有价值。

Ruff 的 formatter 基于 Rome 的 rome_formatter 的分支构建， 并且同样借鉴了 Rome、 Prettier 和 Black 的 API 和实现细节。

Ruff 的 import resolver 基于 Pyright 中的 import 解析算法。

Ruff 还受到 Python 生态系统之外一些工具的影响，例如 Clippy 和 ESLint。

Ruff 受益于众多 贡献者。

Ruff 以 MIT 许可证发布。

谁在使用 Ruff？

Ruff 被许多主要的开源项目和公司使用，包括：

• Albumentations

• Amazon (AWS SAM)

• Anki

• Anthropic (Python SDK)

• Apache Airflow

• AstraZeneca (Magnus)

• Babel

• Benchling (Refac)

• Bokeh

• Capital One (datacompy)

• CrowdCent (NumerBlox)

• Cryptography (PyCA)

• CERN (Indico)

• DVC

• Dagger

• Dagster

• Databricks (MLflow)

• Dify

• FastAPI

• Godot

• Gradio

• Great Expectations

• HTTPX

• Hatch

• Home Assistant

• Hugging Face (Transformers, Datasets, Diffusers)

• IBM (Qiskit)

• ING Bank (popmon, probatus)

• Ibis

• ivy

• JAX

• Jupyter

• Kraken Tech

• LangChain

• Litestar

• LlamaIndex

• Matrix (Synapse)

• MegaLinter

• Meltano (Meltano CLI, Singer SDK)

• Microsoft (Semantic Kernel, ONNX Runtime, LightGBM)

• Modern Treasury (Python SDK)

• Mozilla (Firefox)

• Mypy

• Nautobot

• Netflix (Dispatch)

• Neon

• Nokia

• NoneBot

• NumPyro

• ONNX

• OpenBB

• Open Wine Components

• PDM

• PaddlePaddle

• Pandas

• Pillow

• Poetry

• Polars

• PostHog

• Prefect (Python SDK, Marvin)

• PyInstaller

• PyMC

• PyMC-Marketing

• pytest

• PyTorch

• Pydantic

• Pylint

• PyScripter

• PyVista

• Reflex

• River

• Rippling

• Robyn

• Saleor

• Scale AI (Launch SDK)

• SciPy

• Snowflake (SnowCLI)

• Sphinx

• Stable Baselines3

• Starlette

• Streamlit

• The Algorithms

• Vega-Altair

• Weblate

• WordPress (Openverse)

• ZenML

• Zulip

• build (PyPA)

• cibuildwheel (PyPA)

• delta-rs

• featuretools

• meson-python

• nox

• pip

表达你的支持

如果你正在使用 Ruff，请考虑在你的项目 README.md 中添加 Ruff 徽章：

[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

……或 README.rst：

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
    :target: https://github.com/astral-sh/ruff
    :alt: Ruff

...或者，作为 HTML：

<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff" style="max-width:100%;"></a>

许可证

本仓库采用 MIT License