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.safedump.json

Then inspect it anytime:

safedump view              # Terminal (Rich)
safedump view --html       # Self-contained HTML file
safedump serve             # Local web browser UI

Why Safedump?

Quick Start

Installation

pip install safedump[view]    # with Rich terminal viewer
pip install safedump           # minimal (no dependencies)

One-line setup

import safedump

safedump.install()

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

Manual capture

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

Features

🔒 Privacy First

• Zero cloud — no network calls, no telemetry, no accounts
• Secret redaction — denylist (variable names) + regex (credentials) + entropy-based detection
• Privacy tiers — from tier 0 (stack trace only, safe to share) to tier 4 (adds env var values); see Privacy Tiers
• File permissions — reports saved with 0600 (owner-only)

📋 Rich Debugging Context

• Local variables — structured values (nested lists and dicts) and types at every stack frame
• Exception chains — full __cause__ + ExceptionGroup support
• Thread state — all threads captured, crashing thread highlighted; crashes in worker threads and in __del__ are captured too
• 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
• Self-contained HTML export — safedump view --html report.html
• Local web server — safedump serve for browsing reports in the browser
• CLI filtering — safedump list --type KeyError --since 7d --search error
• Crash statistics — safedump stats for aggregate data
• Diagnostics — safedump doctor checks configuration integrity
• Config presets — configure(preset="production")

🔧 Extensible

• Custom serialization — register_serializer() for non-standard types
• Custom redaction — RedactionRule for domain-specific scrubbing
• before_capture hook — pre-processing before report generation
• on_crash hook — callback invoked after each capture (file notification, etc.)
• pytest integration — a report for every failing test (opt-in plugin)
• Click/Typer integration — @wrap_click() decorator

CLI Reference

safedump view [file]              # View crash report (Rich terminal)
safedump view --json [file]        # View as raw JSON
safedump view --html [output]      # Export as self-contained HTML
safedump list [--count] [--type] [--since] [--search]
safedump stats                     # Aggregate crash statistics
safedump doctor [--verbose]        # Diagnose common issues
safedump serve [--port] [--host]   # Start local web server (localhost only, no CORS)
safedump clean --older-than DAYS   # Delete old reports
safedump test                      # Write a test report (no install() needed)
safedump --dir ./crashes list      # Any command, another report directory ($SAFEDUMP_DIR also works)

Configuration

safedump.configure(
    preset="production",  # "development", "debug", "minimal"
    output_dir="./crashes",
    privacy_tier=1,  # 0=minimal, 1=default, 4=everything
    enable_entropy_detection=True,  # Shannon entropy-based secret detection
    compress=True,  # Gzip compressed crash reports
    on_crash=my_notification_handler,  # Callback after each capture
)

Documentation

Full documentation: muneer320.github.io/safedump.

Supported Platforms

Python versions: 3.9 through 3.13.

Contributing

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

Looking for a place to start? Check out open issues with the good first issue label.

License

MIT © Muneer Alam