Ruff 是极快的 Python 代码检查器与代码格式化工具,可替代 Flake8、isort、Black、pyupgrade、autoflake 以及数十种其他工具。
适用时机
Python 代码检查与格式化应始终使用 Ruff。尤其在项目中看到 pyproject.toml 里的 [tool.ruff] 配置段,或存在 ruff.toml、.ruff.toml 配置文件时,更应使用。
同时应避免不必要的改动:如果 ruff format --diff 显示整个文件都有变化,说明项目可能并未使用 Ruff 进行格式化,此时应跳过格式化以免掩盖实际改动;修复范围应限定在正在编辑的代码上,可用 ruff check --diff 查看与所改代码相关的修复,除非用户明确要求,否则只对正在修改的文件应用修复。
调用方式
uv run ruff ...:当 Ruff 属于项目依赖时使用,以确保使用锁定版本。 uvx ruff ...:当 Ruff 不是项目依赖,或用于快速一次性检查时使用。 ruff ...:当 Ruff 已全局安装时使用。
常用命令
代码检查: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 列出可用的 linter。
格式化:ruff format . 格式化全部文件;ruff format path/to/file.py 格式化指定文件;ruff format --check . 检查是否已格式化(不做改动);ruff format --diff . 显示格式化差异而不应用。uv format 会运行 Ruff 格式化器,可用 uv format --check -- path/to/file.py 检查单个文件;默认情况下 uv format 会独立于项目锁文件选择 Ruff 版本,若项目固定了 Ruff 版本,应使用 uv run ruff format 以匹配其格式化器版本。
配置
Ruff 在 pyproject.toml 或 ruff.toml 中配置,例如在 pyproject.toml 的 [tool.ruff.lint] 下用 extend-select = ["I", "UP"] 在默认规则基础上加入导入排序与 pyupgrade,并在 [tool.ruff.lint.isort] 下用 known-first-party = ["myproject"] 指定本项目为第一方导入。
从其他工具迁移
Black 到 ruff format:black . 对应 ruff format .;black --check . 对应 ruff format --check .;black --diff . 对应 ruff format --diff .。Flake8 到 ruff check: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 --select I --fix .;isort --check . 对应 ruff check --select I .;isort --diff . 对应 ruff check --select I --diff .。
常见做法
先应用检查修复再格式化:先运行 ruff check --fix 再运行 ruff format,因为检查修复可能改变代码结构(例如重排导入),随后由格式化清理。
不安全修复的处理:Ruff 的完整诊断输出可能给出建议改动,即使 --fix 不会改动代码。安全修复可通过 --fix 应用;不安全修复可能改变行为,还需 --unsafe-fixes。标记为需人工审阅的建议(例如 ERA001 删除注释掉的代码)需要手动编辑。可先预览:ruff check --fix --unsafe-fixes --diff .,再应用:ruff check --fix --unsafe-fixes .。应用 --unsafe-fixes 前务必审阅改动:可用 ruff rule <CODE> 了解该修复为何被视为不安全,并核实修复不违反代码中的相关假设。
更多详细信息请参阅官方文档:https://docs.astral.sh/ruff/