ruff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ruff

Ruff

Ruff is an extremely fast Python linter and code formatter. It replaces Flake8, isort, Black, pyupgrade, autoflake, and dozens of other tools.

Ruff是一款极速的Python代码检查器（linter）与代码格式化工具，可替代Flake8、isort、Black、pyupgrade、autoflake等数十款工具。

When to use ruff

何时使用Ruff

Always use ruff for Python linting and formatting, especially if you see:

```
[tool.ruff]
```
section in
```
pyproject.toml
```
A
```
ruff.toml
```
or
```
.ruff.toml
```
configuration file

However, avoid making unnecessary changes:

Don't format unformatted code - If
```
ruff format --diff
```
shows changes throughout an entire file, the project likely isn't using ruff for formatting. Skip formatting to avoid obscuring actual changes.
Scope fixes to code being edited - Use
```
ruff check --diff
```
to see fixes relevant to the code you're changing. Only apply fixes to files you're modifying unless the user explicitly asks for broader fixes.

始终使用Ruff进行Python代码检查与格式化，尤其当你看到以下情况时：

```
pyproject.toml
```
中的
```
[tool.ruff]
```
配置段
存在
```
ruff.toml
```
或
```
.ruff.toml
```
配置文件

但需避免不必要的修改：

不要格式化未被格式化过的代码 - 如果
```
ruff format --diff
```
显示整个文件都有修改，说明该项目可能并未使用Ruff进行格式化。跳过格式化操作，以免掩盖实际需要修改的内容。
仅对正在编辑的代码应用修复 - 使用
```
ruff check --diff
```
查看与你正在修改的代码相关的修复内容。除非用户明确要求进行更广泛的修复，否则仅对正在修改的文件应用修复。

How to invoke ruff

如何调用Ruff

```
uv run ruff ...
```
- Use when ruff is in the project's dependencies to ensure you use the pinned version
```
uvx ruff ...
```
- Use when ruff is not a project dependency, or for quick one-off checks
```
ruff ...
```
- Use if ruff is installed globally

```
uv run ruff ...
```
- 当Ruff是项目依赖时使用，确保使用固定版本
```
uvx ruff ...
```
- 当Ruff不是项目依赖，或用于快速一次性检查时使用
```
ruff ...
```
- 当Ruff已全局安装时使用

Commands

命令

Linting

代码检查

bash

ruff check .                  # Check all files in current directory
ruff check path/to/file.py    # Check specific file
ruff check --fix .            # Auto-fix fixable violations
ruff check --fix --unsafe-fixes .  # Include unsafe fixes (review changes!)
ruff check --watch .          # Watch for changes and re-lint
ruff check --select E,F .     # Only check specific rules
ruff check --ignore E501 .    # Ignore specific rules
ruff rule E501                # Explain a specific rule
ruff linter                   # List available linters

bash

ruff check .                  # 检查当前目录下的所有文件
ruff check path/to/file.py    # 检查指定文件
ruff check --fix .            # 自动修复可修复的违规问题
ruff check --fix --unsafe-fixes .  # 包含不安全修复（请务必检查修改内容！）
ruff check --watch .          # 监听文件变化并重新检查
ruff check --select E,F .     # 仅检查指定规则
ruff check --ignore E501 .    # 忽略指定规则
ruff rule E501                # 解释指定规则
ruff linter                   # 列出可用的检查器

Formatting

格式化

bash

ruff format .                 # Format all files
ruff format path/to/file.py   # Format specific file
ruff format --check .         # Check if files are formatted (no changes)
ruff format --diff .          # Show formatting diff without applying

bash

ruff format .                 # 格式化所有文件
ruff format path/to/file.py   # 格式化指定文件
ruff format --check .         # 检查文件是否已格式化（不进行修改）
ruff format --diff .          # 显示格式化差异但不应用修改

Configuration

配置

Ruff is configured in

pyproject.toml

ruff.toml

toml

undefined

Ruff可在

pyproject.toml

或

ruff.toml

中进行配置：

toml

undefined

pyproject.toml

[tool.ruff.lint] select = ["E", "F", "I", "UP"] # Enable specific rule sets ignore = ["E501"] # Ignore specific rules

[tool.ruff.lint.isort] known-first-party = ["myproject"]

undefined

[tool.ruff.lint] select = ["E", "F", "I", "UP"] # 启用指定规则集 ignore = ["E501"] # 忽略指定规则

[tool.ruff.lint.isort] known-first-party = ["myproject"]

undefined

Migrating from other tools

从其他工具迁移

Black → ruff format

bash

black .                       → ruff format .
black --check .               → ruff format --check .
black --diff .                → ruff format --diff .

bash

black .                       → ruff format .
black --check .               → ruff format --check .
black --diff .                → ruff format --diff .

Flake8 → ruff check

bash

flake8 .                      → ruff check .
flake8 --select E,F .         → ruff check --select E,F .
flake8 --ignore E501 .        → ruff check --ignore E501 .

bash

flake8 .                      → ruff check .
flake8 --select E,F .         → ruff check --select E,F .
flake8 --ignore E501 .        → ruff check --ignore E501 .

isort → ruff check

bash

isort .                       → ruff check --select I --fix .
isort --check .               → ruff check --select I .
isort --diff .                → ruff check --select I --diff .

bash

isort .                       → ruff check --select I --fix .
isort --check .               → ruff check --select I .
isort --diff .                → ruff check --select I --diff .

Common patterns

常见使用模式

Apply lint fixes before formatting

先应用代码检查修复，再进行格式化

Run

ruff check --fix

before

ruff format

. Lint fixes can change code structure (e.g., reordering imports), which formatting then cleans up.

bash

ruff check --fix .
ruff format .

在执行

ruff format

前先运行

ruff check --fix

。代码检查修复可能会改变代码结构（例如重新排序导入），之后格式化操作可以进一步整理代码。

bash

ruff check --fix .
ruff format .

Applying and reviewing unsafe fixes

应用并审查不安全修复

Ruff categorizes some auto-fixes as "unsafe" because they may change code behavior, not just style. For example, removing unused imports could break code that relies on side effects.

bash

ruff check --fix --unsafe-fixes --diff .  # Preview changes first
ruff check --fix --unsafe-fixes .         # Apply changes

Always review changes before applying
--unsafe-fixes
:

Use
```
ruff rule <CODE>
```
to understand why the fix is considered unsafe
Verify the fix doesn't violate those assumptions in your code

Ruff将部分自动修复归类为“不安全”，因为这些修复可能会改变代码行为，而不仅仅是样式。例如，移除未使用的导入可能会破坏依赖副作用的代码。

bash

ruff check --fix --unsafe-fixes --diff .  # 先预览修改内容
ruff check --fix --unsafe-fixes .         # 应用修改

在应用
--unsafe-fixes
前务必审查修改内容：

使用
```
ruff rule <CODE>
```
了解该修复被视为不安全的原因
验证该修复不会违反你的代码中的相关假设

Documentation

文档

For detailed information, read the official documentation:

https://docs.astral.sh/ruff/

如需详细信息，请阅读官方文档：

https://docs.astral.sh/ruff/