Python-Debugging in VS Code

Die Python-Erweiterung unterstützt das Debugging für verschiedene Arten von Python-Anwendungen über die Python-Debugger-Erweiterung. Eine kurze Anleitung zu den Grundlagen des Debuggings finden Sie unter Tutorial - Den Debugger konfigurieren und ausführen. Siehe auch das Flask-Tutorial. Beide Tutorials zeigen grundlegende Fertigkeiten wie das Setzen von Haltepunkten und das schrittweise Durchlaufen von Code.

Für allgemeine Debugging-Funktionen wie das Überprüfen von Variablen, das Setzen von Haltepunkten und andere Aktivitäten, die nicht sprachabhängig sind, lesen Sie den Artikel zum VS Code Debugging.

Dieser Artikel behandelt hauptsächlich Python-spezifische Debugging-Konfigurationen, einschließlich der notwendigen Schritte für bestimmte App-Typen und das Remote-Debugging.

Python-Debugger-Erweiterung

Die Python-Debugger-Erweiterung wird automatisch zusammen mit der Python-Erweiterung für VS Code installiert. Sie bietet Debugging-Funktionen mit debugpy für verschiedene Arten von Python-Anwendungen, einschließlich Skripten, Web-Apps, Remote-Prozessen und mehr.

Um zu überprüfen, ob sie installiert ist, öffnen Sie die Ansicht Erweiterungen (⇧⌘X (Windows, Linux Ctrl+Shift+X)) und suchen Sie nach @installed python debugger. Sie sollten die Python-Debugger-Erweiterung in den Ergebnissen sehen.

Informationen zu unterstützten Python-Versionen finden Sie auf der README-Seite der Erweiterung.

Konfigurationen initialisieren

Eine Konfiguration steuert das Verhalten von VS Code während einer Debugging-Sitzung. Konfigurationen werden in einer launch.json-Datei definiert, die in einem .vscode-Ordner in Ihrem Arbeitsbereich gespeichert ist.

Hinweis: Um die Debugging-Konfiguration zu ändern, muss Ihr Code in einem Ordner gespeichert sein.

Um Debug-Konfigurationen zu initialisieren, wählen Sie zunächst die Ansicht Ausführen und Debuggen in der Seitenleiste

Wenn Sie noch keine Konfigurationen definiert haben, sehen Sie eine Schaltfläche Ausführen und Debuggen sowie einen Link zum Erstellen einer Konfigurationsdatei (launch.json).

Um eine launch.json-Datei mit Python-Konfigurationen zu generieren, führen Sie die folgenden Schritte aus

1. Wählen Sie den Link launch.json-Datei erstellen (wie im Bild oben hervorgehoben) oder verwenden Sie den Menübefehl Ausführen > Konfigurationen öffnen.

2. Wählen Sie Python-Debugger aus der Liste der Debugger-Optionen.

3. Ein Konfigurationsmenü öffnet sich in der Befehlspalette, in dem Sie den Typ der Debug-Konfiguration auswählen können, die Sie für Ihr Python-Projekt verwenden möchten. Wenn Sie ein einzelnes Python-Skript debuggen möchten, wählen Sie Python-Datei in dem erscheinenden Menü Debug-Konfiguration auswählen.

   

   Hinweis: Wenn Sie eine Debugging-Sitzung über das Debug-Panel, F5 oder Ausführen > Debugging starten starten, während keine Konfiguration existiert, wird ebenfalls das Debug-Konfigurationsmenü aufgerufen, aber es wird keine launch.json-Datei erstellt.

4. Die Python-Debugger-Erweiterung erstellt und öffnet daraufhin eine launch.json-Datei, die eine vordefinierte Konfiguration basierend auf Ihrer vorherigen Auswahl enthält, in diesem Fall Python-Datei. Sie können Konfigurationen ändern (z. B. Argumente hinzufügen) und auch benutzerdefinierte Konfigurationen ergänzen.

   

Die Details der Konfigurationseigenschaften werden später in diesem Artikel unter Standardkonfiguration und -optionen behandelt. Weitere Konfigurationen werden ebenfalls in diesem Artikel unter Debugging spezifischer App-Typen beschrieben.

Zusätzliche Konfigurationen

Standardmäßig zeigt VS Code nur die gängigsten Konfigurationen an, die von der Python-Debugger-Erweiterung bereitgestellt werden. Sie können weitere Konfigurationen zur launch.json hinzufügen, indem Sie den Befehl Konfiguration hinzufügen in der Liste und im launch.json-Editor verwenden. Wenn Sie den Befehl verwenden, zeigt Ihnen VS Code eine Liste aller verfügbaren Konfigurationen an (stellen Sie sicher, dass Sie die Option Python auswählen).

Die Auswahl von Anhängen über Prozess-ID führt zu folgendem Ergebnis:

Details zu all diesen Konfigurationen finden Sie unter Debugging spezifischer App-Typen.

Während des Debuggings zeigt die Statusleiste die aktuelle Konfiguration und den aktuellen Debugging-Interpreter an. Durch Klicken auf die Konfiguration wird eine Liste geöffnet, aus der Sie eine andere Konfiguration wählen können.

Standardmäßig verwendet der Debugger denselben Interpreter, der für Ihren Arbeitsbereich ausgewählt ist, genau wie andere Funktionen der Python-Erweiterung für VS Code. Um spezifisch für das Debugging einen anderen Interpreter zu verwenden, setzen Sie den Wert für python in der launch.json für die entsprechende Debugger-Konfiguration. Alternativ können Sie den Python-Interpreter-Indikator in der Statusleiste verwenden, um einen anderen auszuwählen.

Grundlagen des Debuggings

Wenn Sie nur ein Python-Skript debuggen möchten, ist der einfachste Weg, den Pfeil nach unten neben der Ausführen-Schaltfläche im Editor anzuklicken und Python-Debugger: Python-Datei debuggen auszuwählen.

Wenn Sie eine Webanwendung mit Flask, Django oder FastAPI debuggen möchten, bietet die Python-Debugger-Erweiterung dynamisch erstellte Debug-Konfigurationen basierend auf Ihrer Projektstruktur unter der Option Alle automatischen Debug-Konfigurationen anzeigen in der Ansicht Ausführen und Debuggen an.

Wenn Sie jedoch andere Arten von Anwendungen debuggen möchten, können Sie den Debugger über die Ansicht Ausführen starten, indem Sie auf die Schaltfläche Ausführen und Debuggen klicken.

Wenn noch keine Konfiguration festgelegt wurde, erhalten Sie eine Liste von Debugging-Optionen. Hier können Sie die passende Option auswählen, um Ihren Code schnell zu debuggen.

Zwei gängige Optionen sind die Verwendung der Konfiguration Python-Datei, um die aktuell geöffnete Python-Datei auszuführen, oder die Konfiguration Anhängen über Prozess-ID, um den Debugger an einen bereits laufenden Prozess anzuhängen.

Informationen zum Erstellen und Verwenden von Debugging-Konfigurationen finden Sie in den Abschnitten Konfigurationen initialisieren und Zusätzliche Konfigurationen. Sobald eine Konfiguration hinzugefügt wurde, kann sie aus der Dropdown-Liste ausgewählt und mit der Schaltfläche Debugging starten (F5) gestartet werden.

Debugging über die Befehlszeile

Der Debugger kann auch über die Befehlszeile gestartet werden, sofern debugpy in Ihrer Python-Umgebung installiert ist.

debugpy installieren

Sie können debugpy mit python -m pip install --upgrade debugpy in Ihrer Python-Umgebung installieren.

Befehlszeilensyntax

Die Syntax für die Befehlszeile des Debuggers lautet wie folgt

python -m debugpy
    --listen | --connect
    [<host>:]<port>
    [--wait-for-client]
    [--configure-<name> <value>]...
    [--log-to <path>] [--log-to-stderr]
    <filename> | -m <module> | -c <code> | --pid <pid>
    [<arg>]...

Beispiel

Über die Befehlszeile können Sie den Debugger mit einem bestimmten Port (5678) und einem Skript mit der folgenden Syntax starten. Dieses Beispiel geht davon aus, dass das Skript lange läuft, und lässt das Flag --wait-for-client weg, was bedeutet, dass das Skript nicht darauf wartet, dass sich der Client anhängt.

python -m debugpy --listen 5678 ./myscript.py

Sie würden dann die folgende Konfiguration verwenden, um sich von der VS Code Python-Debugger-Erweiterung aus zu verbinden.

{
  "name": "Python Debugger: Attach",
  "type": "debugpy",
  "request": "attach",
  "connect": {
    "host": "localhost",
    "port": 5678
  }
}

Hinweis: Die Angabe des Hosts ist für listen optional, standardmäßig wird 127.0.0.1 verwendet.

Wenn Sie Remote-Code oder Code, der in einem Docker-Container läuft, debuggen möchten, müssten Sie auf dem Remote-Computer oder im Container den vorherigen CLI-Befehl anpassen, um einen Host anzugeben.

python -m debugpy --listen 0.0.0.0:5678 ./myscript.py

Die zugehörige Konfigurationsdatei würde dann wie folgt aussehen.

{
  "name": "Attach",
  "type": "debugpy",
  "request": "attach",
  "connect": {
    "host": "remote-machine-name", // replace this with remote machine name
    "port": 5678
  }
}

Hinweis: Seien Sie sich bewusst, dass Sie durch die Angabe eines anderen Host-Werts als 127.0.0.1 oder localhost einen Port öffnen, um den Zugriff von jedem Computer aus zu ermöglichen, was Sicherheitsrisiken birgt. Sie sollten sicherstellen, dass Sie angemessene Sicherheitsvorkehrungen treffen, wie z. B. die Verwendung von SSH-Tunneln, wenn Sie Remote-Debugging durchführen.

Befehlszeilenoptionen

Hinweis: [<arg>] kann verwendet werden, um Befehlszeilenargumente an die zu startende App zu übergeben.

Debugging durch Anhängen über eine Netzwerkverbindung

Lokales Skript-Debugging

Es kann Fälle geben, in denen Sie ein Python-Skript debuggen müssen, das lokal von einem anderen Prozess aufgerufen wird. Zum Beispiel könnten Sie einen Webserver debuggen, der verschiedene Python-Skripte für spezifische Verarbeitungsaufträge ausführt. In solchen Fällen müssen Sie den VS Code-Debugger an das Skript anhängen, sobald es gestartet wurde.

1. Führen Sie VS Code aus, öffnen Sie den Ordner oder Arbeitsbereich, der das Skript enthält, und erstellen Sie eine launch.json für diesen Arbeitsbereich, falls noch keine existiert.

2. Fügen Sie im Skriptcode Folgendes hinzu und speichern Sie die Datei

   import debugpy
   
   # 5678 is the default attach port in the VS Code debug configurations. Unless a host and port are specified, host defaults to 127.0.0.1
   debugpy.listen(5678)
   print("Waiting for debugger attach")
   debugpy.wait_for_client()
   debugpy.breakpoint()
   print('break on this line')
   

3. Öffnen Sie ein Terminal mit Terminal: Neues Terminal erstellen, wodurch die ausgewählte Umgebung des Skripts aktiviert wird.

4. Installieren Sie im Terminal das debugpy-Paket.

5. Starten Sie im Terminal Python mit dem Skript, zum Beispiel python3 myscript.py. Sie sollten die Meldung "Waiting for debugger attach" sehen, die im Code enthalten ist, und das Skript hält am Aufruf debugpy.wait_for_client() an.

6. Wechseln Sie in die Ansicht Ausführen und Debuggen (⇧⌘D (Windows, Linux Ctrl+Shift+D)), wählen Sie die entsprechende Konfiguration aus der Dropdown-Liste des Debuggers und starten Sie den Debugger.

7. Der Debugger sollte am Aufruf debugpy.breakpoint() anhalten, ab dem Sie den Debugger normal verwenden können. Sie haben auch die Möglichkeit, über die Benutzeroberfläche andere Haltepunkte im Skriptcode zu setzen, anstatt debugpy.breakpoint() zu verwenden.

Remote-Skript-Debugging mit SSH

Remote-Debugging ermöglicht es Ihnen, ein Programm lokal in VS Code schrittweise zu durchlaufen, während es auf einem Remote-Computer ausgeführt wird. Es ist nicht notwendig, VS Code auf dem Remote-Computer zu installieren. Für zusätzliche Sicherheit möchten oder müssen Sie möglicherweise eine sichere Verbindung, wie SSH, zum Remote-Computer verwenden, wenn Sie debuggen.

Hinweis: Auf Windows-Computern müssen Sie möglicherweise Windows 10 OpenSSH installieren, um den ssh-Befehl verfügbar zu haben.

Die folgenden Schritte skizzieren den allgemeinen Prozess zur Einrichtung eines SSH-Tunnels. Ein SSH-Tunnel ermöglicht es Ihnen, auf Ihrem lokalen Computer so zu arbeiten, als würden Sie direkt auf dem Remote-Computer arbeiten, und zwar auf sicherere Weise, als wenn ein Port für den öffentlichen Zugriff geöffnet wäre.

Auf dem Remote-Computer

1. Aktivieren Sie die Portweiterleitung, indem Sie die Konfigurationsdatei sshd_config öffnen (zu finden unter /etc/ssh/ auf Linux und unter %programfiles(x86)%/openssh/etc auf Windows) und die folgende Einstellung hinzufügen oder ändern:

   AllowTcpForwarding yes
   

   Hinweis: Der Standardwert für AllowTcpForwarding ist „yes“, daher müssen Sie möglicherweise keine Änderung vornehmen.

2. Wenn Sie AllowTcpForwarding hinzufügen oder ändern mussten, starten Sie den SSH-Server neu. Unter Linux/macOS führen Sie sudo service ssh restart aus; unter Windows führen Sie services.msc aus, wählen Sie OpenSSH oder sshd in der Liste der Dienste und wählen Sie Neu starten.

Auf dem lokalen Computer

1. Erstellen Sie einen SSH-Tunnel, indem Sie ssh -2 -L Zielport:localhost:Zielport -i Identitätsdatei Benutzer@Remoteadresse ausführen, wobei Sie einen gewählten Port für Zielport sowie den entsprechenden Benutzernamen und die IP-Adresse des Remote-Computers unter Benutzer@Remoteadresse verwenden. Um beispielsweise Port 5678 auf der IP-Adresse 1.2.3.4 zu verwenden, lautet der Befehl ssh -2 -L 5678:localhost:5678 -i Identitätsdatei benutzer@1.2.3.4. Sie können den Pfad zu einer Identitätsdatei mit dem Flag -i angeben.

2. Überprüfen Sie, ob Sie eine Eingabeaufforderung in der SSH-Sitzung sehen können.

3. Erstellen Sie in Ihrem VS Code-Arbeitsbereich eine Konfiguration für Remote-Debugging in Ihrer launch.json-Datei und setzen Sie den Port auf den Port, der im ssh-Befehl verwendet wurde, und den Host auf localhost. Sie verwenden hier localhost, weil Sie den SSH-Tunnel eingerichtet haben.

   {
     "name": "Python Debugger: Attach",
     "type": "debugpy",
     "request": "attach",
     "port": 5678,
     "host": "localhost",
     "pathMappings": [
       {
         "localRoot": "${workspaceFolder}", // Maps C:\Users\user1\project1
         "remoteRoot": "." // To current working directory ~/project1
       }
     ]
   }
   

Debugging starten

Nachdem ein SSH-Tunnel zum Remote-Computer eingerichtet wurde, können Sie mit dem Debugging beginnen.

1. Beide Computer: Stellen Sie sicher, dass identischer Quellcode verfügbar ist.

2. Beide Computer: debugpy installieren.

3. Remote-Computer: Es gibt zwei Möglichkeiten, festzulegen, wie man sich an den Remote-Prozess anhängt.

   1. Fügen Sie im Quellcode die folgenden Zeilen hinzu und ersetzen Sie Adresse durch die IP-Adresse und Portnummer des Remote-Computers (IP-Adresse 1.2.3.4 dient hier nur zur Veranschaulichung).

      import debugpy
      
      # Allow other computers to attach to debugpy at this IP address and port.
      debugpy.listen(('1.2.3.4', 5678))
      
      # Pause the program until a remote debugger is attached
      debugpy.wait_for_client()
      

      Die in listen verwendete IP-Adresse sollte die private IP-Adresse des Remote-Computers sein. Sie können das Programm dann normal starten, wodurch es pausiert, bis sich der Debugger anhängt.

   2. Starten Sie den Remote-Prozess über debugpy, zum Beispiel

      python3 -m debugpy --listen 1.2.3.4:5678 --wait-for-client -m myproject
      

      Dies startet das Paket meinprojekt mit python3, wobei die private IP-Adresse des Remote-Computers 1.2.3.4 lautet und auf Port 5678 gewartet wird (Sie können den Remote-Python-Prozess auch starten, indem Sie einen Dateipfad anstelle von -m angeben, wie zum Beispiel ./hallo.py).

4. Lokaler Computer: Nur wenn Sie den Quellcode auf dem Remote-Computer wie oben beschrieben geändert haben, fügen Sie im Quellcode eine auskommentierte Kopie desselben Codes hinzu, der auf dem Remote-Computer hinzugefügt wurde. Das Hinzufügen dieser Zeilen stellt sicher, dass der Quellcode auf beiden Computern Zeile für Zeile übereinstimmt.

   #import debugpy
   
   # Allow other computers to attach to debugpy at this IP address and port.
   #debugpy.listen(('1.2.3.4', 5678))
   
   # Pause the program until a remote debugger is attached
   #debugpy.wait_for_client()
   

5. Lokaler Computer: Wechseln Sie in die Ansicht Ausführen und Debuggen (⇧⌘D (Windows, Linux Ctrl+Shift+D)) in VS Code, wählen Sie die Konfiguration Python-Debugger: Anhängen.

6. Lokaler Computer: Setzen Sie einen Haltepunkt in den Code, an dem Sie mit dem Debugging beginnen möchten.

7. Lokaler Computer: Starten Sie den VS Code-Debugger mit der angepassten Konfiguration Python-Debugger: Anhängen und der Schaltfläche "Debugging starten". VS Code sollte an Ihren lokal gesetzten Haltepunkten anhalten, sodass Sie den Code schrittweise durchlaufen, Variablen untersuchen und alle anderen Debugging-Aktionen durchführen können. Ausdrücke, die Sie in der Debug-Konsole eingeben, werden ebenfalls auf dem Remote-Computer ausgeführt.

   Die Textausgabe an stdout, wie von print-Anweisungen, erscheint auf beiden Computern. Andere Ausgaben, wie grafische Diagramme aus einem Paket wie matplotlib, erscheinen jedoch nur auf dem Remote-Computer.

8. Während des Remote-Debuggings erscheint die Debugging-Symbolleiste wie unten gezeigt

   

   In dieser Symbolleiste stoppt die Schaltfläche zum Trennen (⇧F5 (Windows, Linux Shift+F5)) den Debugger und ermöglicht es dem Remote-Programm, bis zum Abschluss zu laufen. Die Schaltfläche zum Neustarten (⇧⌘F5 (Windows, Linux Ctrl+Shift+F5)) startet den Debugger auf dem lokalen Computer neu, startet das Remote-Programm aber nicht neu. Verwenden Sie die Neustart-Schaltfläche nur, wenn Sie das Remote-Programm bereits neu gestartet haben und den Debugger erneut anhängen müssen.

Konfigurationsoptionen festlegen

Wenn Sie launch.json zum ersten Mal erstellen, gibt es zwei Standardkonfigurationen, die die aktive Datei im Editor entweder im integrierten Terminal (innerhalb von VS Code) oder im externen Terminal (außerhalb von VS Code) ausführen.

{
  "configurations": [
    {
      "name": "Python Debugger: Current File (Integrated Terminal)",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal"
    },
    {
      "name": "Python Debugger: Current File (External Terminal)",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "externalTerminal"
    }
  ]
}

Die spezifischen Einstellungen werden in den folgenden Abschnitten beschrieben. Sie können auch andere Einstellungen hinzufügen, wie args, die nicht in den Standardkonfigurationen enthalten sind.

Tipp: Es ist oft hilfreich in einem Projekt, eine Konfiguration zu erstellen, die eine bestimmte Startdatei ausführt. Wenn Sie beispielsweise immer start.py mit den Argumenten --port 1593 starten möchten, wenn Sie den Debugger starten, erstellen Sie einen Konfigurationseintrag wie folgt

 {
     "name": "Python Debugger: startup.py",
     "type": "debugpy",
     "request": "launch",
     "program": "${workspaceFolder}/startup.py",
     "args" : ["--port", "1593"]
 },

name

Bietet den Namen für die Debug-Konfiguration, der in der VS Code-Dropdown-Liste erscheint.

type

Identifiziert den zu verwendenden Debugger-Typ; lassen Sie dies für das Debuggen von Python-Code auf debugpy eingestellt.

request

"program": "/Users/Me/Projects/MyProject/src/event_handlers/__init__.py",

"program": "${workspaceFolder}/src/event_handlers/__init__.py",

"args": ["--quiet", "--norepeat", "--port", "1593"],

{
  "name": "Python Debugger: Current File",
  "type": "debugpy",
  "request": "launch",
  "program": "${file}",
  "console": "integratedTerminal",
  "autoReload": {
    "enable": true
  }
}