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代码检查器和代码格式化工具。它可以替代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是项目依赖项时使用此命令，以确保你使用的是固定版本的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

从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

从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

从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 check --fix

，再运行

ruff format

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

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/