Python代码检查与格式化工具Ruff

文章目录

简介
安装
初试
基础使用
配置
- 忽略错误
规则选择
修复
格式化
- 配置
编辑器
- PyCharm
- VSCode
集成
Preview
参考文献

建议与 Python包与环境管理工具uv及pyproject.toml指南配套使用

简介

Ruff 是一款 Python 代码检查与格式化工具，用 Rust 编写，速度极快

比现有的代码检查工具（如 Flake8）和格式化工具（如 Black）快 10 到 100 倍
可通过 pip 安装
支持 pyproject.toml 配置
兼容 Python 3.14
兼容 Flake8、isort 和 Black
内置缓存功能，避免对未更改的文件重新分析
自动纠正错误，如自动删除未使用的导入
超过 800 条内置规则，原生实现 Flake8 插件，如 flake8-bugbear
为 VSCode 等编辑器提供官方集成插件
支持多仓库，具有分层和级联配置功能

Ruff 在众多大型开源项目中得到广泛应用：

安装

shell 复制代码

pip install ruff

# 使用uv
uv tool install ruff

初试

calculate.py

python 复制代码

from typing import Iterable

import os


def sum_even_numbers(numbers: Iterable[int]) -> int:
    """Given an iterable of integers, return the sum of all even numbers in the iterable."""
    return sum(
        num for num in numbers
        if num % 2 == 0
    )

代码检查

shell 复制代码

ruff check

结果

复制代码

F401 [*] `os` imported but unused
 --> src\numbers\calculate.py:3:8
  |
1 | from typing import Iterable
2 |
3 | import os
  |        ^^
  |
help: Remove unused import: `os`

Found 1 error.
[*] 1 fixable with the `--fix` option.

自动修复

shell 复制代码

ruff check --fix

基础使用

代码检查

shell 复制代码

# 检查当前目录
ruff check

# 检查特定文件
ruff check path/to/file.py

# 检查并修复
ruff check --fix

代码格式化

shell 复制代码

# 格式化所有文件
ruff format

# 检查哪些文件需要格式化
ruff format --check

# 格式化特定文件
ruff format path/to/file.py

导入排序

shell 复制代码

# 检查导入排序
ruff check --select I

# 自动修复导入排序
ruff check --select I --fix

配置

pyproject.toml

toml 复制代码

[tool.ruff]
# 行长度限制
line-length = 79

[tool.ruff.lint]
#  强制添加行过长规则
extend-select = ["E501"]

代码检查

shell 复制代码

ruff check

结果

复制代码

E501 Line too long (92 > 79)
 --> src\numbers\calculate.py:6:80
  |
5 | def sum_even_numbers(numbers: Iterable[int]) -> int:
6 |     """Given an iterable of integers, return the sum of all even numbers in the iterable."""
  |                                                                                ^^^^^^^^^^^^^
7 |     return sum(
8 |         num for num in numbers
  |

Found 1 error.

Ruff 支持超过 800 条代码检查规则，分布在 50 多个内置插件中，使用哪些需要根据项目需求来定

默认情况下，Ruff 会启用 Flake8 的 F 规则以及一部分 E 规则，但会忽略格式化工具冲突的规则

如果是首次引入代码检查工具，使用默认的规则即可：它范围窄、针对性强，无需任何配置就能检测出多种常见的错误，如未使用导入语句

如果是从其他代码检查工具迁移到 Ruff，可以复用之前配置的规则

例如，应用 pyupgrade 规则：

toml 复制代码

[tool.ruff.lint]
extend-select = [
  "UP",  # pyupgrade
]

代码检查

shell 复制代码

ruff check

结果

复制代码

UP035 [*] Import from `collections.abc` instead: `Iterable`
 --> src\numbers\calculate.py:1:1
  |
1 | from typing import Iterable
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
help: Import from `collections.abc`

Found 1 error.
[*] 1 fixable with the `--fix` option.

例如，强制所有函数都有 docstrings

toml 复制代码

[tool.ruff.lint]
extend-select = [
  "UP",  # pyupgrade
  "D",   # pydocstyle
]

[tool.ruff.lint.pydocstyle]
convention = "google"

结果

复制代码

D104 Missing docstring in public package
--> src\numbers\__init__.py:1:1

D103 Missing docstring in public function
 --> src\numbers\__init__.py:1:5
  |
1 | def hello() -> str:
  |     ^^^^^
2 |     return "Hello from numbers!"

忽略错误

添加 # noqa

python 复制代码

from typing import Iterable  # noqa

或

from typing import Iterable  # noqa: UP035

或在文件头部添加，忽略整个文件

# ruff: noqa: UP035

规则选择

规则集通过 lint.select、lint.extend-select lint.ignore 来控制

toml 复制代码

[tool.ruff.lint]
select = [
    # pycodestyle
    "E",
    # Pyflakes
    "F",
    # pyupgrade
    "UP",
    # flake8-bugbear
    "B",
    # flake8-simplify
    "SIM",
    # isort
    "I",
]

toml 复制代码

[tool.ruff.lint]
select = ["E", "F"]
ignore = ["F401"]

修复

修复分为"安全"和"不安全"两类

不安全的修复可能会改变运行时、删除注释等

限制修复的范围，可使用 lint.fixable、lint.extend-fixable、lint.unfixable

格式化

Ruff 格式化工具的设计目标是快快快，因此格式化直接兼容了 Black

python 复制代码

def _make_ssl_transport(
    rawsock, protocol, sslcontext, waiter=None,
    *, server_side=False, server_hostname=None,
    extra=None, server=None,
    ssl_handshake_timeout=None,
    call_connection_made=True):
    '''Make an SSL transport.'''
    if waiter is None:
      waiter = Future(loop=loop)

    if extra is None:
      extra = {}

    ...

格式化后

python 复制代码

def _make_ssl_transport(
    rawsock,
    protocol,
    sslcontext,
    waiter=None,
    *,
    server_side=False,
    server_hostname=None,
    extra=None,
    server=None,
    ssl_handshake_timeout=None,
    call_connection_made=True,
):
    """Make an SSL transport."""
    if waiter is None:
        waiter = Future(loop=loop)

    if extra is None:
        extra = {}

    ...

配置

单引号、每行宽度、制表符缩进、文档字符串及其长度

toml 复制代码

[tool.ruff]
line-length = 100

[tool.ruff.format]
quote-style = "single"
indent-style = "tab"
docstring-code-format = true
docstring-code-line-length = 20

编辑器

PyCharm

PyCharm 2025.3 直接支持 Ruff，其他版本可以安装插件

File → Settings → Python → Tools → Ruff

PyCharm Ruff 官方文档

VSCode

集成

GitHub Actions

GitLab CI/CD

pre-commit

Preview

Preview 是 Ruff 中即将成为稳定版但还在测试阶段的功能。这些功能已经基本稳定，但可能还有细微调整，用于收集用户反馈

toml 复制代码

[tool.ruff]
preview = true

参考文献

Ruff