Add new Remote Python Debugger integration (#13800)

2025-07-23 09:17:06 +00:00 · 2020-06-22 15:25:09 +02:00 · 2020-06-22 15:25:09 +02:00 · dc01bd2d4a
commit dc01bd2d4a
parent fe6daeaf46
1 changed files with 157 additions and 0 deletions
--- a/source/_integrations/debugpy.markdown
+++ b/source/_integrations/debugpy.markdown
@ -0,0 +1,157 @@
+---
+title: Remote Python Debugger
+description: Remote Python Debugger (debugpy) for Visual Studio Code 
+ha_category:
+  - Utility
+ha_release: 0.112
+ha_codeowners:
+  - '@frenck'
+ha_domain: debugpy
+---
+
+The remote Python debugger integration allows you to use the Visual Studio Code
+Python debug tooling with a remote Home Assistant instance.
+
+It uses Microsoft's `debugpy` library which is the successor of `ptvsd`, and
+the default library used by Visual Studio Code.
+
+This is useful in testing changes on a local development install, or connecting
+to a production server to debug issues. It is possible to load the integration
+without the activating the debugger, but injecting it with a service call. This
+is particularly useful on a developer' production system as it does not impact
+performance when not injected.
+
+## Configuration
+
+To enable the remote Python debugger integration add the following to
+your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+debugpy:
+```
+
+By default this will listen on all local interfaces, on port 5678,
+will not wait for a connection and start when Home Assistant starts.
+
+{% configuration %}
+host:
+  description: The local interface to listen on.
+  required: false
+  default: 0.0.0.0 (all interfaces).
+  type: string
+port:
+  description: Port to listen on.
+  required: false
+  default: 5678
+  type: integer
+start:
+  description: "If `true`, the debugger will be injected on start of Home Assistant. Set it to false to inject it on demand using the `debugpy.start` service call."
+  required: false
+  default: true
+  type: boolean
+wait:
+  description: "If `true`, wait for the debugger to connect before starting up Home Assistant. This option is ignore when `start` is set to `false`."
+  required: false
+  default: false
+  type: boolean
+{% endconfiguration %}
+
+## Security
+
+Ensure if this is a public-facing server, that the port is secured. Anyone who
+is able to access the debugger port can *execute arbitrary code* on the
+Home Assistant server, which is very unsafe.
+
+If the Home Assistant server is behind your firewall with only the http(s) port
+exposed, then this is safe from outside connections.
+
+## Performance and Memory Use
+
+Using the debugger (even when not attached), increases memory usage and
+decreases performance. It is not recommended to configure the debugger on a
+persistent (production) server, unless absolutely required.
+
+Alternatively, the integration can be loaded by setting the `start` option
+to `false`. This will prevent the debugger from being injected, instead,
+it will be injected on-demand by calling the `debugpy.start` service.
+
+## Waiting at startup
+
+If you want to debug something in the start-up sequence, configure the
+integration to wait for a connection first:
+
+```yaml
+# Example configuration.yaml entry
+debugpy:
+  start: true
+  wait: true
+```
+
+The debugger is loaded quite early on in the boot-up sequence, before any other
+integrations. This will allow you to set breakpoints in `async_setup` or similar
+and debug the loading of the integration.
+
+## Alternate host and port
+
+You can also listen on a different server address or port:
+
+```yaml
+# Example configuration.yaml entry
+debugpy:
+  host: localhost
+  port: 6789
+```
+
+This is useful for multi-homed servers, or for localhost only access
+
+## Service `debugpy.start`
+
+When the `start` option of the integration has been set to `false`, one can
+use the `debugpy.start` service call to inject and start the remote Python
+debugger at runtime.
+
+Please note: There is no way to stop it once started, this would require
+a restart of Home Assistant.
+
+## Example Visual Studio Code configuration
+
+This can be copied into your `launch.json` in the `.vscode` subdirectory in
+your Visual Studio Code project to connect to the debugger.
+
+```json
+{
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            // Example of attaching to local debug server
+            "name": "Python: Attach Local",
+            "type": "python",
+            "request": "attach",
+            "port": 5678,
+            "host": "localhost",
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}",
+                    "remoteRoot": "."
+                }
+            ],
+        },
+        {
+            // Example of attaching to my production server
+            "name": "Python: Attach Remote",
+            "type": "python",
+            "request": "attach",
+            "port": 5678,
+            "host": "homeassistant.local",
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}",
+                    "remoteRoot": "/usr/src/homeassistant"
+                }
+            ],
+        }
+    ]
+}
+```