ruff-linting by laurigates/claude-plugins
npx skills add https://github.com/laurigates/claude-plugins --skill ruff-linting关于使用 ruff check 作为一款极速 Python 代码检查器的专业知识,它具备全面的规则支持和自动修复功能。
ruff 优势
# 检查当前目录
ruff check
# 检查特定文件或目录
ruff check path/to/file.py
ruff check src/ tests/
# 重要:将目录作为参数传递以保持在仓库根目录
# ✅ 正确做法
ruff check services/orchestrator
# ❌ 错误做法
cd services/orchestrator && ruff check
# 显示将要修复的内容(差异预览)
ruff check --diff
# 应用安全的自动修复
ruff check --fix
# 修复特定文件
ruff check --fix src/main.py
# 预览后修复(应用前查看更改)
ruff check --diff services/orchestrator
ruff check --fix services/orchestrator
# 默认输出
ruff check
# 显示统计信息
ruff check --statistics
# 用于工具的 JSON 输出
ruff check --output-format json
# GitHub Actions 注解
ruff check --output-format github
# GitLab 代码质量报告
ruff check --output-format gitlab
# 简洁输出
ruff check --output-format concise
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 代码 | 描述 | 示例规则 |
|---|---|---|
E | pycodestyle 错误 | E501(行过长) |
F | Pyflakes | F401(未使用的导入) |
W | pycodestyle 警告 | W605(无效转义) |
B | flake8-bugbear | B006(可变默认参数) |
I | isort | I001(未排序的导入) |
UP | pyupgrade | UP006(已弃用的类型) |
SIM | flake8-simplify | SIM102(嵌套 if) |
D | pydocstyle | D100(缺少文档字符串) |
N | pep8-naming | N806(变量命名) |
S | flake8-bandit(安全) | S101(assert 使用) |
C4 | flake8-comprehensions | C400(不必要的生成器) |
# 在运行时选择特定规则
ruff check --select E,F,B,I
# 扩展默认选择
ruff check --extend-select UP,SIM
# 忽略特定规则
ruff check --ignore E501,E402
# 显示哪些规则将适用
ruff rule --all
# 解释特定规则
ruff rule F401
# 列出所有可用规则
ruff rule --all
# 按模式搜索规则
ruff rule --all | grep "import"
# 获取详细的规则解释
ruff rule F401
# 输出:unused-import (F401)
# 源自 Pyflakes 检查器。
# 检查未使用的导入。
# 列出所有检查器
ruff linter
# 用于自动化的 JSON 输出
ruff rule F401 --output-format json
[tool.ruff]
# 行长度限制(与 Black 相同)
line-length = 88
# 目标 Python 版本
target-version = "py311"
# 排除目录
exclude = [
".git",
".venv",
"__pycache__",
"build",
"dist",
]
[tool.ruff.lint]
# 启用特定的规则集
select = [
"E", # pycodestyle 错误
"F", # Pyflakes
"B", # flake8-bugbear
"I", # isort
"UP", # pyupgrade
"SIM", # flake8-simplify
]
# 禁用特定规则
ignore = [
"E501", # 行过长(由格式化程序处理)
"B008", # 参数默认值中的函数调用
]
# 允许自动修复
fixable = ["ALL"]
unfixable = ["B"] # 不要自动修复 bugbear 规则
# 按文件忽略
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401", "E402"]
"tests/**/*.py" = ["S101"] # 允许在测试中使用 assert
# 与 pyproject.toml 相同的选项,但没有 [tool.ruff] 前缀
line-length = 100
target-version = "py39"
[lint]
select = ["E", "F", "B"]
ignore = ["E501"]
[lint.isort]
known-first-party = ["myapp"]
force-single-line = true
# 为特定路径覆盖设置
ruff check --config path/to/ruff.toml
# 使用内联配置
ruff check --select E,F,B --ignore E501
# 仅检查特定的规则代码
ruff check --select F401,F841 # 仅未使用的导入/变量
# 专注于安全的检查
ruff check --select S # 所有 bandit 规则
# 仅导入组织
ruff check --select I --fix
# 文档字符串检查
ruff check --select D
# 仅检查已更改的文件(git)
git diff --name-only --diff-filter=d | grep '\.py$' | xargs ruff check
# 检查分支中修改的文件
git diff --name-only main...HEAD | grep '\.py$' | xargs ruff check
# 并行检查多个目录
ruff check src/ &
ruff check tests/ &
wait
# 与其他工具结合使用
ruff check && pytest && ty check
# .pre-commit-config.yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.14.0
hooks:
# 带有自动修复的检查器
- id: ruff-check
args: [--fix]
# 高级配置
- id: ruff-check
name: Ruff 检查器
args:
- --fix
- --config=pyproject.toml
- --select=E,F,B,I
types_or: [python, pyi, jupyter]
# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/ruff-action@v3
with:
args: 'check --output-format github'
changed-files: 'true'
# 或者使用 pip
- name: 安装 ruff
run: pip install ruff
- name: 运行检查器
run: ruff check --output-format github
# .gitlab-ci.yml
Ruff Check:
stage: build
image: ghcr.io/astral-sh/ruff:0.14.0-alpine
script:
- ruff check --output-format=gitlab > code-quality-report.json
artifacts:
reports:
codequality: code-quality-report.json
# 查找未使用的导入
ruff check --select F401
# 查找可变默认参数
ruff check --select B006
# 查找已弃用的类型使用
ruff check --select UP006
# 安全问题
ruff check --select S
# 代码复杂度
ruff check --select C901
# 查找所有 TODO
ruff check --select FIX # flake8-fixme
# 从最少的规则开始
ruff check --select E,F
# 添加 bugbear
ruff check --select E,F,B
# 添加导入排序
ruff check --select E,F,B,I --fix
# 添加 pyupgrade
ruff check --select E,F,B,I,UP --fix
# 生成基线配置
ruff check --select ALL --ignore <violations> > ruff-baseline.toml
# 自动修复所有安全的违规
ruff check --fix
# 修复前预览更改
ruff check --diff | less
# 仅修复导入
ruff check --select I --fix
# 代码现代化
ruff check --select UP --fix
# 简化推导式
ruff check --select C4,SIM --fix
[tool.ruff.lint.isort]
combine-as-imports = true
known-first-party = ["myapp"]
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]
[tool.ruff.lint.flake8-quotes]
docstring-quotes = "double"
inline-quotes = "single"
multiline-quotes = "double"
[tool.ruff.lint.pydocstyle]
convention = "google" # 或 "numpy", "pep257"
[tool.ruff.lint.pylint]
max-args = 10
max-branches = 15
max-returns = 8
max-statements = 60
何时使用 ruff check
关键:目录参数
ruff check services/orchestratorcd services/orchestrator && ruff check规则选择策略
select = ["E", "F"](错误 + pyflakes)select = ["E", "F", "B"]select = ["E", "F", "B", "I"]select = ["E", "F", "B", "I", "UP"]select = ["E", "F", "B", "I", "UP", "S"]可修复 vs 不可修复
unfixable 以手动审查B (bugbear), F (pyflakes F401)I (isort), UP (pyupgrade)应避免的常见错误
cd 而不是传递目录参数--fix 之前不使用 --diffruff rule <code>)# 基本操作
ruff check # 检查当前目录
ruff check path/to/dir # 检查特定目录
ruff check --diff # 显示修复预览
ruff check --fix # 应用修复
# 规则管理
ruff rule --all # 列出所有规则
ruff rule F401 # 解释规则 F401
ruff linter # 列出所有检查器
# 输出格式
ruff check --statistics # 显示违规计数
ruff check --output-format json # JSON 输出
ruff check --output-format github # GitHub Actions 格式
# 选择
ruff check --select E,F,B # 选择规则
ruff check --ignore E501 # 忽略规则
ruff check --extend-select UP # 扩展选择
ruff.tomlpyproject.toml~/.config/ruff/ruff.toml# 最小安全集
ruff check --select E,F
# 良好的默认集
ruff check --select E,F,B,I
# 全面集
ruff check --select E,F,B,I,UP,SIM
# 安全导向集
ruff check --select E,F,B,S
# 文档字符串强制执行
ruff check --select D --config '[lint.pydocstyle]\nconvention = "google"'
这使得 ruff check 成为快速、全面的 Python 代码检查的首选工具。
每周安装数
125
仓库
GitHub 星标数
18
首次出现
2026年2月14日
安全审计
安装于
github-copilot119
opencode119
gemini-cli118
codex118
kimi-cli116
amp116
Expert knowledge for using ruff check as an extremely fast Python linter with comprehensive rule support and automatic fixing.
ruff Advantages
# Lint current directory
ruff check
# Lint specific files or directories
ruff check path/to/file.py
ruff check src/ tests/
# IMPORTANT: Pass directory as parameter to stay in repo root
# ✅ Good
ruff check services/orchestrator
# ❌ Bad
cd services/orchestrator && ruff check
# Show what would be fixed (diff preview)
ruff check --diff
# Apply safe automatic fixes
ruff check --fix
# Fix specific files
ruff check --fix src/main.py
# Fix with preview (see changes before applying)
ruff check --diff services/orchestrator
ruff check --fix services/orchestrator
# Default output
ruff check
# Show statistics
ruff check --statistics
# JSON output for tooling
ruff check --output-format json
# GitHub Actions annotations
ruff check --output-format github
# GitLab Code Quality report
ruff check --output-format gitlab
# Concise output
ruff check --output-format concise
| Code | Description | Example Rules |
|---|---|---|
E | pycodestyle errors | E501 (line too long) |
F | Pyflakes | F401 (unused import) |
W | pycodestyle warnings | W605 (invalid escape) |
B | flake8-bugbear | B006 (mutable default) |
I | isort | I001 (unsorted imports) |
# Select specific rules at runtime
ruff check --select E,F,B,I
# Extend default selection
ruff check --extend-select UP,SIM
# Ignore specific rules
ruff check --ignore E501,E402
# Show which rules would apply
ruff rule --all
# Explain a specific rule
ruff rule F401
# List all available rules
ruff rule --all
# Search for rules by pattern
ruff rule --all | grep "import"
# Get detailed rule explanation
ruff rule F401
# Output: unused-import (F401)
# Derived from the Pyflakes linter.
# Checks for unused imports.
# List all linters
ruff linter
# JSON output for automation
ruff rule F401 --output-format json
[tool.ruff]
# Line length limit (same as Black)
line-length = 88
# Target Python version
target-version = "py311"
# Exclude directories
exclude = [
".git",
".venv",
"__pycache__",
"build",
"dist",
]
[tool.ruff.lint]
# Enable specific rule sets
select = [
"E", # pycodestyle errors
"F", # Pyflakes
"B", # flake8-bugbear
"I", # isort
"UP", # pyupgrade
"SIM", # flake8-simplify
]
# Disable specific rules
ignore = [
"E501", # Line too long (handled by formatter)
"B008", # Function calls in argument defaults
]
# Allow automatic fixes
fixable = ["ALL"]
unfixable = ["B"] # Don't auto-fix bugbear rules
# Per-file ignores
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401", "E402"]
"tests/**/*.py" = ["S101"] # Allow assert in tests
# Same options as pyproject.toml but without [tool.ruff] prefix
line-length = 100
target-version = "py39"
[lint]
select = ["E", "F", "B"]
ignore = ["E501"]
[lint.isort]
known-first-party = ["myapp"]
force-single-line = true
# Override settings for specific paths
ruff check --config path/to/ruff.toml
# Use inline configuration
ruff check --select E,F,B --ignore E501
# Check only specific rule codes
ruff check --select F401,F841 # Only unused imports/variables
# Security-focused check
ruff check --select S # All bandit rules
# Import organization only
ruff check --select I --fix
# Docstring checks
ruff check --select D
# Check only changed files (git)
git diff --name-only --diff-filter=d | grep '\.py$' | xargs ruff check
# Check files modified in branch
git diff --name-only main...HEAD | grep '\.py$' | xargs ruff check
# Parallel checking of multiple directories
ruff check src/ &
ruff check tests/ &
wait
# Combine with other tools
ruff check && pytest && ty check
# .pre-commit-config.yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.14.0
hooks:
# Linter with auto-fix
- id: ruff-check
args: [--fix]
# Advanced configuration
- id: ruff-check
name: Ruff linter
args:
- --fix
- --config=pyproject.toml
- --select=E,F,B,I
types_or: [python, pyi, jupyter]
# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/ruff-action@v3
with:
args: 'check --output-format github'
changed-files: 'true'
# Or using pip
- name: Install ruff
run: pip install ruff
- name: Run linter
run: ruff check --output-format github
# .gitlab-ci.yml
Ruff Check:
stage: build
image: ghcr.io/astral-sh/ruff:0.14.0-alpine
script:
- ruff check --output-format=gitlab > code-quality-report.json
artifacts:
reports:
codequality: code-quality-report.json
# Find unused imports
ruff check --select F401
# Find mutable default arguments
ruff check --select B006
# Find deprecated type usage
ruff check --select UP006
# Security issues
ruff check --select S
# Code complexity
ruff check --select C901
# Find all TODOs
ruff check --select FIX # flake8-fixme
# Start with minimal rules
ruff check --select E,F
# Add bugbear
ruff check --select E,F,B
# Add import sorting
ruff check --select E,F,B,I --fix
# Add pyupgrade
ruff check --select E,F,B,I,UP --fix
# Generate baseline configuration
ruff check --select ALL --ignore <violations> > ruff-baseline.toml
# Auto-fix all safe violations
ruff check --fix
# Preview changes before fixing
ruff check --diff | less
# Fix only imports
ruff check --select I --fix
# Modernize code
ruff check --select UP --fix
# Simplify comprehensions
ruff check --select C4,SIM --fix
[tool.ruff.lint.isort]
combine-as-imports = true
known-first-party = ["myapp"]
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]
[tool.ruff.lint.flake8-quotes]
docstring-quotes = "double"
inline-quotes = "single"
multiline-quotes = "double"
[tool.ruff.lint.pydocstyle]
convention = "google" # or "numpy", "pep257"
[tool.ruff.lint.pylint]
max-args = 10
max-branches = 15
max-returns = 8
max-statements = 60
When to Use ruff check
Critical: Directory Parameters
ruff check services/orchestratorcd services/orchestrator && ruff checkRule Selection Strategy
select = ["E", "F"] (errors + pyflakes)select = ["E", "F", "B"]select = ["E", "F", "B", "I"]select = ["E", "F", "B", "I", "UP"]select = ["E", "F", "B", "I", "UP", "S"]Fixable vs Unfixable
unfixable to review manuallyB (bugbear), F (pyflakes F401)I (isort), UP (pyupgrade)Common Mistakes to Avoid
cd instead of passing directory parameter--diff before --fixruff rule <code>)# Basic operations
ruff check # Lint current directory
ruff check path/to/dir # Lint specific directory
ruff check --diff # Show fix preview
ruff check --fix # Apply fixes
# Rule management
ruff rule --all # List all rules
ruff rule F401 # Explain rule F401
ruff linter # List all linters
# Output formats
ruff check --statistics # Show violation counts
ruff check --output-format json # JSON output
ruff check --output-format github # GitHub Actions format
# Selection
ruff check --select E,F,B # Select rules
ruff check --ignore E501 # Ignore rules
ruff check --extend-select UP # Extend selection
ruff.toml in current directorypyproject.toml in current directory~/.config/ruff/ruff.toml# Minimal safety
ruff check --select E,F
# Good default
ruff check --select E,F,B,I
# Comprehensive
ruff check --select E,F,B,I,UP,SIM
# Security-focused
ruff check --select E,F,B,S
# Docstring enforcement
ruff check --select D --config '[lint.pydocstyle]\nconvention = "google"'
This makes ruff check the preferred tool for fast, comprehensive Python code linting.
Weekly Installs
125
Repository
GitHub Stars
18
First Seen
Feb 14, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
github-copilot119
opencode119
gemini-cli118
codex118
kimi-cli116
amp116
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
163,300 周安装
UP | pyupgrade | UP006 (deprecated types) |
SIM | flake8-simplify | SIM102 (nested if) |
D | pydocstyle | D100 (missing docstring) |
N | pep8-naming | N806 (variable naming) |
S | flake8-bandit (security) | S101 (assert usage) |
C4 | flake8-comprehensions | C400 (unnecessary generator) |