Ruff 是一款基于 Rust 编写的高性能 Python 代码检查器和格式化工具，旨在替代 Flake8、Black、isort 等工具，提供显著的性能提升。 Ruff 的核心特性、多种安装方式（pip、uv、brew 等）、Linter 和 Formatter 的基本用法及配置方法。内容涵盖规则设置、自动修复、VSCode 插件集成、预提交钩子及 CI/CD 流程。通过统一工具链，Ruff 能大幅优化 Python 项目的开发体验和代码质量。
Ruff 是一款用 Rust 编写的高性能 Python 代码检查器（linter）和格式化工具（formatter），由 Astral 公司开发。它的目标是作为 Flake8、Black、isort 等多个 Python 工具的统一替代品，提供 10-100 倍的性能提升。
pip install ruff 即可安装Ruff 的性能提升带来了显著的开发体验改善。以下是来自实际项目的反馈：
'Ruff 快到有时候我故意在代码里加个 bug 来确认它真的在运行检查' —— FastAPI 创始人 Sebastián Ramírez
'在我 25 万行的 dagster 模块上，pylint 需要 2.5 分钟，而 Ruff 检查整个代码库只需 0.4 秒' —— Elementl 创始人 Nick Schrock
# 使用 uv（推荐）
uv tool install ruff@latest # 全局安装
uv add --dev ruff # 添加到项目开发依赖
# 使用 pip
pip install ruff
# 使用 pipx
pipx install ruff
# 使用 uvx（无需安装）
uvx ruff check # 直接运行检查
uvx ruff format # 直接运行格式化
# macOS/Linux 独立安装脚本
curl -LsSf https://astral.sh/ruff/install.sh | sh
# Windows 独立安装脚本
powershell -c "irm https://astral.sh/ruff/install.ps1 | iex"
# Homebrew (macOS/Linux)
brew install ruff
# Conda
conda install -c conda-forge ruff
# Docker
docker run -v .:/io --rm ghcr.io/astral-sh/ruff check
ruff --version
ruff check --help # 查看 linter 选项
ruff format --help # 查看 formatter 选项
# 检查当前目录所有 Python 文件
ruff check
# 检查并自动修复问题
ruff check --fix
# 监听文件变化并重新检查
ruff check --watch
# 检查指定路径
ruff check path/to/code/
ruff check path/to/file.py
# 检查并显示所有可用修复（包括不安全修复）
ruff check --fix --unsafe-fixes
# 退出码为 0 即使发现 violations
ruff check --exit-zero
Ruff 使用类似 Flake8 的规则代码系统（如 F401、E501）。规则通过 pyproject.toml 或 ruff.toml 配置：
# pyproject.toml
[tool.ruff.lint]
# 启用规则
select = ["E", "F", "B", "UP", "SIM", "I"]
# 忽略特定规则
ignore = ["E501", "F401"]
# 自动修复设置
fixable = ["ALL"]
unfixable = ["F401"]
[tool.ruff.lint]
select = [
"E", # pycodestyle 错误
"F", # Pyflakes
"UP", # pyupgrade
"B", # flake8-bugbear
"SIM", # flake8-simplify
"I", # isort
]
Ruff 将修复分为安全修复和不安全修复：
默认仅启用安全修复。启用不安全修复：
ruff check --fix --unsafe-fixes
# 忽略特定规则
x = 1 # noqa: F841
# 忽略多个规则
i = 1 # noqa: E741, F841
# 忽略所有 violations
y = 2 # noqa
# 文件级忽略（放在文件顶部）
# ruff: noqa
# 文件级忽略特定规则
# ruff: noqa: F401, E501
0：未发现 violations 或所有问题已自动修复1：发现 violations2：异常终止（配置错误、CLI 选项无效或内部错误）# 格式化当前目录所有 Python 文件
ruff format
# 格式化指定路径
ruff format path/to/code/
ruff format path/to/file.py
# 检查格式但不写入（用于 CI）
ruff format --check
# 格式化并显示差异
ruff format --diff
Ruff Formatter 是 Black 的替代品，保持 99.9% 以上的兼容性。主要差异：
# pyproject.toml
[tool.ruff]
line-length = 88 # 行长度限制（默认 88）
[tool.ruff.format]
quote-style = "double" # 引号风格：single/double/preserve
indent-style = "space" # 缩进风格：space/tab
line-ending = "auto" # 行尾：auto/lf/crlf
docstring-code-format = false # 是否格式化 docstring 中的代码示例
docstring-code-line-length = "dynamic" # docstring 代码行长度
# fmt: off
not_formatted = 3
also_not_formatted = 4
# fmt: on
# 跳过单个语句
a = [1, 2, 3, 4, 5] # fmt: skip
使用 Formatter 时建议禁用以下 Linter 规则：
[tool.ruff.lint]
ignore = [
"W191", # tab-indentation
"E111", # indentation-with-invalid-multiple
"E114", # indentation-with-invalid-multiple-comment
"E117", # over-indented
"D206", # docstring-tab-indentation
"D300", # triple-single-quotes
"Q000", # bad-quotes-inline-string
"Q001", # bad-quotes-multiline-string
"Q002", # bad-quotes-docstring
"Q003", # avoidable-escaped-quote
"COM812", # missing-trailing-comma
"COM819", # prohibited-trailing-comma
]
# pyproject.toml
[tool.ruff]
# 全局设置
line-length = 88
target-version = "py38"
include = ["*.py", "*.pyi", "**/pyproject.toml"]
exclude = [".git", "__pycache__", "build", "dist"]
[tool.ruff.lint]
# 启用规则
select = ["E", "F", "B", "UP", "SIM", "I"]
# 忽略特定规则
ignore = ["E501", "F401"]
# 自动修复设置
fixable = ["ALL"]
unfixable = []
# 按文件忽略规则
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"] # 允许未使用的导入
"tests/**/*.py" = ["B"] # 测试文件不检查 bugbear
[tool.ruff.format]
# 格式化设置
quote-style = "double"
indent-style = "space"
line-ending = "auto"
docstring-code-format = true
# isort 设置
[tool.ruff.lint.isort]
known-first-party = ["my_package"]
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]
# 1. 检查并修复代码
ruff check --fix
# 2. 格式化代码
ruff format
# 3. 仅排序导入
ruff check --select I --fix
# 4. 检查未使用的 noqa 指令
ruff check --extend-select RUF100 --fix
# .pre-commit-config.yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.8.0
hooks:
# Linter
- id: ruff
args: [--fix, --exit-non-zero-on-fix]
# Formatter
- id: ruff-format
# GitHub Actions
name: Run Ruff
run: |
pip install ruff
ruff check --exit-non-zero-on-fix
ruff format --check
VS Code：安装官方插件 Ruff，自动启用检查和格式化
其他编辑器：通过 LSP 或插件支持，详见 编辑器集成文档
| 工具 | 功能 | 性能 | 备注 |
|---|---|---|---|
| Flake8 | Lint | 基准 | 需要大量插件 |
| Black | Format | 基准 | 社区标准 |
| isort | 导入排序 | 基准 | - |
| Ruff | Lint + Format + Sort | 10-100x 更快 | 单一工具替代 |
示例：在 CPython 代码库上（约 200k 行），Ruff 检查耗时 <0.5 秒，而 Flake8 需要数十秒。
Ruff 通过 Rust 的高性能实现，将 Python 代码检查、格式化和导入排序统一到一个工具中，带来数量级的性能提升。它与现有工具（Flake8、Black、isort）高度兼容，迁移成本低，是现代 Python 项目的理想选择。
快速开始命令：
pip install ruff
ruff check --fix
ruff format
更多详细信息请访问 Ruff 官方文档。
Ctrl+Shift+X）code --install-extension charliermarsh.ruff
在 VSCode 设置中（文件 > 首选项 > 设置 或按 Ctrl+,），搜索 'Ruff'，添加以下配置：
settings.json 中）{
"[python]": {
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.ruff": "explicit",
"source.organizeImports.ruff": "explicit"
},
"editor.defaultFormatter": "charliermarsh.ruff"
}
}
配置说明：
editor.formatOnSave ：保存时自动格式化代码source.fixAll.ruff ：保存时自动修复可修复的 lint 错误source.organizeImports.ruff ：保存时自动排序导入语句editor.defaultFormatter ：将 Ruff 设为 Python 文件的默认格式化工具settings.json 中）{
"{// 启用/禁用 Ruff 扩展}"
}
Note: The original input had a comment inside JSON which is invalid. I will correct it to valid JSON structure for the example.
Corrected JSON Example:
{
// 启用/禁用 Ruff 扩展
"ruff.enable": true,
// 指定 Python 解释器路径（如果扩展无法自动检测）
"ruff.interpreter": ["/usr/bin/python3"],
// 指定 Ruff 可执行文件路径
"ruff.path": ["/home/user/.local/bin/ruff"],
// 行长度限制
"ruff.lineLength": 88,
// 启用的规则集
"ruff.lint.select": ["E", "F", "W", "I"],
// 忽略的规则
"ruff.lint.ignore": ["E501"],
// 排除的文件/目录
"ruff.exclude": ["**/tests/**", "**/vendor/**"],
// 启用预览特性
"ruff.lint.preview": true,
"ruff.format.preview": true,
// 配置优先级
"ruff.configurationPreference": "filesystemFirst"
}
在项目根目录创建 pyproject.toml 或 ruff.toml：
# pyproject.toml
[tool.ruff]
line-length = 88
target-version = "py38"
include = ["*.py", "*.pyi", "**/pyproject.toml"]
exclude = [".git", "__pycache__", "build", "dist"]
[tool.ruff.lint]
# 启用规则
select = ["E", "F", "B", "UP", "SIM", "I"]
# 忽略规则
ignore = ["E501"]
# 自动修复设置
fixable = ["ALL"]
unfixable = []
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]
"tests/**/*.py" = ["B"]
[tool.ruff.format]
quote-style = "double"
indent-style = "space"
docstring-code-format = true
创建 .vscode/settings.json（仅对当前工作区生效）：
{
"ruff.configuration": "${workspaceFolder}/pyproject.toml",
"ruff.logLevel": "info",
"ruff.trace.server": "messages",
"python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python"
}
Shift+Alt+FCtrl+. 选择修复方案Ctrl+Shift+P) → 'Ruff: Organize Imports'按 Ctrl+Shift+P 打开命令面板，输入：
Ruff: Show Logs - 显示 Ruff 日志Ruff: Restart Server - 重启语言服务器Ruff: Run Linting - 运行代码检查Ruff: Format Document - 格式化当前文档Ruff: Organize Imports - 排序导入语句如果之前使用 Black，确保禁用 Black 并切换到 Ruff：
{
"python.formatting.provider": "none",
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff"
}
}
问题：安装后没有代码检查或格式化功能
解决方案：
ruff --version（建议 ≥ 0.5.3）Ctrl+Shift+P → 'Python: Select Interpreter'）问题：Ruff 和 Pyright 同时运行导致重复提示
解决方案：
{
"python.analysis.diagnosticSeverityOverrides": {
"reportMissingImports": "none",
"reportUnusedVariable": "none"
}
}
问题：团队同时使用 Black 和 Ruff 导致格式冲突
解决方案：
pyproject.toml 中配置 Ruff 的 Black 兼容模式：[tool.ruff.format]
# Ruff 默认就是 Black 兼容的，无需特殊配置
preview = true # 启用最新的 Black 兼容特性
解决方案：
{
"ruff.lint.run": "onType",
"files.watcherExclude": {"**/.ruff_cache/**": true}
}
在 settings.json 中：
{
"ruff.logLevel": "debug",
"ruff.trace.server": "verbose",
"ruff.logFile": "${workspaceFolder}/.vscode/ruff.log"
}
在终端运行：
# 检查当前配置
ruff check --show-settings
# 检查格式化配置
ruff format --show-settings
| 组件 | 最低版本 | 推荐版本 |
|---|---|---|
| VSCode | 1.74.0 | 1.80.0+ |
| Ruff 扩展 | 2024.32.0 | 最新版 |
| Ruff CLI | 0.5.3 | 0.9.8+ |
| Python | 3.7 | 3.10+ |
建议定期更新：
# 更新 Ruff CLI
pip install --upgrade ruff
# 更新 VSCode 扩展
# 在扩展面板点击更新按钮
// .vscode/settings.json
{
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.ruff": "explicit",
"source.organizeImports.ruff": "explicit"
},
"editor.rulers": [88],
"editor.tabSize": 4,
"editor.insertSpaces": true
},
"ruff.enable": true,
"ruff.interpreter": ["${workspaceFolder}/venv/bin/python"],
"ruff.lint.select": ["E", "F", "B", "UP", "SIM", "I"],
"ruff.lint.ignore": ["E501", "F403"],
"ruff.format.preview": true,
"ruff.lint.preview": true,
"files.associations": {"*.pyi": "python"}
}
按照以上配置，Ruff 将在 VSCode 中提供流畅的代码检查和格式化体验，大幅提升 Python 开发效率。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online