debugwand - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #react #go #golang #docker #java #windows #awesome #kubernetes #vue #ios #openai #open-source

debugwand

(★ 127)

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

파일 탐색기

최종 버전 다운로드 (.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

# 설치 가이드

1. 코드 내려받기

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

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd debugwand

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Python

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Python 3 설치 시 'Add Python to PATH' 옵션을 꼭 체크하세요 (Windows).

pip install .

PyPI에 배포된 패키지를 바로 설치합니다. 소스 클론이 필요 없습니다.

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

파이썬 스크립트(또는 모듈)를 실행합니다.

✅ 에러 메시지 없이 실행되고 터미널에 안내 문구가 출력되면 정상입니다.

// 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