Ruff umfassender Leitfaden: Python-Linting mit Rust neu geschrieben, 100× schneller als Flake8

TL;DR: Ruff ist ein in Rust geschriebenes Python-Code-Analysetool (Linter + Formatter), das 10–100× schneller ist als Flake8. Es prüft ein Großprojekt mit 300.000 Zeilen Code in unter 0,5 Sekunden. 2026 gilt Ruff als De-facto-Standard für Code-Qualität im Python-Ökosystem und wird von namhaften Projekten wie Instagram, PyTorch, Jupyter und Apache Airflow eingesetzt. Dieser Leitfaden zeigt dir Schritt für Schritt, wie du Ruff von der Installation über die Konfiguration bis zur vollständigen Migration von Flake8/Black/isort einsetzt.

1. Was ist Ruff?

Ruff wurde vom Astral-Team entwickelt (dasselbe Team wie hinter uv) und ist in Rust geschrieben. Es positioniert sich als All-in-One-Code-Analysetool für das Python-Ökosystem und vereint die Funktionen mehrerer separater Tools:

Warum ist Ruff so schnell?

1. Rust-Kompilierung: Rust ist Python in Sachen Performance um Größenordnungen überlegen
2. Parallele Verarbeitung: Nutzt automatisch mehrere CPU-Kerne für paralleles Datei-Scanning
3. Null Abhängigkeiten: Kein Python-Runtime nötig – eine einzelne Binärdatei genügt
4. Inkrementelles Caching: Nur geänderte Dateien werden geprüft; beim zweiten Lauf fast augenblicklich fertig

Ruff auf GitHub: https://github.com/astral-sh/ruff ⭐ Stand 2026 über 35.000 Sterne.

2. Ruff installieren

Ruff lässt sich auf verschiedene Arten installieren. Empfohlen wird pip oder das offizielle Installationsskript:

# Methode 1: über pip (empfohlen)
pip install ruff

# Methode 2: über uv (schneller)
uv tool install ruff

# Methode 3: macOS Homebrew
brew install ruff

# Methode 4: Offizielles Installationsskript
curl -LsSf https://astral.sh/ruff/install.sh | sh

# Installation prüfen
ruff --version
# Ausgabe: ruff 0.9.x

Nach der Installation stehen zwei Hauptbefehle zur Verfügung:

• ruff check: Code-Analyse (Linter-Modus)
• ruff format: Code-Formatierung (Formatter-Modus)

3. Schnellstart: Prüfe dein Projekt in 5 Minuten

Erstelle eine Testdatei hello.py:

import os
import sys
import json  # unused

def  hello_world():
    x=1+2
    print("hello world")
    return x

if __name__ == "__main__":
    hello_world()

3.1 Code-Analyse ausführen

ruff check hello.py

Beispielausgabe:

hello.py:1:8: F401 [*] `os` imported but unused
hello.py:2:8: F401 [*] `sys` imported but unused
hello.py:3:8: F401 [*] `json` imported but unused
hello.py:5:1: W293 [*] Blank line contains whitespace
hello.py:7:6: E225 [*] Missing whitespace around operator
Found 5 errors.
[*] 5 fixable with the `--fix` option.

Ruff hat präzise 5 Probleme erkannt: 3 ungenutzte Imports, 1 überflüssige Leerzeile und 1 fehlendes Leerzeichen um einen Operator herum. Jeder Fehler ist mit dem Hinweis versehen, ob er per --fix automatisch behoben werden kann.

3.2 Automatische Reparatur

ruff check --fix hello.py

Nach der Ausführung wird der Dateiinhalt automatisch korrigiert:

def hello_world():
    x = 1 + 2
    print("hello world")
    return x

if __name__ == "__main__":
    hello_world()

3.3 Code-Formatierung

ruff format hello.py

ruff format funktioniert ähnlich wie Black: Es passt automatisch Einrückungen, Leerzeilen und Anführungszeichen-Stile an und sorgt so für einen einheitlichen Code-Stil im gesamten Projekt.

4. Konfigurationsdatei im Detail

Erstelle eine pyproject.toml im Projektstammverzeichnis, um Ruff zu konfigurieren:

[tool.ruff]
# Ziel-Python-Version
target-version = "py312"
# Zeilenlängenbeschränkung
line-length = 88
# Zu prüfende Verzeichnisse
src = ["src", "tests"]
# Ausgeschlossene Verzeichnisse
exclude = [
    ".git",
    ".venv",
    "__pycache__",
    "build",
    "dist",
]

[tool.ruff.lint]
# Aktivierte Regelsätze
select = [
    "E",      # pycodestyle-Fehler
    "W",      # pycodestyle-Warnungen
    "F",      # pyflakes
    "I",      # isort (Import-Sortierung)
    "UP",     # pyupgrade (Versions-Upgrade-Vorschläge)
    "B",      # flake8-bugbear (häufige Bug-Muster)
    "SIM",    # flake8-simplify (Code-Vereinfachung)
    "RUF",    # Ruff-eigene Regeln
]
# Deaktivierte Regeln
ignore = [
    "E501",   # Zeile zu lang (dem Formatter überlassen)
    "E402",   # Import nicht am Dateianfang (bei manchen Skripten nötig)
]
# Maximal erlaubte Komplexität
mccabe.max-complexity = 10

[tool.ruff.lint.per-file-ignores]
# Testdateien: bestimmte Regeln ignorieren
"tests/**/*.py" = ["S101", "PLR2004"]
# Migrationsdateien: alle Regeln ignorieren
"**/migrations/*.py" = ["ALL"]

[tool.ruff.format]
# Anführungszeichen-Stil: einfach oder doppelt
quote-style = "double"
# Einrückungstyp
indent-style = "space"
# Abschließende Leerzeile
skip-magic-trailing-comma = false

4.1 Häufige Regelsätze erklärt

5. Kompletter Migrationsleitfaden: Black/isort/Flake8 ersetzen

Wenn dein Projekt bisher die Kombination Black + isort + Flake8 genutzt hat, kannst du vollständig auf Ruff umsteigen.

5.1 Alte Tools deinstallieren

pip uninstall black isort flake8 autoflake pyupgrade -y

5.2 Ruff für Black-Kompatibilität konfigurieren

Füge in der pyproject.toml Black-kompatible Einstellungen hinzu:

[tool.ruff]
line-length = 88          # Black-Standard-Zeilenbreite
target-version = "py312"

[tool.ruff.format]
quote-style = "double"    # Black-Standard: doppelte Anführungszeichen
indent-style = "space"

[tool.ruff.lint]
select = ["E", "W", "F", "I"]

5.3 Gesamtprojekt auf einmal reparieren

# Schritt 1: Alle Python-Dateien formatieren
ruff format .

# Schritt 2: Prüfen und automatisch reparieren
ruff check --fix .

# Schritt 3: Verbleibende Probleme anzeigen (ohne Auto-Fix)
ruff check .

5.4 Integration mit pre-commit

Erstelle eine .pre-commit-config.yaml:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.9.0
    hooks:
      # Zuerst formatieren
      - id: ruff-format
      # Dann prüfen
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]

Pre-commit-Hook installieren:

pip install pre-commit
pre-commit install

Ab jetzt formatiert und prüft Ruff bei jedem git commit automatisch die gestagten Dateien.

6. CI/CD-Integration in der Praxis

6.1 GitHub Actions

name: Ruff Check

on: [push, pull_request]

jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install Ruff
        run: pip install ruff

      - name: Run Ruff format check
        run: ruff format --check .

      - name: Run Ruff lint
        run: ruff check --output-format=github .

6.2 GitLab CI

ruff:
  image: python:3.12-slim
  stage: test
  script:
    - pip install ruff
    - ruff format --check .
    - ruff check .
  allow_failure: true  # Am Anfang können Fehler erlaubt sein

6.3 Performance-Optimierung für Großprojekte

Bei sehr großen Projekten helfen folgende Strategien:

# Nur geänderte Dateien prüfen (CI-Szenario)
ruff check --diff .

# SARIF-Format ausgeben (für GitHub Code Scanning)
ruff check --output-format=sarif . > results.sarif

# Nur bestimmte Regeln prüfen
ruff check --select=F,E .

# Konfiguration und Cache-Status anzeigen
ruff check --show-settings .

7. Ruff im Vergleich zur Konkurrenz

Performance in der Praxis

In einem Projekt mit 500.000 Zeilen Code:

• Ruff check: 0,3 Sekunden
• Flake8: 45 Sekunden
• pylint: 120 Sekunden

Ruff ist damit rund 150× schneller als Flake8 und etwa 400× schneller als pylint.

8. Fortgeschrittene Anwendung

8.1 Eigene Regeln

Ruff ermöglicht über die pyproject.toml die individuelle Anpassung von Regel-Schweregraden:

[tool.ruff.lint]
select = ["E", "F", "W"]

# Bestimmte Regeln als Warnung statt Fehler einstufen
[tool.ruff.lint.flake8-errmsg]
max-string-length = 20

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

8.2 IDE-Integration

VS Code: Installiere die offizielle Ruff-Erweiterung. Sie bietet: - Echtzeit-Lint-Prüfung - Automatisches Formatieren beim Speichern - Ein-Klick-Reparaturvorschläge

// .vscode/settings.json
{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
      "source.fixAll.ruff": "explicit"
    }
  }
}

PyCharm: Über External Tools einrichten: - Settings → Tools → External Tools öffnen - Ruff hinzufügen: Program = ruff, Arguments = check --fix $FilePath$

8.3 Inkrementelle Prüfung (Watch-Modus)

# Dateiänderungen überwachen und automatisch neu prüfen
ruff check --watch .

8.4 HTML-Bericht erstellen

# JSON-Format ausgeben, mit jq weiterverarbeiten
ruff check --output-format=json . | jq '.'

# Oder SARIF-Format für GitHub Code Scanning
ruff check --output-format=sarif . > ruff-results.sarif

9. Häufige Fragen

F1: Kann Ruff Flake8 vollständig ersetzen?

In den meisten Fällen ja. Ruff enthält die meisten Flake8-Regeln (E-, W- und F-Reihen) sowie Regeln beliebter Plugins (bugbear, eradicate usw.). Falls du jedoch ein sehr spezielles Flake8-Plugin nutzt, solltest du vorher prüfen, ob Ruff eine entsprechende Implementierung bietet.

F2: Kann Ruff pylint ersetzen?

Nicht vollständig. Ruff konzentriert sich auf Code-Stil und häufige Bug-Erkennung, während pylint tiefere Code-Qualitätsanalysen bietet (z. B. Komplexitätsbewertung, Duplikaterkennung). Für die tägliche Entwicklung reicht Ruff völlig aus; für strenge Qualitätsaudits empfiehlt sich die Kombination Ruff + pylint.

F3: Ist Ruffs --fix sicher?

Sehr sicher. Die automatische Reparatur betrifft nur Regeln mit klar definierter Fix-Strategie – es werden keine semantischen Änderungen vorgenommen. Vor dem Fixen empfiehlt sich ein Blick auf die geplante Änderung mit ruff check --diff ..

F4: Welche Python-Versionen unterstützt Ruff?

Ruff selbst unterstützt die Code-Analyse für Python 3.7 bis 3.13. Über target-version kannst du die Ziel-Python-Version festlegen und entsprechende Upgrade-Vorschläge erhalten.

10. Fazit

Ruff wird zunehmend zur Code-Qualitäts-Infrastruktur im Python-Ökosystem. Dank der extremen Performance durch Rust, dem umfangreichen eingebauten Regelsatz und dem All-in-One-Linter-plus-Formatter-Erlebnis macht es die Code-Qualitätsverwaltung in Python-Projekten einfacher und effizienter als je zuvor.

Handlungsempfehlung:

1. Mit pip install ruff installieren
2. Im Projekt ruff check --fix . + ruff format . ausführen
3. pyproject.toml für eigene Regeln konfigurieren
4. In pre-commit und CI/CD-Pipeline integrieren

Die Code-Qualität deines Projekts wird sich sofort deutlich verbessern – und der gesamte Vorgang dauert nur wenige Minuten.

Weiterführende Links:

• Ruff offizielle Dokumentation: https://docs.astral.sh/ruff/
• Ruff auf GitHub: https://github.com/astral-sh/ruff
• uv-Tool (Ruff-Schwesterprojekt): https://docs.astral.sh/uv/
• Weiterführende Ressource: linux-tutorials/linux-fileformat.md — Python-Code-Formatierung verstehen
• Weiterführende Ressource: linux-tutorials/ubuntu-dependency.md — Grundlagen des Python-Paketmanagements