Ruff 是一个用 Rust 编写的极其快速的 Python linter 和代码格式化工具。它的目标是成为现有 Python 工具（如 Flake8、isort、pydocstyle、pyupgrade、autoflake 等）的替代品，并将它们的功能整合到一个高效的工具中。

Ruff 的主要优点：

  • 速度极快：比现有的 linter（如 Flake8 + 插件）快 10-100 倍。
  • 单一工具：集成了 linting、格式化、导入排序、现代化语法等多项功能。
  • 兼容性：支持 pyproject.toml 配置，并能识别 Flake8 的配置。
  • 自动修复：支持对大量 linting 规则进行自动修复。
  • 内置缓存：避免对未更改的文件重复分析。
  • 活跃开发：项目持续更新，不断添加新规则和功能。

1. 安装 Ruff

推荐使用 pip 来安装 Ruff：

1
pip install ruff

或者，如果你使用 pipx（推荐用于安装命令行工具）：

1
pipx install ruff

你也可以通过其他包管理器（如 Conda、Homebrew）安装，具体请参考 Ruff 官方文档。

2. 基本用法

  • 检查代码（Linting）

在你的项目根目录下运行：

1
ruff check .

这会检查当前目录及其子目录下的所有 Python 文件。Ruff 会输出发现的问题，包括文件路径、行号、列号、规则代码和问题描述。

例如：

1
2
3
4
src/my_module.py:5:1: F841 Local variable `x` is assigned to but never used
src/my_module.py:10:80: E501 Line too long (88 > 79 characters)
Found 2 errors.
[*] 1 potentially fixable with the --fix option.

  • 自动修复

Ruff 可以自动修复许多检测到的问题。使用 --fix 标志：

1
ruff check . --fix

Ruff 会修改文件以修复可修复的问题。对于无法自动修复的问题，它仍会显示出来。

  • 格式化代码（Formatting）

Ruff 包含一个与 Black 兼容的代码格式化工具。运行：

1
ruff format .

这会根据配置的样式格式化项目中的 Python 文件。

  • 检查并格式化

你可以一次性运行检查和格式化：

1
ruff .

这等同于先运行 ruff format . 再运行 ruff check . --fix。

  • 查看可用规则
1
ruff rule --all
  • 解释特定规则
1
ruff rule F841

这会显示规则 F841 (Unused variable) 的详细解释。

3. 配置 Ruff

Ruff 主要通过项目根目录下的 pyproject.toml 文件或独立的 ruff.toml 文件进行配置。推荐使用 pyproject.toml，因为它也是许多其他 Python 工具（如 Poetry, Black, Pytest）的标准配置文件。

在 pyproject.toml 中，Ruff 的配置位于 [tool.ruff] 部分。

**基本配置示例 (pyproject.toml)**：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
[tool.ruff]
# 设置目标 Python 版本 (例如 "py310" 代表 Python 3.10)
# 这会影响一些代码升级和语法检查规则
target-version = "py310"

# 选择要启用的规则代码或前缀
# F: Pyflakes, E/W: pycodestyle, I: isort, U: pyupgrade, B: flake8-bugbear 等
# 默认启用 F, E, W
select = ["E", "F", "W", "I", "U", "B"]

# 忽略特定的规则
ignore = ["E501"] # 例如, 忽略行过长错误

# 指定要排除检查的文件或目录模式
exclude = [
    ".bzr",
    ".direnv",
    ".eggs",
    ".git",
    ".hg",
    ".mypy_cache",
    ".nox",
    ".pants.d",
    ".pytype",
    ".ruff_cache",
    ".svn",
    ".tox",
    ".venv",
    "__pypackages__",
    "_build",
    "buck-out",
    "build",
    "dist",
    "node_modules",
    "venv",
    "migrations/", # 忽略 Django migrations 目录
]

# 每行的最大长度 (用于 E501 和格式化)
line-length = 88

# 仅启用可自动修复的规则子集进行修复
# fixable = ["A", "B"]

# 从自动修复中排除特定规则
# unfixable = ["B"]

# [tool.ruff.lint] # (可选) Linting 相关的特定配置可以放在这里
# select = ["E", "F"]

# [tool.ruff.format] # (可选) Formatter 相关的特定配置可以放在这里
# quote-style = "double" # 使用双引号而非单引号

# 特定插件的配置 (例如 isort)
[tool.ruff.lint.isort]
known-first-party = ["my_package"] # 将 'my_package' 视为第一方库
# required-imports = ["from __future__ import annotations"] # 强制添加某个导入

# pyupgrade 配置
[tool.ruff.lint.pyupgrade]
# 保留 Python 3.9 以下版本的类型注解 (如果 target-version < "py310")
keep-runtime-typing = true

关键配置选项说明:

  • target-version: 非常重要，确保 Ruff 根据你项目使用的 Python 版本应用正确的规则。
  • select: 启用规则集合。你可以使用前缀（如 F 代表 Pyflakes 的所有规则）或具体代码（如 F841）。查看 Ruff 文档获取完整的规则列表。
  • ignore: 禁用特定的规则。
  • exclude: 排除不需要检查或格式化的文件/目录。默认已包含常见的虚拟环境、版本控制和缓存目录。
  • line-length: 设置代码行的最大长度，影响 E501 规则和 ruff format。
  • fixable/unfixable: 更精细地控制哪些规则参与自动修复。
  • 插件配置 ([tool.ruff.lint.<plugin_name>])：为特定的规则集（如 isort, pydocstyle）提供更详细的配置。

4. 常用规则和插件

Ruff 内置支持并重新实现了许多流行的 Flake8 插件和独立工具的规则，包括：

  • Pyflakes (F): 检测基本错误，如未使用的导入、未定义的变量。
  • pycodestyle (E, W): 检查代码风格是否符合 PEP 8 指南（缩进、空格、命名等）。
  • isort (I): 对导入进行排序和分组。
  • pyupgrade (U): 升级到更现代的 Python 语法。
  • flake8-bugbear (B): 检测可能的逻辑错误和可疑代码。
  • flake8-comprehensions (C4): 鼓励使用更简洁的推导式。
  • flake8-simplify (SIM): 简化复杂的代码结构。
  • pydocstyle (D): 检查文档字符串（docstrings）的风格。
  • … 等等，支持的规则集在不断增加。

示例：Ruff 检测和修复

  • 未使用的导入 (F401)

    1
    2
    import os # Ruff: F401 `os` imported but unused
    print("Hello")

    ruff check . --fix 会自动删除 import os 这一行。

  • 导入排序 (I)

    1
    2
    import sys
    import os # Ruff: I001 Import block is un-sorted or un-formatted

    ruff check . --fix 或 ruff format . 会将其重新排序为：

    1
    2
    import os
    import sys

  • 现代语法 (U)

    1
    2
    # 如果 target-version >= "py36"
    my_string = "Value: %s" % value # Ruff: UP031 Use format specifiers instead of %-style formatting

    ruff check . --fix 会将其改为：

    1
    my_string = f"Value: {value}"

5. 集成

  • 编辑器集成

    • VS Code: 安装官方的 Ruff VS Code 插件。它可以在你编写代码时实时显示 linting 问题，并提供格式化和快速修复功能。通常需要在 VS Code 的设置 (settings.json) 中启用 Ruff 作为格式化工具和 linter。
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      {
        "[python]": {
          "editor.defaultFormatter": "charliermarsh.ruff",
          "editor.formatOnSave": true, // 可选：保存时自动格式化
          "editor.codeActionsOnSave": {
            "source.fixAll": "explicit", // 可选：保存时运行 Ruff 的自动修复 (可以设为 true 自动修复)
            "source.organizeImports": "explicit" // 可选: 保存时自动整理 import
          }
        },
        "ruff.enable": true,
        // "ruff.fixAll": true, // 如果希望保存时总是执行 --fix
        // "ruff.organizeImports": true // 如果希望保存时总是整理 imports
      }
    • PyCharm/IntelliJ: Ruff 可以作为 外部工具 集成。或者使用 File Watchers 插件在文件保存时自动运行 Ruff。社区也有一些 Ruff 插件可用。

  • 预提交钩子 (Pre-commit Hooks)
    使用 pre-commit 可以在提交代码前自动运行 Ruff。在你的 .pre-commit-config.yaml 文件中添加：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    repos:
    -   repo: https://github.com/astral-sh/ruff-pre-commit
        # 根据需要选择 Ruff 的版本
        rev: v0.4.1 # 使用最新的稳定版 tag
        hooks:
            # 同时运行 linter 和 formatter
            - id: ruff
              args: [--fix] # 可选: 启用自动修复
            # 或者, 分开运行 formatter 和 linter
            # - id: ruff-format
            # - id: ruff
            #   args: [--fix]

    然后运行 pre-commit install 来安装钩子。

  • CI/CD (例如 GitHub Actions)
    在你的 CI 工作流程中添加一个步骤来运行 Ruff，确保合并到主分支的代码是符合规范的。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    name: Ruff Check

    on: [push, pull_request]

    jobs:
      ruff:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - name: Set up Python
            uses: actions/setup-python@v5
            with:
              python-version: '3.10' # 选择你的项目 Python 版本
          - name: Install Ruff
            run: pip install ruff
          - name: Run Ruff Linter
            run: ruff check .
          - name: Run Ruff Formatter Check (Optional)
            run: ruff format . --check # --check 只检查不修改，CI 中常用

6. 总结

Ruff 是一个强大、快速且易于使用的 Python 工具，可以显著提高代码质量和开发效率。通过整合多种检查和格式化功能，它可以简化你的开发工作流和 CI/CD 配置。强烈建议尝试将其集成到你的 Python 项目中。

希望这个教程对你有所帮助！如果你有任何具体的问题，随时可以提问。