ruff-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ruff Professional Development

Ruff 专业开发指南

Version: 0.14.10 (Documentation generated December 2025)

版本： 0.14.10（文档生成于2025年12月）

Overview

概述

Ruff is an extremely fast Python linter and formatter written in Rust. It combines the functionality of multiple Python tools (Flake8, isort, Black, pyupgrade, and more) into a single high-performance tool.

This skill provides comprehensive guidance for:

Configuring and integrating Ruff into Python projects
Understanding and fixing lint rule violations
Formatting Python code with Ruff's formatter
Setting up editor integrations
Migrating from other Python tooling

Ruff是一款用Rust编写的极速Python代码检查器（linter）和格式化工具。它将多款Python工具（Flake8、isort、Black、pyupgrade等）的功能整合到一个高性能工具中。

本指南提供以下方面的全面指导：

在Python项目中配置和集成Ruff
理解并修复代码检查规则违规问题
使用Ruff的格式化工具格式化Python代码
配置编辑器集成
从其他Python工具迁移至Ruff

Quick Start

快速开始

Installation

安装

See

references/installation.md

for complete installation instructions across all platforms and package managers.

查看

references/installation.md

获取全平台及各包管理器的完整安装说明。

Basic Usage

基础用法

Linting:

bash

ruff check .                    # Lint all files
ruff check path/to/file.py      # Lint specific file
ruff check --fix .              # Auto-fix violations

Formatting:

bash

ruff format .                   # Format all files
ruff format path/to/file.py     # Format specific file
ruff format --check .           # Check formatting without changes

Configuration:

toml

undefined

代码检查：

bash

ruff check .                    # 检查所有文件
ruff check path/to/file.py      # 检查指定文件
ruff check --fix .              # 自动修复违规问题

代码格式化：

bash

ruff format .                   # 格式化所有文件
ruff format path/to/file.py     # 格式化指定文件
ruff format --check .           # 检查格式但不修改文件

配置：

toml

undefined

pyproject.toml or ruff.toml

pyproject.toml 或 ruff.toml

[tool.ruff] line-length = 88 target-version = "py311"

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


See `references/configuration.md` for comprehensive configuration options.

[tool.ruff] line-length = 88 target-version = "py311"

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


查看`references/configuration.md`获取完整的配置选项。

Core Workflows

核心工作流

1. Integrating Ruff into a Project

1. 将Ruff集成到项目中

Steps:

Install Ruff (see
```
references/installation.md
```
)
Create initial configuration (see
```
references/configuration.md
```
)
Run initial check:
```
ruff check .
```
Review and configure rules (see
```
references/settings.md
```
)
Set up pre-commit hooks or CI integration (see
```
references/integrations.md
```
)

步骤：

安装Ruff（查看
```
references/installation.md
```
）
创建初始配置（查看
```
references/configuration.md
```
）
运行初始检查：
```
ruff check .
```
查看并配置规则（查看
```
references/settings.md
```
）
设置pre-commit钩子或CI集成（查看
```
references/integrations.md
```
）

2. Fixing Lint Violations

2. 修复代码检查违规问题

Process:

Run
```
ruff check .
```
to identify violations
For specific rule violations, reference
```
references/rules/<rule-name>.md
```
Apply automatic fixes:
```
ruff check --fix .
```
Manual fixes for remaining violations using rule documentation

Finding Rule Documentation:

All 937 rules are in
```
references/rules/
```
Rules are named by their description (e.g.,
```
unused-import.md
```
,
```
line-too-long.md
```
)
See
```
references/rules/rules.md
```
for complete rule index

流程：

运行
```
ruff check .
```
识别违规问题
针对特定规则违规，参考
```
references/rules/<rule-name>.md
```
应用自动修复：
```
ruff check --fix .
```
结合规则文档手动修复剩余违规问题

查找规则文档：

全部937条规则位于
```
references/rules/
```
目录下
规则按描述命名（例如
```
unused-import.md
```
、
```
line-too-long.md
```
）
查看
```
references/rules/rules.md
```
获取完整规则索引

3. Code Formatting

3. 代码格式化

Workflow:

Review formatter overview:
```
references/formatter/overview.md
```
Configure formatter settings in
```
pyproject.toml
```
Run formatter:
```
ruff format .
```
For Black compatibility: see
```
references/formatter/black.md
```

工作流：

查看格式化工具概述：
```
references/formatter/overview.md
```
在
```
pyproject.toml
```
中配置格式化工具设置
运行格式化工具：
```
ruff format .
```
关于Black兼容性：查看
```
references/formatter/black.md
```

4. Editor Integration

4. 编辑器集成

Setup:

Review
```
references/editors/overview.md
```
for editor support
Follow setup instructions:
```
references/editors/setup.md
```
Configure editor settings:
```
references/editors/settings.md
```
Explore editor features:
```
references/editors/features.md
```

设置步骤：

查看
```
references/editors/overview.md
```
了解编辑器支持情况
按照
```
references/editors/setup.md
```
的说明进行设置
配置编辑器设置：
```
references/editors/settings.md
```
探索编辑器功能：
```
references/editors/features.md
```

5. Migrating from Other Tools

5. 从其他工具迁移

Migration paths:

From Black: See
```
references/formatter/black.md
```
From Flake8/isort/pyupgrade: See
```
references/configuration.md
```
for rule equivalents
General migration: See
```
references/tutorial.md
```
for migration guidance

迁移路径：

从Black迁移： 查看
```
references/formatter/black.md
```
从Flake8/isort/pyupgrade迁移： 查看
```
references/configuration.md
```
获取等效规则
通用迁移： 查看
```
references/tutorial.md
```
获取迁移指导

Documentation Organization

文档结构

This skill includes comprehensive reference documentation organized for efficient access:

Navigation Guide:

references/INDEX.md

- Complete index of all documentation with use-case based navigation

Core Documentation:

```
configuration.md
```
- Complete configuration reference
```
settings.md
```
- All available settings and options
```
linter.md
```
- Linter functionality and configuration
```
tutorial.md
```
- Comprehensive getting started guide

Formatter:

```
formatter/overview.md
```
- Formatter basics
```
formatter/black.md
```
- Black compatibility

Rules (937 total):

```
rules/rules.md
```
- Rules overview and index
```
rules/<rule-name>.md
```
- Individual rule documentation

Editor Integration:

```
editors/overview.md
```
- Editor support overview
```
editors/setup.md
```
- Installation instructions
```
editors/features.md
```
- Available features
```
editors/settings.md
```
- Configuration options

Other Resources:

```
installation.md
```
- Installation guide
```
integrations.md
```
- CI/CD and tool integrations
```
versioning.md
```
- Versioning and compatibility
```
preview.md
```
- Preview features
```
faq.md
```
- Frequently asked questions
```
contributing.md
```
- Contributing to Ruff

本指南包含组织有序的全面参考文档，便于快速访问：

导航指南：

references/INDEX.md

- 完整的文档索引，基于使用场景提供导航

核心文档：

```
configuration.md
```
- 完整配置参考
```
settings.md
```
- 所有可用设置和选项
```
linter.md
```
- 代码检查器功能及配置
```
tutorial.md
```
- 全面的入门指南

格式化工具：

```
formatter/overview.md
```
- 格式化工具基础
```
formatter/black.md
```
- Black兼容性

规则（共937条）：

```
rules/rules.md
```
- 规则概述及索引
```
rules/<rule-name>.md
```
- 单个规则文档

编辑器集成：

```
editors/overview.md
```
- 编辑器支持概述
```
editors/setup.md
```
- 安装说明
```
editors/features.md
```
- 可用功能
```
editors/settings.md
```
- 配置选项

其他资源：

```
installation.md
```
- 安装指南
```
integrations.md
```
- CI/CD及工具集成
```
versioning.md
```
- 版本控制及兼容性
```
preview.md
```
- 预览功能
```
faq.md
```
- 常见问题
```
contributing.md
```
- 贡献至Ruff

Finding Specific Information

查找特定信息

For configuration questions:

Start with
```
references/settings.md
```
for all available options
Review
```
references/configuration.md
```
for configuration patterns

Check

references/linter.md

references/formatter/overview.md

for component-specific settings

For rule violations:

Note the rule code/name from error message
Find corresponding file in
```
references/rules/
```
Rules are alphabetically named (e.g., E501 →
```
line-too-long.md
```
)

For editor setup:

Check
```
references/editors/overview.md
```
for supported editors
Follow
```
references/editors/setup.md
```
for your editor
Configure with
```
references/editors/settings.md
```

For tool migration:

Review
```
references/tutorial.md
```
for general guidance
See
```
references/formatter/black.md
```
for Black-specific migration
Check
```
references/configuration.md
```
for rule mapping from other linters

配置相关问题：

首先查看
```
references/settings.md
```
获取所有可用选项
查看
```
references/configuration.md
```
了解配置模式

查看

references/linter.md

或

references/formatter/overview.md

获取组件特定设置

规则违规相关问题：

从错误信息中记录规则代码/名称
在
```
references/rules/
```
目录下找到对应文件
规则按字母顺序命名（例如E501 →
```
line-too-long.md
```
）

编辑器设置相关问题：

查看
```
references/editors/overview.md
```
了解支持的编辑器
按照
```
references/editors/setup.md
```
针对你的编辑器进行设置
参考
```
references/editors/settings.md
```
进行配置

工具迁移相关问题：

查看
```
references/tutorial.md
```
获取通用指导
查看
```
references/formatter/black.md
```
获取Black特定迁移指导
查看
```
references/configuration.md
```
获取与其他代码检查器的规则映射

Included Scripts

包含的脚本

This skill includes Python scripts for updating documentation (located in

scripts/

scrape_ruff_docs.py - Scrape a single Ruff documentation page
discover_ruff_docs.py - Discover all Ruff documentation URLs
bulk_scrape_ruff.py - Bulk scrape all Ruff documentation

These scripts use cloudscraper, BeautifulSoup, and markdownify to fetch and convert Ruff documentation.

本指南包含用于更新文档的Python脚本（位于

scripts/

目录下）：

scrape_ruff_docs.py - 抓取单个Ruff文档页面
discover_ruff_docs.py - 发现所有Ruff文档URL
bulk_scrape_ruff.py - 批量抓取所有Ruff文档

这些脚本使用cloudscraper、BeautifulSoup和markdownify来获取并转换Ruff文档。

Best Practices

最佳实践

When configuring Ruff:

Start with defaults and incrementally add rules
Use
```
select
```
to enable rule categories,
```
ignore
```
for exceptions
Test configuration changes incrementally
Document reasoning for ignored rules in comments

When fixing violations:

Review auto-fixes before committing
Understand the rule before ignoring it
Use inline ignores (
```
# noqa
```
) sparingly
Consider if the rule should be disabled project-wide

When formatting:

Run formatter before linter to avoid conflicts
Configure line length consistently across tools
Use
```
--check
```
in CI to verify formatting
Format entire codebase at once when first adopting

When integrating:

Set up editor integration for immediate feedback
Add pre-commit hooks for team consistency
Include in CI pipeline with appropriate settings
Document Ruff configuration in project README

配置Ruff时：

从默认设置开始，逐步添加规则
使用
```
select
```
启用规则类别，
```
ignore
```
处理例外情况
逐步测试配置变更
在注释中记录忽略规则的原因

修复违规问题时：

提交前查看自动修复内容
忽略规则前先理解规则含义
谨慎使用行内忽略（
```
# noqa
```
）
考虑是否应在项目范围内禁用该规则

格式化代码时：

先运行格式化工具再运行代码检查器，避免冲突
在所有工具中统一配置行长度
在CI中使用
```
--check
```
验证格式
首次使用时一次性格式化整个代码库

集成Ruff时：

设置编辑器集成以获取即时反馈
添加pre-commit钩子确保团队一致性
在CI流水线中配置合适的设置
在项目README中记录Ruff配置

Advanced Usage

高级用法

Performance optimization:

Use
```
--cache-dir
```
for faster repeated runs
Configure file exclusions to skip irrelevant paths
Leverage parallel execution (default behavior)

Preview features:

See
```
references/preview.md
```
for experimental features
Enable with
```
preview = true
```
in configuration
Test preview rules before enabling in production

Custom rule selection:

Combine rule categories:
```
select = ["E", "F", "I", "N"]
```
Use per-file ignores for specific patterns
Configure different rules for different directories

性能优化：

使用
```
--cache-dir
```
加快重复运行速度
配置文件排除规则，跳过无关路径
利用并行执行（默认行为）

预览功能：

查看
```
references/preview.md
```
了解实验性功能
在配置中设置
```
preview = true
```
启用
在生产环境启用前测试预览规则

自定义规则选择：

组合规则类别：
```
select = ["E", "F", "I", "N"]
```
针对特定模式使用按文件忽略规则
为不同目录配置不同规则

Documentation Coverage

文档覆盖范围

This skill provides complete coverage of Ruff v0.14.10:

937 individual rule documentation files
Full configuration and settings reference
Complete editor integration guides
Formatter documentation including Black compatibility
Installation, integration, and migration guides
FAQ and troubleshooting resources

All documentation is current as of December 2025 and reflects the latest stable release (0.14.10).

本指南完整覆盖Ruff v0.14.10：

937个单独的规则文档文件
完整的配置和设置参考
完整的编辑器集成指南
包含Black兼容性的格式化工具文档
安装、集成和迁移指南
FAQ及故障排除资源

所有文档截至2025年12月，反映最新稳定版本（0.14.10）。