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 config overrides, targeted rule checks, and changed-files-only / parallel invocation patterns are in references/command-recipes.md.

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

Recipes for finding specific issues, gradual adoption, and refactoring support are in references/command-recipes.md.

Plugin Configuration

Per-plugin [tool.ruff.lint.<plugin>] settings (isort, flake8-quotes, pydocstyle, pylint) are in references/plugin-configuration.md.

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.