LeakWatch

LeakWatch is a lightweight, easy-to-use Python library designed to help developers identify memory leaks and abnormal memory growth within Python applications.

Unlike traditional profilers that provide raw memory statistics, LeakWatch focuses on explaining:

• What is growing (which object types).
• Where it was created (source attribution / traceback).
• How fast it is growing (growth rate over time).
• Whether it is likely a memory leak (calculates a leak score).

Features

• Snapshot Comparison: Capture and compare memory states dynamically.
• Context Monitoring: Monitor code blocks or decorate functions using monitor.
• Source Attribution: Resolve file and line tracebacks for allocated objects.
• Leak Scoring: Intelligent heuristic to identify the probability of a leak.
• Report Export: Generate reports in JSON, Markdown, or beautiful dark-themed HTML.
• Command-Line Interface: Run your Python scripts under a monitor or export reports.

Installation

Install using pip:

pip install leakwatch-py

Quick Start

One-liner

from leakwatch import watch

watch()
# Your application code runs...

Snapshot Mode

from leakwatch import snapshot

snapshot("before")

# ... your code ...

snapshot("after")

Context Manager

from leakwatch import monitor

with monitor():
    run_application()

Generate Reports

from leakwatch import report

report(format='html', path='report.html')
report(format='json', path='report.json')
report(format='markdown', path='report.md')

CLI Usage

Monitor a script:

leakwatch run python app.py

Export a report:

leakwatch report --html
leakwatch report --json
leakwatch report --markdown

How It Works

LeakWatch uses Python's built-in tracemalloc and gc modules to:

1. Capture snapshots of memory allocations and object counts at different points in time.
2. Analyze growth patterns by comparing snapshots to identify which object types are increasing.
3. Compute a leak score using heuristics such as growth percentage, monotonic increase detection, and object classification (built-in vs custom types).
4. Attribute sources by resolving tracemalloc tracebacks to find where leaking objects were allocated.

License

MIT License - see LICENSE for details.

Author

Vicky — TrixSec