Ruff Integration

ruff Integration

Integrate ruff into editors, pre-commit hooks, and CI/CD pipelines.

When to Use This Skill

VS Code Setup

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

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

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

GitHub Actions CI

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

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

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)

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

Agentic Optimizations

Quick Reference

# Editor
code --install-extension charliermarsh.ruff

# Pre-commit
pre-commit install && pre-commit run --all-files

# CI (GitHub Actions)
uses: astral-sh/ruff-action@v3

# Docker
docker run -v .:/app ghcr.io/astral-sh/ruff:0.14.0-alpine check /app

For editor configs (Neovim, Zed, Helix), GitLab/CircleCI/Jenkins CI, build system integration, Docker setup, LSP configuration, and migration guides, see REFERENCE.md.

ruff Integration Reference

Detailed configurations for editors, CI/CD platforms, build systems, Docker, and migration guides.

Editor Integration

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"]

CI/CD Integration

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

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