Pyright-Leitfaden: Schnelle statische Typprüfung für Python-Code

Typ-Hinweise machen Python-Code einfacher zu verstehen und zu pflegen. Aber hier ist der Haken: Hinweise allein finden keine Fehler. Du brauchst einen Typ-Checker, um sicherzustellen, dass dein Code auch wirklich den von dir angegebenen Typen entspricht.

Ich hab's sowohl mit Mypy als auch mit Pyright in der Produktion ausprobiert. Der Geschwindigkeitsvorteil von Pyright ist vor allem während der Entwicklung deutlich zu sehen. Tippfehler werden schon während der Eingabe angezeigt und nicht erst nach dem Speichern. Bei großen Codebasen macht diese schnellere Feedbackschleife echt einen Unterschied.

Dieses Tutorial zeigt dir alles, was du brauchst, um Pyright richtig zu nutzen. Ich zeige dir, wie du es installierst, für dein Projekt einrichtest und in VS Code integrierst. Ich werde auch die Unterschiede zwischen Pyright und Mypy herausarbeiten.

Was ist Pyright?

Pyright ist ein statischer Typprüfer für Python, den Microsoft entwickelt hat. Es liest deinen Code, checkt die Typ-Annotationen und meldet Fehler, wenn die Typen nicht passen. Im Gegensatz zu Laufzeitprüfungen, die Fehler bei der Ausführung des Codes erkennen, werden diese bei der statischen Analyse schon vor der Ausführung entdeckt.

Während die meisten Python-Tools in Python geschrieben sind, ist Pyright in TypeScript geschrieben und läuft auf Node.js. Seltsame Wahl für ein Python-Tool, oder? Aber genau deshalb ist Pyright so schnell. Die V8-JavaScript-Engine läuft viel schneller als CPython.

Du wirst Pyright auf zwei Arten begegnen. Du kannst es als Befehlszeilentool in CI/CD-Pipelines laufen lassen, um Typfehler vor dem Zusammenführen zu erkennen. Oder vielleicht benutzt du es schon, ohne es zu merken. Es läuft mit Pylance, der Python-Erweiterung von Microsoft für VS Code. Die roten Wellenlinien unter den Tippfehlern? Das ist Pyright, der hinter den Kulissen arbeitet.

Das Tool kommt mit gebündelten Typ-Stubs für die Python-Standardbibliothek und gängige Pakete. Du musst nichts extra installieren, um Code zu überprüfen, der os, json oder typing nutzt. Für Pakete von Drittanbietern nutzt Pyright von der Community gepflegte Stubs aus typeshed oder paket-spezifische Stubs, die du separat installierst.

Wie installiere ich Pyright?

Jetzt installieren wir Pyright auf deinem System. Du hast zwei Möglichkeiten, das Programm zu installieren: npm (die native Methode) oder pip (der Python-Wrapper).

Pyright mit npm installieren

Die empfohlene Installation nutzt npm, weil Pyright auf Node.js läuft. Du brauchst Node.js Version 14.0.0 oder höher.

# Global installation
npm install -g pyright

# Run without installing globally
npx pyright

# Local project installation
npm install --save-dev pyright

Ich nutze die globale Installation für schnelle Checks und die lokale Installation für Projekte, bei denen ich die Version festlegen will. Der Ansatz „ npx “ ist praktisch für einmalige Sachen, ohne dass du deine globalen Pakete erweitern musst.

Pyright über Python-Wrapper installieren

Wenn dein Team nur mit Python arbeitet und Node.js nicht in der Toolchain haben will, gibt's einen PyPI-Wrapper:

# Standard installation
pip install pyright

# Recommended: includes Node.js automatically
pip install pyright[nodejs]

Der Wrapper checkt, ob Node.js auf deinem System installiert ist. Wenn es fehlt, lädt der Wrapper automatisch eine eigenständige Version runter. Das Extra „ [nodejs] “ nutzt eine zuverlässigere Download-Methode als die Standardmethode.

Denk dran, dass es immer Kompromisse gibt. Der erste Durchlauf dauert länger, weil Abhängigkeiten runtergeladen werden müssen. CI-Umgebungen mit eingeschränktem Netzwerkzugang könnten nicht funktionieren. Und die PyPI-Version kommt manchmal ein paar Tage später raus als die npm-Versionen.

Für die meisten Python-Teams funktioniert der Wrapper super. Solltest du aber Probleme haben, greif einfach auf die npm-Installation zurück. Es ist zuverlässiger.

Pyright in einem Python-Projekt ausführen

Nach der Installation ist die Nutzung von Pyright echt einfach. Geh zu deinem Projektverzeichnis und führe Folgendes aus:

pyright

Das ist es eigentlich schon. Pyright sucht nach Python-Dateien, checkt sie und meldet alle Typfehler, die es findet. Keine komplizierte Einrichtung nötig.

Was Pyright standardmäßig überprüft

Was sucht Pyright? Ohne irgendwelche Einstellungen macht es ein paar Überprüfungen. Es überprüft Typ-Annotationen, die mit der tatsächlichen Verwendung übereinstimmen. Es fängt undefinierte Variablen und nicht erreichbaren Code ab. Es überprüft Importe richtig. Es zeigt offensichtliche Typfehler an, wie zum Beispiel, wenn man eine Zeichenfolge übergibt, wo eigentlich eine ganze Zahl erwartet wird.

Hier ist ein Beispiel für die Ausgabe eines Projekts mit Fehlern:

/src/utils.py:12:15 - error: Argument of type "str" cannot be assigned 
   to parameter "count" of type "int" in function "process_items"
   "str" is not assignable to "int" (reportArgumentType)
/src/main.py:45:9 - error: "user" is possibly unbound (reportPossiblyUnbound)
2 errors, 0 warnings, 0 informations

Jeder Fehler zeigt den Dateipfad, die Zeilennummer, die Spalte und eine Beschreibung an. Der Name der Regel in Klammern (wie „ reportArgumentType “) zeigt dir genau, welche Prüfung den Fehler ausgelöst hat. Das ist wichtig, wenn du bestimmte Regeln unterdrücken willst. Darauf kommen wir gleich noch zu sprechen.

Exit-Codes verstehen

Pyright gibt je nach Ergebnis unterschiedliche Exit-Codes zurück:

In CI-Pipelines willst du normalerweise, dass der Build bei Exit-Code 1 fehlschlägt. Die Exit-Codes 2-4 zeigen an, dass mit dem Tool selbst was schiefgelaufen ist, nicht mit deinem Code.

Pyright einrichten

Pyright funktioniert zwar sofort, aber echte Projekte brauchen Anpassungen. Du solltest angeben, welche Dateien überprüft werden sollen, welche Python-Version verwendet werden soll und wie streng die Analyse sein soll. Schauen wir uns mal die wichtigsten Konfigurationsoptionen an.

Typprüfungsmodi

Pyright hat vier Stufen der Strenge. Der Modus, den du wählst, bestimmt, wie viele Regeln aktiviert werden.

Welchen Modus solltest du wählen? Bei neuen Projekten solltest du mit„ “ im Standardmodus „ “ anfangen. Es findet echte Fehler, ohne dich mit Meldungen zu überhäufen. Arbeitest du mit altem Code? Der Basis- -Modus ist besser, wenn du das Tippen nach und nach lernst. Benutz denstrengen Modusvon „ “ nur für Bibliotheken und wichtige Infrastrukturen, wo du maximale Sicherheit brauchst.

Kleiner Hinweis: Der Sprung von Standard zu Strict ist ziemlich groß. Der strenge Modus aktiviert etwa 30 zusätzliche Regeln, darunter Anforderungen für Typ-Annotationen bei allen Funktionsparametern und Rückgabewerten. Rechne beim Wechsel mit einer Verzehnfachung der gemeldeten Fehler. Ich hab das auf die harte Tour gelernt.

Der strenge Modus verlangt vollständige Typ-Annotationen. Bild vom Autor

Konfigurationsdateien

Pyright liest die Konfiguration von pyrightconfig.json oder pyproject.toml. Wenn beides da ist, hat pyrightconfig.json Vorrang.

Hier ist ein minimalistisches pyrightconfig.json:

{
  "include": ["src"],
  "exclude": ["**/node_modules", "**/__pycache__", "**/.venv"],
  "pythonVersion": "3.12",
  "typeCheckingMode": "standard"
}

Das Äquivalent in „ pyproject.toml “:

[tool.pyright]
include = ["src"]
exclude = ["**/node_modules", "**/__pycache__", "**/.venv"]
pythonVersion = "3.12"
typeCheckingMode = "standard"

Die Konfigurationsdatei regelt, wie Pyright funktioniert. Bild vom Autor.

Hier ist ein wichtiges Detail, das viele Leute verwirrt: Wenn du „ exclude “ manuell festlegst, ersetzt es ersetzt die Standardeinstellungen komplett. Füge immer „ node_modules “, „ __pycache__ “ und deine virtuelle Umgebung in benutzerdefinierte Ausschlussmuster ein. Ansonsten versucht Pyright, deine Abhängigkeiten zu analysieren, was zu massiven Verzögerungen führt. Glaub mir, du willst nicht 10 Minuten auf eine Typprüfung warten.

Konfiguration der virtuellen Umgebung

Wie findet Pyright deine installierten Pakete? Du musst ihm sagen, wo es suchen soll. Mach das mit venvPath und venv:

{
  "venvPath": ".",
  "venv": ".venv"
}

Das sagt Pyright, dass es nach Paketen in ./.venv suchen soll. Wenn du einen anderen Speicherort für die virtuelle Umgebung benutzt, pass das entsprechend an. Ohne das kann Pyright deine installierten Abhängigkeiten nicht finden und meldet für alles fehlende Importfehler.

Diagnose unterdrücken

Manchmal hat Pyright technisch gesehen recht, aber du musst bestimmte Fehler trotzdem ignorieren. Vielleicht arbeitest du mit altem Code oder weißt in einem bestimmten Fall besser Bescheid als der Typ-Checker. Du kannst Fehler auf drei Ebenen unterdrücken.

Unterdrückung der Konfigurationsebene

Regeln komplett deaktivieren:

{
  "reportMissingTypeStubs": "none",
  "reportUnusedVariable": "warning"
}

Unterdrückung auf Dateiebene

Füge oben in der Datei einen Kommentar hinzu:

# pyright: basic
# pyright: reportPrivateUsage=false

Unterdrückung der Leitungspegel

Eine einzelne Zeile unterdrücken:

x: int = "hello"  # type: ignore
x: int = "hello"  # pyright: ignore
x: int = "hello"  # pyright: ignore[reportAssignmentType]

Die spezielle Regelsyntax ([reportAssignmentType]) ist praktisch, wenn du eine Überprüfung deaktivieren willst, ohne die anderen in derselben Zeile zu beeinträchtigen.

Nachdem wir uns mit der Konfiguration beschäftigt haben, schauen wir uns mal an, wie Pyright in deine Entwicklungsumgebung integriert wird.

Pyright in VS Code und IDEs

Wenn du wie die meisten Python-Entwickler bist, wirst du Pyright eher über Pylance als über die Befehlszeile nutzen. Wenn du diese Beziehung verstehst, kannst du deinen Editor richtig einrichten und häufige Probleme vermeiden.

Pyright gegen Pylance

Pylance ist die VS Code-Erweiterung von Microsoft, die die Typüberprüfungs-Engine von Pyright mitbringt. Wenn du Pylance installierst, bekommst du Pyright automatisch dazu. Aber Pylance hat ein paar Funktionen, die es im Open-Source-Pyright nicht gibt:

• Semantische Hervorhebung: Variablen werden je nach Typ farbig dargestellt.
• Erweiterter automatischer Import: intelligentere Importvorschläge
• Code-Navigation: Such alle Referenzen in deinem Arbeitsbereich

Diese Funktionen sind Closed Source und nur in VS Code verfügbar. Wenn du Neovim, Emacs oder einen anderen Editor benutzt, bekommst du die Kernfunktionen von Pyright, aber nicht diese Extras.

Pylance zeigt Typfehler im Editor an. Bild vom Autor.

Wichtige VS Code-Einstellungen

Richte Pylance über die Einstellungen von VS Code ein:

{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "standard",
  "python.analysis.diagnosticMode": "openFilesOnly"
}

Die Einstellung „ diagnosticMode “ beeinflusst die Leistung. „ "openFilesOnly" “ checkt nur die Dateien, die du gerade geöffnet hast. „ "workspace" “ checkt alles, braucht aber mehr Speicher und CPU-Leistung.

Häufige Konfigurationsprobleme

Die Wahl des Dolmetschers ist wichtig. Pylance nutzt den Python-Interpreter, den du ausgewählt hast, um installierte Pakete zu finden. Wenn plötzlich Fehler bei Paketen auftauchen, von denen du weißt, dass sie installiert sind, schau mal nach, ob in der Statusleiste von VS Code der richtige Interpreter ausgewählt ist.

Die Auswahl des Interpreters beeinflusst die Pfade zur Paketerkennung. Bild vom Autor.

Die Standardeinstellungen von CLI und Pylance sind unterschiedlich. Pylance setzt „ typeCheckingMode “ standardmäßig auf „ "off" “, während die CLI standardmäßig „ "standard" “ verwendet. Pylance fügt außerdem automatisch „ src “ zu den Suchpfaden hinzu, die CLI tut das nicht. Damit dein Editor und CI immer gleich funktionieren, musst du alle Optionen in „ pyproject.toml “ genau festlegen.

Das Phänomen des „ausgegrauten Codes“. Pylance macht nicht erreichbaren Code anhand einer Typanalyse grau. Wenn Code unerwartet ausgegraut angezeigt wird, schau dir die Funktion an, die direkt davor aufgerufen wurde. Eine Funktion, die so geschrieben ist, dass sie „ NoReturn “ zurückgibt , lässt alles danach unerreichbar erscheinen.

Pyright gegen Mypy: Wann man was benutzt

Du fragst dich vielleicht: Soll ich Pyright verwenden oder bei Mypy bleiben? Beide Tools sind einsatzbereit, und welche du nimmst, hängt von deinem Arbeitsablauf und deinen Anforderungen ab. Ich erkläre dir mal die wichtigsten Unterschiede.

Geschwindigkeit und Reaktionsfähigkeit

Pyright ist ungefähr 3- bis 5-mal schneller als Mypy, wenn es um komplette Projektscans geht, und bei inkrementellen Überprüfungen geht's quasi sofort. Das ist vor allem während der Entwicklung wichtig, wenn du sofort Feedback haben willst.

Mypy hat einen Daemon-Modus (dmypy), der die Leistung verbessert, aber trotzdem langsamer ist und manchmal Probleme mit dem Cache hat, die einen Neustart brauchen.

Unterschiede bei der Typinferenz

Jetzt wird's spannend. Die Tools machen unterschiedliche Typ-Schlussfolgerungen. Schau dir mal diesen Code an:

coordinates = (10, 20)

Pyright macht die Schlussfolgerung „ tuple[Literal[10], Literal[20]] “ und behält die genauen Werte bei, weil Tupel unveränderlich sind. Mypy denkt sich „ tuple[int, int] “ aus und erweitert das auf allgemeine Typen.

Pyrights Ansatz findet mehr Fehler, führt aber manchmal zu Problemen, wenn Funktionen allgemeine Typen erwarten. In der Praxis ist das meistens egal, weil „ Literal[10] ” ein gültiger Untertyp von „int ” ist .

Analyse von Code ohne Anmerkungen

Das ist der größte praktische Unterschied und ein echter Game-Changer für alte Codebasen. Mypy ignoriert standardmäßig nicht kommentierte Funktionen. Pyright checkt sie trotzdem und findet offensichtliche Fehler auch ohne Typ-Hinweise.

Bei alten Codebasen mit wenigen Anmerkungen ist Pyright ein starker Linter, der undefinierte Variablen und unmögliche Methodenaufrufe findet. Mypy sieht diese Funktionen als „dynamisch“ an und ignoriert sie einfach.

Plugin-Unterstützung

Mypy hat Plugins für Frameworks wie Django und SQLAlchemy. Diese Plugins verstehen die ORM-Magie und bieten genaue Typen für dynamisch generierte Attribute.

Pyright hat kein Plugin-System. Es hängt komplett von Typ-Stubs ab. Im Jahr 2026 haben die meisten großen Bibliotheken hochwertige Stubs, sodass das nicht mehr so wichtig ist wie früher. Wenn du aber ein Framework mit viel Metaprogrammierung benutzt, schau mal, ob es gute Stubs gibt, bevor du dich für Pyright entscheidest.

Benutz Pylance (Pyright) während der Entwicklung, um sofort Feedback zu kriegen, und überleg dir, Pyright und Mypy in CI laufen zu lassen, wenn dein Projekt Framework-Plugins nutzt.

Häufige Probleme bei der Nutzung von Pyright

Wenn Pyright unerwartete Fehler meldet, liegt das meistens an einem dieser Probleme.

Fehlende Typ-Stubs

Hast du diesen Fehler schon mal gesehen? Pyright meckert, wenn es keine Typinformationen für ein Paket findet:

Import "requests" could not be resolved (reportMissingImports)

Fehlende Stubs lösen Importwarnungen aus. Bild vom Autor.

Schau zuerst mal, ob das Paket in deiner virtuellen Umgebung installiert ist und ob Pyright weiß, wo es zu finden ist (mit den Einstellungen „ venvPath “ und „ venv “, die wir schon besprochen haben).

Wenn das Paket installiert ist, aber keine Typinformationen hat, installiere die Community-Stubs:

pip install types-requests types-PyYAML types-redis

Für Pakete ohne verfügbare Stubs hast du zwei Möglichkeiten. Du kannst die Warnung in deiner Konfiguration mit „ "reportMissingTypeStubs": "none" ” deaktivieren. Oder mach deine eigenen Entwürfe:

pyright --createstub some_package

Dadurch wird eine Skelett - .pyi -Datei erstellt, die du mit den von dir tatsächlich verwendeten Methoden füllen kannst.

Fehler beim Pre-Commit-Hook

Funktioniert Pyright lokal, aber nicht in Pre-Commit-Hooks? Das Problem ist meistens die Isolierung der Umgebung. Pre-Commit führt Hooks in abgeschotteten Umgebungen aus, die die installierten Pakete deines Projekts nicht sehen können.

Behebe das Problem, indem du den Hook auf deine virtuelle Umgebung richtest:

repos:
  - repo: https://github.com/RobertCraigie/pyright-python
    rev: v1.1.408
    hooks:
      - id: pyright
        args: ["--venvpath", ".", "--venv", ".venv"]

Unerwartete Fehler im strengen Modus

Hast du den strengen Modus aktiviert und plötzlich tauchen Tausende von Fehlern auf? Keine Panik. Das ist ganz normal. Der strenge Modus verlangt vollständige Typ-Annotationen. Fang mit dem Basis- oder Standardmodus an, füge nach und nach Anmerkungen hinzu und aktiviere „strict“ nur für vollständig typisierte Module.

Benutze Kommentare pro Datei, um Legacy-Code in einem laxen Modus zu halten:

# pyright: basic

So kannst du neue Codes streng checken und gleichzeitig alte Codes nach und nach migrieren.

Abgesehen von der Fehlerbehebung gibt's hier ein paar Tipps, die dir von Anfang an helfen, Pyright besser zu nutzen.

Tipps für die Nutzung von Pyright

Nachdem ich mit Pyright an verschiedenen Projekten gearbeitet habe, habe ich ein paar Sachen gelernt, die die Einführung einfacher machen. Wenn du diese Best Practices für die Codierung anwendest, bleibt deine Typprüfung eine Hilfe und wird nicht zum Problem.

Fang mit dem Standardmodus an. Wie schon gesagt, fängt es echte Fehler ab, ohne dass man alles kommentieren muss. Du kannst die Regeln später immer noch verschärfen.

Mach deine Pyright-Version fest. Pyright bringt oft neue Versionen raus, und manchmal markiert die neue Version Code, der vorher okay war. Bei CI kann ein nicht angehefteter „ pip install pyright ” dazu führen, dass Builds am Montagmorgen nach den Releases vom Wochenende fehlschlagen. Ich war schon mal da. Das macht keinen Spaß.

[tool.pyright]
# In pyproject.toml
pythonVersion = "3.12"

# In requirements-dev.txt
pyright==1.1.408

Behebt Fehler nach und nach. Versuch nicht, 10.000 Fehler auf einmal zu beseitigen. Benutze das Array „ strict “, um strenge Überprüfungen nur für bestimmte Verzeichnisse durchzuführen:

{
  "typeCheckingMode": "standard",
  "strict": ["src/core", "src/api"]
}

Benutz Konfigurationsdateien frühzeitig. Selbst bei kleinen Projekten verhindert eine klare Konfiguration Überraschungen. Nimm dir fünf Minuten Zeit, um deine Python-Version, den Pfad zur virtuellen Umgebung und die gewählte Strenge zu notieren. Dein zukünftiges Ich wird dir dankbar sein.

Strebe nicht sofort nach Perfektion. Benutz am Anfang ruhig viel „ # pyright: ignore “. Das macht technische Schulden sichtbar, sodass du sie nach und nach bereinigen kannst, anstatt den Fortschritt zu blockieren. Perfekt ist der Feind des Guten, vor allem wenn man neue Tools einführt.