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

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

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.

ruff Integration Reference

Wiring ruff into editors, pre-commit hooks, CI/CD platforms, build systems, Docker, and migration guides. This is the on-demand companion to the ruff-linting skill — the SKILL.md body covers linting rules and the quick pre-commit / GitHub Actions form; this file holds the comprehensive integration material (formerly the standalone ruff-integration skill).

When to reach for this file

Editor Integration

VS Code

// .vscode/settings.json
{
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    },
    "editor.defaultFormatter": "charliermarsh.ruff"
  },
  "ruff.lint.args": ["--select=E,F,B,I"],
  "ruff.importStrategy": "fromEnvironment"
}

# Install extension
code --install-extension charliermarsh.ruff

Neovim (nvim-lspconfig)

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      lint = {
        select = {"E", "F", "B", "I"},
        ignore = {"E501"}
      },
      format = {
        lineLength = 88,
        quoteStyle = "double"
      }
    }
  }
}

Using none-ls.nvim:

local null_ls = require("null-ls")
null_ls.setup {
  sources = {
    null_ls.builtins.formatting.ruff,
    null_ls.builtins.diagnostics.ruff,
  }
}

Zed

// settings.json
{
  "languages": {
    "Python": {
      "language_servers": ["ruff"],
      "formatter": "language_server",
      "format_on_save": "on"
    }
  },
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lint": { "select": ["E", "F", "B", "I"] }
        }
      }
    }
  }
}

Helix

# ~/.config/helix/languages.toml
[[language]]
name = "python"
language-servers = ["ruff"]
auto-format = true
formatter = { command = "ruff", args = ["format", "-"] }

[language-server.ruff]
command = "ruff"
args = ["server"]

Pre-commit Integration

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

Advanced hook configuration (explicit config + rule selection, Jupyter):

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.14.0
    hooks:
      - id: ruff-check
        name: Ruff linter
        args:
          - --fix
          - --config=pyproject.toml
          - --select=E,F,B,I
        types_or: [python, pyi, jupyter]
      - id: ruff-format

pre-commit install           # Install hooks
pre-commit run --all-files   # Run manually
pre-commit autoupdate        # Update versions

Run ruff-check --fix before ruff-format so import/lint fixes land before the formatter normalizes layout.

CI/CD Integration

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'
          changed-files: 'true'   # lint only changed files

Separate lint + format checks:

jobs:
  ruff-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install ruff
      - run: ruff check --output-format github

  ruff-format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install ruff
      - run: ruff format --check --diff

GitLab CI

.base_ruff:
  stage: build
  image:
    name: ghcr.io/astral-sh/ruff:0.14.0-alpine

Ruff Check:
  extends: .base_ruff
  script:
    - ruff check --output-format=gitlab > code-quality-report.json
  artifacts:
    reports:
      codequality: $CI_PROJECT_DIR/code-quality-report.json

Ruff Format:
  extends: .base_ruff
  script:
    - ruff format --check --diff

CircleCI

version: 2.1
jobs:
  lint:
    docker:
      - image: cimg/python:3.11
    steps:
      - checkout
      - run: pip install ruff
      - run: ruff check
      - run: ruff format --check

workflows:
  main:
    jobs:
      - lint

Jenkins

pipeline {
    agent any
    stages {
        stage('Lint') {
            steps {
                sh 'pip install ruff'
                sh 'ruff check --output-format json > ruff-report.json'
            }
        }
        stage('Format Check') {
            steps { sh 'ruff format --check' }
        }
    }
    post {
        always { archiveArtifacts artifacts: 'ruff-report.json' }
    }
}

Build System Integration

Make

.PHONY: lint format check fix

lint:
	ruff check

format:
	ruff format

check: lint
	ruff format --check

fix:
	ruff check --fix
	ruff format

Just

lint:
    ruff check

format:
    ruff format

fix:
    ruff check --fix
    ruff format

ci: lint
    ruff format --check

Task (go-task)

version: '3'
tasks:
  lint:
    cmds: [ruff check]
  format:
    cmds: [ruff format]
  fix:
    cmds:
      - ruff check --fix
      - ruff format
  ci:
    deps: [lint]
    cmds: [ruff format --check]

tox

[testenv:lint]
deps = ruff
commands =
    ruff check
    ruff format --check

[testenv:format]
deps = ruff
commands = ruff format

Docker Integration

Dockerfile

FROM python:3.11-slim as development
RUN pip install --no-cache-dir ruff
COPY . /app
WORKDIR /app
RUN ruff check && ruff format --check

FROM python:3.11-slim as production
# ... production setup

Docker Compose

services:
  lint:
    image: ghcr.io/astral-sh/ruff:0.14.0-alpine
    volumes: [".:/app"]
    working_dir: /app
    command: ruff check

  format:
    image: ghcr.io/astral-sh/ruff:0.14.0-alpine
    volumes: [".:/app"]
    working_dir: /app
    command: ruff format --check

Configuration Hierarchy

1. Command-line arguments (highest priority) 2. Editor LSP settings 3. ruff.toml in current directory 4. pyproject.toml in current directory 5. Parent directory configs (recursive) 6. User config: ~/.config/ruff/ruff.toml 7. Ruff defaults (lowest priority)

LSP Server Configuration

Server Settings

{
  "settings": {
    "lineLength": 88,
    "lint": {
      "select": ["E", "F", "B", "I"],
      "ignore": ["E501"],
      "preview": false
    },
    "format": {
      "preview": false,
      "quote-style": "double"
    },
    "configuration": "~/path/to/ruff.toml"
  }
}

Code Actions

{
  "codeActionsOnSave": {
    "source.fixAll": "explicit",
    "source.organizeImports": "explicit"
  }
}

Migration Guides

From Flake8 + Black

# 1. Remove old tools
pip uninstall flake8 black isort

# 2. Install ruff
pip install ruff

# 3. Migrate configuration
# Convert .flake8 + pyproject.toml[black] → pyproject.toml[ruff]

# 4. Update pre-commit hooks (replace black, flake8, isort with ruff)

# 5. Test
ruff check --diff
ruff format --diff

From pylint

# Map pylint rules to ruff's PLxxx rules
[tool.ruff.lint]
select = ["E", "F", "B", "I", "UP", "PL"]

[tool.ruff.lint.pylint]
max-args = 10
max-branches = 15

ruff check --select PL  # Test pylint-compatible rules

Best Practices

• Editor: Enable format-on-save, use project-specific .vscode/settings.json
• Pre-commit: Run ruff-check --fix first, then ruff-format
• CI/CD: Use --output-format github for PR annotations
• Performance: Cache ruff in CI, run on changed files only in pre-commit
• Team: Commit editor/pre-commit configs to version control