Safedump

Debug crashes without reproducing them.
Local-first crash reports with automatic secret redaction.

What is Safedump?

Python's traceback tells you where your code crashed. Safedump tells you why.

When an exception occurs, Safedump captures the complete debugging context — local variables, exception chains, thread state, environment — and saves it as a structured, safe-to-share crash report. No cloud. No telemetry. No network calls. Ever.

import safedump

safedump.install()
# ... your application runs, crashes ...
# Crash report saved: ~/.safedump/crash-2026-06-25-123456-TypeError-a1b2c3.json

Then inspect it anytime:

$ safedump view

Why Safedump?

How is it different?

Quick Start

Installation

For the full experience (terminal viewer):

pip install safedump[view]

Minimal install (no dependencies):

pip install safedump

One-line setup

import safedump

safedump.install()

That's it. Every unhandled exception now produces a crash report.

What a crash report looks like

$ safedump view
╭───────────────────────────────── Exception ──────────────────────────────────╮
│ ZeroDivisionError: division by zero                                          │
╰──────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────╮
│ app.py:13 in <module>                                                        │
╰──────────────────────────────────────────────────────────────────────────────╯
┏━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Variable  ┃ Type     ┃ Value                          ┃
┡━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ safedump  │ module   │ <module 'safedump'>            │
│ calculate │ function │ <function calculate at 0x...>  │
└───────────┴──────────┴────────────────────────────────┘
╭──────────────────────────────────────────────────────────────────────────────╮
│ app.py:10 in calculate                                                       │
╰──────────────────────────────────────────────────────────────────────────────╯
┏━━━━━━━━━━┳━━━━━━┳━━━━━━━┓
┃ Variable ┃ Type ┃ Value ┃
┡━━━━━━━━━━╇━━━━━━╇━━━━━━━┩
│ orders   │ list │ []    │
│ total    │ int  │ 0     │
└──────────┴──────┴───────┘
╭─────────────────────────────── Environment ────────────────────────────────╮
│ OS: posix | Python: 3.11 | Platform: linux | CWD: /app                     │
╰─────────────────────────────────────────────────────────────────────────────╯

Manual capture

try:
    result = dangerous_operation()
except Exception:
    path = safedump.capture_exception()
    print(f"Crash captured: {path}")  # share this file
    raise

Features

🔒 Privacy First

• Zero cloud — no network calls, no telemetry, no accounts
• Secret redaction — passwords, tokens, and API keys automatically scrubbed
• Privacy tiers — configure exactly what gets captured
• File permissions — reports saved with 0600 (owner-only)

📋 Rich Debugging Context

• Local variables — values and types at every stack frame
• Exception chains — full __cause__ + ExceptionGroup support
• Thread state — all threads captured, crashing thread highlighted
• Environment — OS, Python version, CWD, env var names

🎨 Developer Experience

• One-line install — import safedump; safedump.install()
• Beautiful terminal viewer — Rich-powered with syntax highlighting
• CLI tools — view, list, clean, test
• Config presets — configure(preset="production")

🔧 Extensible

• Plugin system — register_serializer() for custom types
• Custom redaction — RedactionRule for domain-specific scrubbing
• before_capture hook — pre-processing before report generation

Configuration

safedump.configure(
    preset="production",  # or "development", "debug", "minimal"
    output_dir="./crashes",  # where to save reports
    privacy_tier=1,  # 0=minimal, 1=default, 4=everything
)

CLI Commands

safedump view                    # View latest crash report
safedump view crash.json         # View specific report
safedump view --json             # View as raw JSON (pipe to jq)
safedump list                    # List recent crashes
safedump list --count 10         # Last 10 crashes
safedump clean --older-than 30   # Delete reports older than 30 days
safedump test                    # Verify installation

FAQ

Does Safedump send data anywhere? No. Safedump is completely offline. It never makes network connections. Crash reports are stored locally on your filesystem.

Is it safe to share crash reports? Yes (after review). By default, Safedump redacts variable names like password, token, and secret, and detects credential patterns (AWS keys, GitHub tokens, JWTs). The report includes a redaction audit trail. Still, always review before sharing publicly.

What's the performance overhead? Zero during normal execution. Safedump only runs when an unhandled exception occurs. Crash capture takes <30ms for typical 20-frame tracebacks.

What Python versions? 3.9 through 3.13. Tested on all versions in CI.

Can I use this in production? Yes. Use configure(preset="production") (privacy tier 1, no env capture, no argv). Safedump is designed to fail gracefully — if the handler itself crashes, the original traceback is always preserved.

Supported Python Versions

Platform Support

Safedump is tested and fully supported on Windows, macOS, and Linux.

Windows-specific notes:

• Crash reports are saved under %USERPROFILE%\.safedump by default (equivalent to ~/.safedump on Unix).
• If the primary output directory is unavailable, Safedump falls back to your system's temp directory (tempfile.gettempdir()), not a hardcoded /tmp path.
• Colored, Rich-formatted output works in PowerShell, Command Prompt, and Windows Terminal. If Rich is not installed, Safedump automatically falls back to clean plain-text output — no crashes, no garbled characters.
• Box-drawing characters used by Rich (panels, tables) render correctly in modern Windows terminals.

Roadmap

• v1.1 — HTML export, safedump serve, entropy-based redaction
• v1.2 — Windows first-class support, logging integration
• v1.3 — Framework guides (Flask, FastAPI, Django)
• v2.0 — Plugin ecosystem, third-party type packages

See ROADMAP.md for details.

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup and guidelines.

Looking for a place to start? Check out good first issues.

License

MIT © Muneer Alam