debugwand - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #typescript #android #rust #deep-learning #linux #docker #windows #awesome #cli #vue #awesome-list #pytorch

debugwand

(★ 127)

An *experimental* zero-preparation remote debugger for Python applications running in *local* Kubernetes clusters or Docker containers.

File Explorer

Download Latest Version (.zip)

- - build.yml
  - lint.yml
  - test.yml
  - typecheck.yml
- dependabot.yml
- __init__.py
- attacher.py
- cli.py
- container.py
- debugpy_template.py
- kubernetes.py
- operations.py
- types.py
- ui.py
- hot-reload.md
- troubleshooting.md
- test_k8s.py
- test_operations.py
- test_wand.py
.gitignore
.pre-commit-config.yaml
.python-version
debug.png
LICENSE
pyproject.toml
README.md

# Installation Guide

1. Get the code

git clone https://github.com/savannahostrowski/debugwand

Downloads the entire project code from GitHub to your computer.

cd debugwand

Moves into the project folder you just downloaded.

2. Python

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Python 3 On Windows, be sure to check 'Add Python to PATH' during installation.

pip install .

Installs the package published on PyPI directly — no need to clone the source.

python <실행할 파일명>.py # README에서 정확한 실행 파일명을 확인하세요

Runs the Python script (or module).

✅ If it runs without errors and prints output in the terminal, it worked.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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