memray — Python Memory Profiler from Bloomberg

Introduction

memray is a memory profiler for Python developed by Bloomberg. It tracks every memory allocation made by Python code and C extensions using a native C-level tracing hook, then generates detailed reports including flame graphs, summary tables, and tree views. It helps developers find memory leaks, reduce peak memory usage, and understand allocation patterns in production workloads.

What memray Does

• Traces every malloc, realloc, and free call from Python and C extension code
• Records full Python call stacks at each allocation point for precise attribution
• Generates interactive HTML flame graphs showing where memory was allocated
• Supports live mode to watch memory usage in real time during execution
• Detects memory leaks by tracking allocations that were never freed

Architecture Overview

memray installs a C-level allocation hook that intercepts glibc memory functions (malloc, free, realloc, etc.) via LD_PRELOAD or a compile-time patching mechanism. Each allocation event is recorded along with the current Python call stack, captured using the CPython frame introspection API. Events are written to a compact binary file that can be analyzed offline. The reporter subsystem reads this file and generates various output formats: flame graphs, summary tables, tree views, and a live TUI dashboard.

Self-Hosting & Configuration

• Install with pip: pip install memray
• Profile a script: memray run script.py (writes a .bin results file)
• Generate a flame graph: memray flamegraph output.bin
• Use memray run --live for real-time terminal visualization
• Integrate with pytest via pytest-memray to set memory limits on tests

Key Features

• Tracks C extension allocations, not just Python-level objects
• Interactive HTML flame graphs with zoom, search, and filtering
• Live TUI mode for real-time memory monitoring during long runs
• Leak detection report that highlights allocations never freed
• pytest plugin to enforce memory budgets in CI pipelines

Comparison with Similar Tools

• tracemalloc — Python stdlib module; only tracks Python-level allocations, not C extensions
• Valgrind / Massif — powerful but very slow due to CPU emulation; memray runs at near-native speed
• py-spy — CPU sampling profiler for Python; memray focuses on memory allocation, not CPU time
• Fil — another Python memory profiler; memray provides richer reporting and live visualization
• Heaptrack — C/C++ heap profiler; memray adds Python stack integration for mixed Python/C codebases

FAQ

Q: Does memray slow down my program? A: It adds moderate overhead since it records every allocation. For most workloads the slowdown is 2-5x, much less than Valgrind.

Q: Can I use memray in production? A: Yes. You can attach to a running process using memray attach and detach without restarting.

Q: Does it work with NumPy, pandas, and other C extensions? A: Yes. memray hooks at the C allocator level, so allocations from any C extension are captured.

Q: What Python versions are supported? A: memray supports CPython 3.8 and above on Linux and macOS.

Sources

• https://github.com/bloomberg/memray
• https://bloomberg.github.io/memray/