https://github.com/savannahostrowski/debugwand
An *experimental* zero-preparation remote debugger for Python applications running in *local* Kubernetes clusters or Docker containers.
https://github.com/savannahostrowski/debugwand
debugger debugging docker knative kubernetes python uvicorn
Last synced: 3 months ago
JSON representation
An *experimental* zero-preparation remote debugger for Python applications running in *local* Kubernetes clusters or Docker containers.
- Host: GitHub
- URL: https://github.com/savannahostrowski/debugwand
- Owner: savannahostrowski
- License: mit
- Created: 2025-10-30T19:08:05.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-04-05T15:17:48.000Z (3 months ago)
- Last Synced: 2026-04-05T17:13:42.857Z (3 months ago)
- Topics: debugger, debugging, docker, knative, kubernetes, python, uvicorn
- Language: Python
- Homepage: https://pypi.org/project/debugwand/
- Size: 204 KB
- Stars: 115
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# debugwand 🪄
A zero-preparation remote debugger for Python applications running in Kubernetes clusters or Docker containers.
*Made possible by the Python 3.14 [remote debugging attachment protocol](https://docs.python.org/3/howto/remote_debugging.html) and [debugpy](https://github.com/microsoft/debugpy)*
> Note: `debugwand` is experimental and not made for production. Use at your own risk.
## Features
- **Zero-preparation debugging** - No code changes or restarts required
- **Full breakpoint debugging** - Using `debugpy`
- **Kubernetes-native** - Handles pod discovery, service routing, and Knative
- **Container support** - Debug Python processes in local Podman or Docker containers
- **Process selection** - Interactive selection with CPU/memory metrics
## Requirements
- **Python 3.14+** on both local machine and target
- **debugpy** installed in the target container
- **kubectl** (for Kubernetes) or **Docker CLI** (for containers)
- **SYS_PTRACE capability** - on Linux/containers (see [troubleshooting](docs/troubleshooting.md))
## Quick Start
### Kubernetes
```bash
# List pods and Python processes
wand pods -n my-namespace -s my-service --with-pids
# Debug a live process
wand debug -n my-namespace -s my-service
```
### Docker/Podman
```bash
# Debug a container (must have SYS_PTRACE capability)
wand debug --container my-container
```
> Containers must be started with `--cap-add=SYS_PTRACE` and `-p 5679:5679`
### Connect your editor
**VSCode** launch configuration:
```json
{
"name": "Attach to debugwand",
"type": "debugpy",
"request": "attach",
"connect": { "host": "localhost", "port": 5679 },
"pathMappings": [{ "localRoot": "${workspaceFolder}", "remoteRoot": "/app" }]
}
```
**Other DAP clients**: Connect to `localhost:5679`
## Configuration
| Environment Variable | Description |
|---------------------|-------------|
| `DEBUGWAND_SIMPLE_UI` | Set to `1` for simplified output (useful for Tilt/CI) |
| `DEBUGWAND_AUTO_SELECT_POD` | Set to `1` to auto-select the newest pod |
## Additional Documentation
- **[Hot-Reload Support](docs/hot-reload.md)** - Debugging with uvicorn `--reload` mode
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
## How it works
```
┌─────────────────┐ ┌────────────────────┐
│ Local Machine │ │ Pod / Container │
│ │ │ │
│ debugwand CLI │◄─ kubectl/docker/podman ─► │ Python App │
└────────┬────────┘ └────────┬───────────┘
│ │
│ 1. Discover pods (k8s only) │
├─────────────────────────────────────────────►│
│ │
│ 2. List Python processes │
├─────────────────────────────────────────────►│
│ │
│ 3. Select process │
│ │
│ 4. Inject debugpy via │
│ sys.remote_exec() │
├─────────────────────────────────────────────►│
│ │
│ 5. debugpy.listen()
│ ┌──────────────┤
│ 6. Port-forward (k8s) │ │
│ or exposed port │ │
│◄──────────────────────────────┼─────────────►│
│ localhost:5679 │ │
│ └──────────────┤
│ 7. Connect editor │
├──────────────────────────────────────────────┤
│ Debugging Session │
│◄────────────────────────────────────────────►│
```
## License
MIT