Ruff

文档 | 在线试用

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

从头开始检查CPython代码库。

• ⚡️ 比现有的代码检查工具（如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正在积极开发中，并被许多主要的开源项目使用，如：

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

...以及更多项目。

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太神奇了。

目录

更多信息，请参阅文档。

1. 入门
2. 配置
3. 规则
4. 贡献
5. 支持
6. 致谢
7. 谁在使用Ruff？
8. 许可证

入门

更多信息，请参阅文档。

安装

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 插件和相关的代码质量工具，包括：

• 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

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

贡献

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

您也可以加入我们的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>

许可证

本仓库采用 MIT 许可证