Ruff

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

<p align="center"> <picture align="center"> <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/1309177/232603514-c95e9b0f-6b31-43de-9a80-9e844173fd6a.svg"> <source media="(prefers-color-scheme: light)" srcset="https://yellow-cdn.veclightyear.com/835a84d5/a5f5011f-0d1c-46ae-94d6-43b15a571aaf.svg"> <img alt="显示基准测试结果的条形图。" src="https://yellow-cdn.veclightyear.com/835a84d5/a5f5011f-0d1c-46ae-94d6-43b15a571aaf.svg"> </picture> </p> <p align="center"> <i>从头开始检查CPython代码库。</i> </p>

⚡️ 比现有的代码检查工具（如Flake8）和格式化工具（如Black）快10-100倍
🐍 可通过pip安装
🛠️ 支持pyproject.toml
🤝 兼容Python 3.13
⚖️ 可直接替代Flake8、isort和Black
📦 内置缓存功能，避免重复分析未更改的文件
🔧 支持自动修复，可自动纠正错误（例如，自动移除未使用的导入）
📏 内置超过800条规则，包括流行的Flake8插件（如flake8-bugbear）的原生重新实现
⌨️ 官方编辑器集成，支持VS Code和其他编辑器
🌎 适用于单体仓库，支持分层和级联配置

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

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

Ruff正在积极开发中，并被许多主要的开源项目使用，如：

...以及更多项目。

Ruff由Astral支持。阅读发布公告或原始的项目公告。

用户评价

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

Ruff太快了，有时我会故意在代码中添加一个错误，只是为了确认它确实在运行并检查代码。

Nick Schrock，Elementl的创始人，GraphQL的共同创建者：

为什么Ruff是一个游戏改变者？主要是因为它快了近1000倍。真的。不是笑话。在我们最大的模块（dagster本身，25万行代码）上，pylint在我的M1上使用4个核心并行处理需要大约2.5分钟。而对我们整个代码库运行ruff只需要0.4秒。

Bryan Van de Ven，Bokeh的共同创建者，Conda的原作者：

在我的机器上，Ruff比flake8快约150-200倍，扫描整个仓库只需约0.2秒，而不是约20秒。这极大地改善了本地开发的体验。它速度快到我将其添加为实际的提交钩子，这太棒了。

Timothy Crosley，isort的创建者：

刚刚将我的第一个项目切换到Ruff。到目前为止只有一个缺点：它太快了，以至于我不相信它在工作，直到我故意引入了一些错误。

Tim Abbott，Zulip的首席开发者：

这简直是快得离谱... ruff太神奇了。

入门

更多信息，请参阅文档。

安装

Ruff在PyPI上以ruff的名称提供：

# 使用pip安装。
pip install ruff
# 使用 pipx
pipx install ruff

从 0.5.0 版本开始，可以使用我们的独立安装程序安装 Ruff：

# 在 macOS 和 Linux 上
curl -LsSf https://astral.sh/ruff/install.sh | sh

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

# 安装特定版本
curl -LsSf https://astral.sh/ruff/0.6.1/install.sh | sh
powershell -c "irm https://astral.sh/ruff/0.6.1/install.ps1 | iex"

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

使用方法

要将 Ruff 作为代码检查工具运行，可以尝试以下任何命令：

ruff check                          # 检查当前目录（及其所有子目录）中的所有文件
ruff check path/to/code/            # 检查 `/path/to/code`（及其所有子目录）中的所有文件
ruff check path/to/code/*.py        # 检查 `/path/to/code` 中的所有 `.py` 文件
ruff check path/to/code/to/file.py  # 检查 `file.py`
ruff check @arguments.txt           # 使用输入文件进行检查，将其内容视为换行符分隔的命令行参数

或者，要将 Ruff 作为格式化工具运行：

ruff format                          # 格式化当前目录（及其所有子目录）中的所有文件
ruff format path/to/code/            # 格式化 `/path/to/code`（及其所有子目录）中的所有文件
ruff format path/to/code/*.py        # 格式化 `/path/to/code` 中的所有 `.py` 文件
ruff format path/to/code/to/file.py  # 格式化 `file.py`
ruff format @arguments.txt           # 使用输入文件进行格式化，将其内容视为换行符分隔的命令行参数

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

- repo: https://github.com/astral-sh/ruff-pre-commit
  # Ruff 版本
  rev: v0.6.1
  hooks:
    # 运行代码检查器
    - id: ruff
      args: [ --fix ]
    # 运行格式化器
    - 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: chartboost/ruff-action@v1

配置

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

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

# 排除各种常见的忽略目录
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",
]

# 与 Black 相同
line-length = 88
indent-width = 4

# 假设 Python 3.8
target-version = "py38"

[lint]
# 默认启用 Pyflakes (`F`) 和 pycodestyle (`E`) 的一部分规则
select = ["E4", "E7", "E9", "F"]
ignore = []

# 当提供 `--fix` 时，允许修复所有启用的规则
fixable = ["ALL"]
unfixable = []

# 允许以下划线开头的未使用变量
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"

[format]
# 与 Black 一样，使用双引号作为字符串
quote-style = "double"

# 与 Black 一样，使用空格而不是制表符进行缩进
indent-style = "space"

# 与 Black 一样，保留魔术尾随逗号
skip-magic-trailing-comma = false

# 与 Black 一样，自动检测适当的行尾
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']}"

要选择使用最新的代码检查规则、格式化器样式更改、接口更新等，可以通过在配置文件中设置 preview = true 或在命令行中传递 --preview 来启用预览模式。预览模式启用了一系列不稳定的功能，这些功能可能会在稳定之前发生变化。

使用 ruff help 可以了解更多关于 Ruff 的顶级命令，或使用 ruff help check 和 ruff help format 分别了解更多关于代码检查和格式化命令。

规则

Ruff 支持超过 800 条代码检查规则，其中许多规则的灵感来自流行的工具，如 Flake8、isort、pyupgrade 等。无论规则的来源如何，Ruff 都将每条规则作为一个一等公民在 Rust 中重新实现。

默认情况下，Ruff 启用了 Flake8 的 F 规则，以及 E 规则的一部分，省略了任何与使用格式化器（如 ruff format 或 Black）重叠的样式规则。

如果你刚开始使用 Ruff，默认规则集是一个很好的起点：它无需任何配置就能捕获各种常见错误（如未使用的导入）。

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

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

贡献

我们欢迎并非常感谢您的贡献。要开始贡献，请查看贡献指南。

您也可以加入我们的Discord。

支持

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

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

致谢

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

在某些情况下，Ruff包含了相应工具的"直接"Rust移植版本。我们感谢这些工具的维护者们的工作，以及他们为Python社区提供的所有价值。

Ruff的格式化器基于Rome的rome_formatter的一个分支构建，同样借鉴了Rome、Prettier和Black的API和实现细节。

Ruff的导入解析器基于Pyright的导入解析算法。

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

Ruff得益于大量贡献者的支持。

Ruff采用MIT许可证发布。

谁在使用Ruff？

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

Albumentations
亚马逊 (AWS SAM)
Anthropic (Python SDK)
Apache Airflow
阿斯利康 (Magnus)
Babel
Benchling (Refac)
Bokeh
Cryptography (PyCA)
欧洲核子研究组织 (Indico)
DVC
Dagger
Dagster
Databricks (MLflow)
Dify
FastAPI
Godot
Gradio
Great Expectations
HTTPX
Hatch
Home Assistant
Hugging Face (Transformers, Datasets, Diffusers)
IBM (Qiskit)
荷兰国际集团 (popmon, probatus)
Ibis
ivy
Jupyter
Kraken Tech
LangChain
Litestar
LlamaIndex
Matrix (Synapse)
MegaLinter
Meltano (Meltano CLI, Singer SDK)
微软 (Semantic Kernel, ONNX Runtime, LightGBM)
Modern Treasury (Python SDK)
Mozilla (Firefox)
Mypy
Nautobot
Netflix (Dispatch)
Neon
诺基亚
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
PyVista
Reflex
River
Rippling
Robyn
Saleor
Scale AI (Launch SDK)
SciPy
Snowflake (SnowCLI)
Sphinx
Stable Baselines3
Starlette
Streamlit
The Algorithms
Vega-Altair
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>