GGitHub 趋势观察站
每日 07:00 更新订阅EN
← 返回今日榜单

精选指南 · 编程与开发

Ruff

在单个 Python 文件上完成诊断、修复与格式检查。用明确的规则配置和两次复查确认结果。

访问 GitHub 仓库 ↗
最近上榜 · 2026-11-08#10

当日排名

+350当日新增 Star50,961总 Star
← 全部精选指南

入选理由:小样本即可核对诊断、修复与格式化,官方文档给出了规则配置与退出状态,补充指南目录中的 Python 代码质量实践。

入选:2026-11-07 · 资料核对:2026-11-07。根据官方资料整理,未进行安装与功能实测。

Ruff:让一次 Python 检查和格式化有可核对的结果

它解决什么问题

Ruff 可以检查 Python 源码中的静态问题,也能统一引号和空白等格式。这里用一个样本把两个步骤分开,先发现并移除未使用的导入,再检查并整理格式。学会读取检查结果后,可以把相同流程放到提交前或持续集成中。

适合谁,哪些情况不适合

经常维护 Python 脚本或团队仓库的人,可以先在单个文件上熟悉规则与格式选项。已有检查器的项目可以选取小目录试行,核对改动后再确定覆盖范围。需要验证程序输出、接口行为或类型时,还要运行项目测试或相应的类型检查工具。

环境与准备

示例使用 macOS 或 Linux 的终端,要求 python3 能创建带 pip 的虚拟环境。安装阶段需要能访问 Python 包索引。使用独立练习目录和虚拟环境,可以把示例文件和软件版本放在一起。Windows 用户可以按官方安装页选择相应安装方式,下面的路径与终端命令以 macOS 和 Linux 为例。

安装与第一次使用

1. 创建独立目录并安装。 本例固定为本次核对过发行说明的 0.17.4。以下命令在同一个终端执行。

workdir=$(mktemp -d) &&
cd "$workdir" &&
python3 -m venv .venv &&
.venv/bin/python -m pip install 'ruff==0.17.4' &&
.venv/bin/ruff --version

确认最后一条显示 Ruff 版本,再继续创建两个文件。ruff.toml 只选 F401,便于把未使用导入与其他规则区分开。

cat > ruff.toml <<'TOML'
[lint]
select = ["F401"]
TOML

cat > example.py <<'PY'
import math

print(  "hello"  )
PY

2. 先读诊断,再应用修复。 运行下面的检查,应在第一行看到 F401,表示导入的 math 没有被使用。此时可以打开文件确认。

.venv/bin/ruff check --config ruff.toml example.py

确认这行导入可以移除后,运行:

.venv/bin/ruff check --config ruff.toml --fix example.py
.venv/bin/ruff check --config ruff.toml example.py

第二次检查应通过,文件里应只剩打印语句及空白。真实项目可在修复前先查看规则和预期改动。

3. 检查格式并验证。 先用 --check 查看是否仍有格式差异,随后执行写回。

.venv/bin/ruff format --config ruff.toml --check example.py
.venv/bin/ruff format --config ruff.toml example.py
.venv/bin/ruff format --config ruff.toml --check example.py
cat example.py
.venv/bin/python example.py

第一次格式检查预计提示文件需要调整,最后一次应通过。源码应显示为 print("hello"),运行应输出 hello。这里的预期结果来自文档和示例,未把文档核对当作现场运行记录。

主要能力与典型场景

  • 提交前排查。 对改动文件先运行 check,按诊断中的文件位置与规则编号处理问题。只对已确认的范围使用 --fix。
  • 统一已有项目的格式。 先对小目录运行 format --check,确认差异后单独提交格式调整,便于审阅。
  • 让团队用同一套设置。 把规则与目标 Python 版本写入项目配置,固定 CI 使用的 Ruff 版本。已有 pyproject.toml 的项目可在 tool.ruff.lint 下配置检查规则。
  • 整理导入。 如果团队需要导入排序,可在检查配置中增加 I 系列规则,检查并修复后再格式化。格式化命令本身只处理版式。

常见问题与排错

  • 检查没有出现 F401。 确认进入练习目录,文件中仍有 import math,且 --config 指向本例的 ruff.toml。也可用 check --show-settings 查看解析后的设置。
  • 格式检查退出码为 1。 有文件需要格式化时,--check 会用非零状态提示差异。若配置无效或命令异常,格式化文档列出的退出码为 2。
  • 终端与编辑器结果不同。 比对工具版本、目标文件和配置路径。嵌套项目可能命中更近的配置文件。
  • 自动修复改了文件。 先看差异再决定是否保留。用于 CI 的格式检查可用 --check,仅报告状态。

费用、隐私与限制

Ruff 源码采用 MIT,本文命令在本地读取与检查源文件,无需模型账号或上传代码。安装软件包需要联网。自动修复和格式化会改写目标文件,使用前确认路径和工作区状态。规则诊断覆盖配置选定的问题,代码是否符合业务预期由项目测试核对。

官方资料