Ruff in Python: Ein vollständiger Leitfaden zum Ersetzen Ihres Lint- und Format-Stacks

Veröffentlicht

31. Juli 2026

Autor

Faizan Nadeem

Die Grundlagen

Was Ruff tatsächlich abdeckt

Ruff ist ein in Rust geschriebener Linter und Formatter, der konsolidiert, wofür früher mehrere separate Python-Tools nötig waren — Flake8 und sein Plugin-Ökosystem, Black, isort, pyupgrade und autoflake unter anderem. Es wurde von Charlie Marsh entwickelt, der 2022 Astral gründete, um gezielt schnellere Entwickler-Tools für das Python-Ökosystem zu bauen, nachdem er in mehreren anderen Sprach-Ökosystemen gearbeitet und festgestellt hatte, wie viel langsamer sich Python-Tooling im Vergleich anfühlte. Astral entwickelte später mit derselben Grundidee uv, den schnellen Python-Paketmanager, und Anfang 2026 übernahm OpenAI Astral, um dieses Tooling intern einzusetzen — Ruff selbst bleibt Open Source und wird aktiv weiterentwickelt.

Der Grund, warum ein Tool fünf ersetzen kann, ist keine Magie — Linting, Import-Sortierung, Erkennung toten Codes und Syntax-Upgrades sind im Kern dieselbe Operation: den Code in eine Struktur parsen, diese Struktur nach Mustern durchsuchen und dann entweder berichten oder beheben, was man findet. All das in einem Durchlauf und in einer kompilierten Sprache zu tun, ist der Grund, warum Ruff nicht nur „ein bisschen schneller“ ist als der alte Stack — auf realen Codebasen ist es routinemäßig 10- bis 100-mal schneller.

Warum dies ein Problem mit hohem Nutzen ist

Tool-Müdigkeit ist ein echter Produktivitätskostenfaktor. Fünf Konfigurationen, fünf Befehle, fünf Stellen, an denen eine Regel stillschweigend nicht so angewendet wird, wie man es erwartet hat — dieser Overhead summiert sich über jeden Commit, jeden Reviewer und das Onboarding jedes neuen Teammitglieds hinweg.
Langsames Tooling wird übersprungen. Wenn Ihre Lint-Suite 20 Sekunden braucht, führen Entwickler sie lokal irgendwann nicht mehr aus und lassen stattdessen CI sie abfangen, was bedeutet, dass Feedback Minuten später statt sofort ankommt.
Inkonsistentes Formatting erzeugt Rauschen in jedem Diff. Ohne einen erzwungenen Formatter wird Zeit im Code-Review auf Leerraum- und Anführungsstil-Diskussionen verwendet statt auf echte Logik.

Die vollständige Architektur

Source Code ─▶ Parse ─▶ Rule Engine (lint checks) ─▶ Report / Autofix
                              │
                              ▼
                     Formatter (style only, no logic changes)
                              │
                              ▼
                     Clean, consistently-formatted code

Das Leitprinzip: Linting und Formatting sind getrennte Anliegen, die zufällig im selben Binary ausgeliefert werden. Linting verändert, was Ihr Code tut (zum Beispiel das Entfernen eines ungenutzten Imports oder das Aktualisieren alter Syntax); Formatting verändert nur, wie er aussieht (Abstände, Anführungsstil, Zeilenlänge). Diese Unterscheidung klar zu halten, ist wichtig, sobald Sie Regelsets konfigurieren — Sie wollen nicht, dass ein „Stil“-Tool stillschweigend Logik verändert oder umgekehrt.

Die Kernschichten erklärt

1. Linting

Was es ist: Statische Analyse, die echte Probleme in Ihrem Code erkennt — ungenutzte Importe, ungenutzte Variablen, undefinierte Namen und Dutzende weitere Muster — ohne ihn auszuführen.

Warum es wichtig ist: Das sind die Probleme, die später stillschweigend Kosten verursachen: ein ungenutzter Import, der das Entfernen einer fehlenden Abhängigkeit verschleiert, oder eine Variable, die zugewiesen und nie gelesen wird und auf einen Logikfehler hinweist, nicht bloß auf eine Stilfrage.

import os
import sys

print("Hello")

Ruff markiert das sofort:

F401  'sys' imported but unused

Praxistipp: Regelcodes sind nicht willkürlich — das Buchstabenpräfix zeigt an, aus welchem Tool-Regelsatz es stammt (F ist Pyflakes, E ist pycodestyle, B ist flake8-bugbear, I ist isort). Das zu wissen macht es viel schneller, die tatsächliche Bedeutung eines Codes nachzuschlagen, statt zu raten.

2. Formatting

Was es ist: Ein mit Black kompatibler Formatter, der Leerraum, Anführungsstil und Zeilenumbrüche normalisiert — die Logik bleibt unberührt.

# before
x=1+2
print( x )

# after
x = 1 + 2
print(x)

Warum es wichtig ist: Ein konsistenter Formatter entfernt eine ganze Kategorie von Code-Review-Kommentaren und Diff-Rauschen. Niemand diskutiert über Abstände, wenn das Tool es automatisch entscheidet.

Praxistipp: Führen Sie ruff format und ruff check in CI als zwei getrennte Schritte aus, auch wenn beide über dasselbe Tool laufen können — ein Formatting-Fehler und ein Lint-Fehler bedeuten unterschiedliche Dinge, und beides in einem CI-Schritt zusammenzuwerfen macht Fehler schwerer einzuordnen.

3. Import-Sortierung

Was es ist: Automatische, deterministische Reihenfolge von Importen — zuerst Standardbibliothek, dann Drittanbieter, dann lokal — und ersetzt damit, was isort früher separat übernommen hat.

# before
import requests
import os
import json

# after
import json
import os

import requests

Warum es wichtig ist: Die Reihenfolge von Importen wirkt trivial, bis die Editoren zweier Entwickler sie unterschiedlich automatisch sortieren und jeder PR ein nicht zusammenhängender Import-Umsortierungs-Diff beigemischt ist.

4. Autofixing

Was es ist: Ruff meldet Probleme nicht nur — für einen großen Teil der Regeln kann es den Code direkt umschreiben, um sie zu beheben.

ruff check --fix .

# before
import os
import sys

print("Hello")

# after (sys automatically removed)
import os

print("Hello")

Praxistipp: Autofix ist für die meisten Regelkategorien sicher, aber nicht für alle — einige Fixes sind als unsicher markiert, weil sie das Verhalten in Grenzfällen ändern könnten. Prüfen Sie, welche Ihrer aktivierten Regeln autofix-sicher sind, bevor Sie --fix unbeaufsichtigt auf eine große Legacy-Codebasis loslassen.

5. Syntax-Upgrades

Was es ist: Das Umschreiben älterer Python-Idiome in ihre modernen Entsprechungen — die Aufgabe, die pyupgrade früher allein übernommen hat.

# before
name = "{}".format(user)

# after
name = f"{user}"

Warum es wichtig ist: Codebasen sammeln Muster an, die gegen die Python-Version geschrieben wurden, die damals aktuell war. Ein Syntax-Upgrade-Durchlauf hält den Code auf die Interpreter-Version ausgerichtet, die Sie tatsächlich als Ziel haben, statt jahrelange stilistische Altlasten unbegrenzt weiterzutragen.

6. Konfiguration über `pyproject.toml`

Was es ist: Eine einzelne Konfigurationsdatei, die steuert, welche Regelsets aktiv sind, welche Zeilenlänge gilt, welche Python-Zielversion verwendet wird und welcher Formatting-Stil angewendet wird — und ersetzt damit separate Konfigurationsdateien für Flake8, isort und Black.

[tool.ruff]
line-length = 88
target-version = "py312"

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

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

Praxistipp: Beginnen Sie mit einer kleinen select-Liste (E, F mindestens) und erweitern Sie sie bewusst. Am ersten Tag gegen eine bestehende Codebasis jede verfügbare Regelfamilie zu aktivieren, erzeugt meist eine überwältigende Wand von Warnungen, die die Einführung schlimmer erscheinen lässt, als sie ist.

End-to-End-Durchlauf

Verfolgen Sie eine Datei durch einen vollständigen Prüf- und Korrekturzyklus:

Ausgangspunkt. Eine Datei hat einen ungenutzten Import, eine ungenutzte Variable und inkonsistente Abstände:
```
import os
import sys

def hello():
    print( "Hello" )
```
Führen Sie den Linter aus. ruff check . meldet den ungenutzten sys-Import mit dem Regelcode F401.
Beheben Sie, was sicher zu beheben ist. ruff check --fix . entfernt den ungenutzten Import automatisch.
Führen Sie den Formatter aus. ruff format . normalisiert die Abstände innerhalb von print(...).

Ergebnis:

import os


def hello():
    print("Hello")

Commit. Wenn ein pre-commit-Hook konfiguriert ist, laufen beide Schritte automatisch, bevor der Commit durchgelassen wird — ein Entwickler, der vergisst, einen der Befehle manuell auszuführen, kann also trotzdem keinen Code pushen, der eine der beiden Prüfungen nicht besteht.
CI als letztes Gate. Selbst wenn pre-commit eingerichtet ist, führt CI sowohl ruff check . als auch ruff format --check . erneut aus, sodass auch ein lokal umgangener Hook noch vor dem Merge abgefangen wird.

Sonderfälle

Unterdrücken einer Regel, mit der Sie nicht einverstanden sind. Manchmal passt eine Regel nicht zu einer bestimmten Zeile oder Datei. Verwenden Sie einen gezielten Kommentar # noqa: F401 für eine einzelne Zeile statt eines pauschalen ignore in der Konfiguration, das die Regel projektweit stummschaltet.

Monorepos mit unterschiedlichen Standards pro Paket. Die Konfiguration von Ruff ist hierarchisch — eine pyproject.toml in einem Unterverzeichnis kann die Root-Konfiguration nur für dieses Paket überschreiben, was wichtig ist, wenn ein Teil eines Monorepos (etwa ein Legacy-Service) realistisch noch nicht denselben Standard erfüllen kann wie neuerer Code.

Migration einer bestehenden großen Codebasis. Alle Regeln auf einmal gegen jahrelang gewachsenen bestehenden Code zu aktivieren, erzeugt Tausende Warnungen und bringt die Einführung zum Stillstand. Beginnen Sie mit einem minimalen Regelsatz, bringen Sie ihn auf „grün“ und erweitern Sie dann die select-Liste in bewussten, reviewbaren Schritten.

Skalierung & Produktionsherausforderungen

Große Codebasen und CI-Zeit. Ruffs Geschwindigkeit ist genau das, was es praktikabel macht, es bei jedem Push statt nur nachts auszuführen — eine Prüfung, die mit Flake8 über ein großes Repo hinweg zwanzig Sekunden brauchte, ist mit Ruff oft deutlich unter einer Sekunde fertig, was verändert, wie oft Teams bereit sind, sie laufen zu lassen.

Legacy-Code mit Tausenden bestehender Verstöße. Statt alles auf einmal zu beheben, verwenden Sie zuerst ruff check --fix für automatisch behebbare Probleme und triagieren Sie den Rest dann nach Regelcode — alle Instanzen einer bestimmten Regel über die gesamte Codebasis in einem einzigen, reviewbaren PR zu beheben, ist weitaus handhabbarer als ein gigantischer Cleanup-Commit.

Lokale, pre-commit- und CI-Konfigurationen synchron halten. Alle drei sollten dieselbe pyproject.toml lesen, statt die Regelauswahl an verschiedenen Stellen zu duplizieren — Konfigurationsdrift zwischen dem, was der Editor eines Entwicklers erzwingt, und dem, was CI erzwingt, ist eine häufige Ursache für Überraschungen vom Typ „lokal hat es funktioniert“.

Codebeispiele

Editor-Integration, pre-commit und CI sind die drei Stellen, an denen Ruff eingebunden werden muss, damit es tatsächlich erzwungen wird, statt nur optional zu laufen:

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

# .github/workflows/ruff.yml
name: Ruff
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install ruff
      - run: ruff check .
      - run: ruff format --check .

Beachten Sie, dass der CI-Job format --check statt format verwendet — er sollte den Build bei unformatiertem Code fehlschlagen lassen, ihn nicht stillschweigend in CI neu formatieren.

Häufige Fallstricke

Fehler: check und format als denselben Befehl behandeln. Den Formatter zu überspringen, nur weil das Linting bestanden wurde, hinterlässt inkonsistente Abstände und Anführungsstile in der Codebasis. Lösung: Führen Sie beides aus und erzwingen Sie beides getrennt in CI.

Fehler: auf einer bestehenden Codebasis sofort jede Regelfamilie zu aktivieren. Das erzeugt eine so große Zahl an Warnungen, dass sich niemand mehr damit beschäftigt. Lösung: Eng anfangen (E, F), aufräumen und dann bewusst erweitern.

Fehler: zu einem pauschalen ignore greifen statt zu einem gezielten noqa. Eine Regel projektweit stummzuschalten, weil eine Datei eine Ausnahme brauchte, verbirgt echte Probleme überall sonst. Lösung: Begrenzen Sie Unterdrückungen auf die konkrete Zeile oder Datei, die sie benötigt.

Fehler: --fix unbeaufsichtigt auf als unsicher markierte Regeln loszulassen. Nicht jeder Autofix erhält in jedem Randfall das Verhalten. Lösung: Prüfen Sie, welche aktivierten Regeln sicher automatisch zu beheben sind, bevor Sie das in CI ohne menschliche Kontrolle automatisieren.

Fehler: Ruff nur in CI auszuführen, nie lokal. Dadurch wird jeder Lint-Fehler zu einer langsamen Feedback-Schleife über einen CI-Lauf statt zu einer sofortigen im Editor. Lösung: Integrieren Sie es zuerst in Ihren Editor und in pre-commit-Hooks — CI sollte das Sicherheitsnetz sein, nicht der primäre Feedback-Mechanismus.

Best Practices für den Produktionseinsatz

Halten Sie die Konfiguration an einer Stelle. Ein einzelner pyproject.toml-Eintrag, den Editor, pre-commit und CI gleichermaßen lesen, verhindert Drift zwischen dem, was wo erzwungen wird.
Führen Sie Regelsets schrittweise ein. Vor allem bei einer bestehenden Codebasis sollten Sie select in kleinen, reviewbaren Schritten erweitern statt alles auf einmal.
Trennen Sie Linting- und Formatting-Belange in CI. Führen Sie ruff check . und ruff format --check . als getrennte Schritte aus, damit ein Fehler Ihnen sagt, welche Art Problem Sie gerade betrachten.
Begrenzen Sie Unterdrückungen eng. Bevorzugen Sie ein noqa auf Zeilenebene gegenüber einem projektweiten ignore, wann immer eine Regel nicht zu einem bestimmten Fall passt.
Lassen Sie die Geschwindigkeit Ihren Workflow verändern, nicht nur Ihre Wartezeit. Weil Ruff schnell genug ist, um bei jedem Speichern zu laufen, sollten Sie es als Live-Feedback-Schleife im Editor behandeln und nicht nur als pre-commit- oder CI-Gate.

Zum Abschluss

Ruff ist nicht einfach ein schnelleres Flake8 — es ist das Ergebnis davon, fünf separate, langsame Tools durch ein schnelles zu ersetzen, das all ihre Aufgaben gleichzeitig übernimmt. Die Geschwindigkeit ist die Schlagzeile, aber der eigentliche Gewinn ist, dass ein Tool, das schnell genug ist, um bei jedem Tastendruck zu laufen, auch tatsächlich so verwendet wird, statt etwas zu sein, das Entwickler gerade noch tolerieren, einmal vor einem Commit auszuführen. Wenn Sie immer noch mit Flake8, Black und isort als getrennten Konfigurationen jonglieren, ist die Migration kleiner, als sie aussieht.

Was hält Ihr Team noch davon ab, Ihren Lint- und Format-Stack zu konsolidieren — Tooling, Legacy-Konfiguration oder einfach Trägheit?