laurigates/ruff-linting

ruff Linting

Expert knowledge for using ruff check as an extremely fast Python linter with comprehensive rule support and automatic fixing.

When to Use This Skill

| Use this skill when... | Use a focused sibling instead when... | |---|---| | Running ruff check, selecting rule sets, or auto-fixing lint violations | Running ruff format to enforce code style — use ruff-formatting | | Configuring [tool.ruff.lint] rules and per-file ignores in pyproject.toml | Comparing ruff against type-checkers and formatters at a stack level — use python-code-quality | | Wiring ruff into editors, pre-commit, CI/CD, Docker, or build systems | See the quick forms in CI/CD Integration below; full editor/CI/Docker/migration recipes in REFERENCE.md | | Migrating from Flake8/pylint/isort/pyupgrade to ruff's combined rule set | Running ruff format to enforce code style — use ruff-formatting |

Core Expertise

ruff Advantages

• Extremely fast (10-100x faster than Flake8)
• Written in Rust for performance
• Replaces multiple tools (Flake8, pylint, isort, pyupgrade, etc.)
• Auto-fix capabilities for many rules
• Compatible with existing configurations
• Over 800 built-in rules

Basic Usage

Simple Linting

# 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

Auto-Fixing

# 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

Output Formats

# 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

Rule Selection

Common Rule Codes

| 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) | | 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) |

Selecting Rules

# 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

Rule Queries

# 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

Configuration

pyproject.toml

[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

ruff.toml (standalone)

# 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

Advanced Usage

Per-File Configuration

# Override settings for specific paths
ruff check --config path/to/ruff.toml

# Use inline configuration
ruff check --select E,F,B --ignore E501

Targeting Specific Issues

# 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

Integration Patterns

# 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

CI/CD Integration

Quick form — lint with PR annotations on GitHub Actions:

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]
jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v3
        with:
          args: 'check --output-format github'

Quick form — pre-commit hook:

# .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-format

For the full integration recipes — editor setup (VS Code, Neovim, Zed, Helix), the advanced pre-commit config, GitLab/CircleCI/Jenkins, Make/Just/Task/tox, Docker, LSP server settings, and Flake8/Black/pylint migration guides — see REFERENCE.md.

Common Patterns

Finding Specific Issues

# 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

Gradual Adoption

# 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

Refactoring Support

# 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

Plugin Configuration

isort (Import Sorting)

[tool.ruff.lint.isort]
combine-as-imports = true
known-first-party = ["myapp"]
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]

flake8-quotes

[tool.ruff.lint.flake8-quotes]
docstring-quotes = "double"
inline-quotes = "single"
multiline-quotes = "double"

pydocstyle

[tool.ruff.lint.pydocstyle]
convention = "google"  # or "numpy", "pep257"

pylint

[tool.ruff.lint.pylint]
max-args = 10
max-branches = 15
max-returns = 8
max-statements = 60

Best Practices

When to Use ruff check

• Code quality enforcement
• Pre-commit validation
• CI/CD pipelines
• Refactoring assistance
• Security scanning
• Import organization

Critical: Directory Parameters

• ✅ Always pass directory as parameter: ruff check services/orchestrator
• ❌ Never use cd: cd services/orchestrator && ruff check
• Reason: Parallel execution, clearer output, tool compatibility

Rule Selection Strategy

1. Start minimal: select = ["E", "F"] (errors + pyflakes)
2. Add bugbear: select = ["E", "F", "B"]
3. Add imports: select = ["E", "F", "B", "I"]
4. Add pyupgrade: select = ["E", "F", "B", "I", "UP"]
5. Consider security: select = ["E", "F", "B", "I", "UP", "S"]

Fixable vs Unfixable

• Mark uncertain rules as unfixable to review manually
• Common unfixables: B (bugbear), F (pyflakes F401)
• Let ruff fix safe rules: I (isort), UP (pyupgrade)

Common Mistakes to Avoid

• Using cd instead of passing directory parameter
• Enabling ALL rules immediately (use gradual adoption)
• Not using --diff before --fix
• Ignoring rule explanations (ruff rule <code>)
• Not configuring per-file ignores for special cases

Quick Reference

Essential Commands

# 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

Configuration Hierarchy

1. Command-line arguments (highest priority)
2. ruff.toml in current directory
3. pyproject.toml in current directory
4. Parent directory configs (recursive)
5. User config: ~/.config/ruff/ruff.toml

Common Rule Combinations

# 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.