debugx 0.1.0

The most comprehensive offline Python debugging snapshot tool: capture your runtime, system, and project state in one call.

debugx

The most comprehensive offline Python debugging snapshot tool.

debugx collects a complete snapshot of your Python runtime, host system, project, and application environment in a single command -- and writes it out as a beautiful, self-contained HTML dashboard, a GitHub-issue-ready Markdown file, and a schema-versioned JSON document. Everything runs 100% offline. debugx never uploads data anywhere, ever.

pip install debugx

from debugx import capture

capture()

That's it. You now have debug_report.html, debug_report.json, and debug_report.md in your current directory.

Why debugx?

When a bug report says "it works on my machine," or a teammate needs to understand exactly what environment produced a stack trace, debugx gives you one command that answers almost every follow-up question before it's asked: Python version, installed packages, git branch and dirty state, OS/CPU/memory, Docker/Kubernetes context, network reachability, recent log lines, the active exception -- masked for secrets, formatted for humans, and generated in under two seconds.

Features

• Runtime: Python version, executable, virtual environment, pip version, loaded modules, threads, GC stats.
• System: OS, hostname, architecture, CPU, memory, disk usage.
• Project: git branch/commit/status, pyproject.toml/requirements.txt detection, Poetry/uv detection, project structure.
• Environment: environment variables and packages, with automatic secret detection and masking.
• Network: hostname, local IP, DNS status, internet reachability, listening ports -- all local, no data sent.
• Containers: Docker and Kubernetes detection (namespace, pod, node).
• Diagnostics: current exception with syntax-highlighted traceback, call stack, recent log lines, warnings.
• Plugins: register your own health checks with @debugx.plugin -- e.g. "is my database reachable?"
• Never crashes: every collector and plugin is isolated; a failure is recorded, not raised.
• Never uploads: no network calls beyond local reachability checks, no telemetry, no analytics.

Installation

pip install debugx

# Optional: richer CPU/memory/process metrics via psutil
pip install "debugx[full]"

Basic usage

from debugx import capture

capture()

Advanced usage

from debugx import capture

capture(
    output=["html", "json", "markdown"],
    include_packages=True,
    include_git=True,
    include_network=True,
    include_processes=True,
    include_ports=True,
    include_logs=True,
    include_runtime=True,
    include_docker=True,
    include_kubernetes=True,
    include_project=True,
    include_environment=True,
    include_stacktrace=True,
    include_performance=True,
    include_threads=True,
    mask_secrets=True,
    output_directory="./reports",
    compress=False,
    verbose=False,
)

Capturing an exception

from debugx import capture

try:
    1 / 0
except ZeroDivisionError as exc:
    capture(exception=exc, output=["html"])

CLI

debugx capture              # write html+json+markdown to the current directory
debugx capture --html -o ./reports
debugx capture --all --compress
debugx capture --no-network --no-processes --verbose
debugx capture --config debugx.toml

debugx report debug_report.json --html   # re-render HTML/Markdown from a saved JSON snapshot

debugx doctor                # environment sanity checks
debugx plugins                # list discovered plugins
debugx system                 # quick system summary, no files written
debugx version

Run debugx --help or debugx <command> --help for the full flag reference.

Plugins

from debugx import plugin

@plugin(name="database", priority=10, timeout=2.0)
def check_database() -> dict:
    return {"status": "healthy"}

Third-party packages can also register plugins via entry points -- see docs/plugin-development.md.

Security

• debugx never makes network requests that send data anywhere; the only network activity is a bare TCP handshake / DNS lookup used purely to report reachability.
• debugx never executes arbitrary shell commands; git is invoked with a fixed argument list only.
• Secrets (passwords, tokens, API keys, JWTs, connection strings, etc.) are detected and replaced with ******** by default in every output. See SECURITY.md.

Documentation

• Architecture
• Plugin development
• API reference
• Examples
• Contributing
• Changelog
• Roadmap

License

MIT -- see LICENSE.