Memray: A Memory Profiler for Python Applications

1.19.2 · active · verified Sun Apr 05

Memray is a powerful and accurate memory profiler for Python applications, offering detailed insights into memory allocations, identifying leaks, and visualizing memory usage over time. It leverages low-level operating system features to accurately track memory, including native calls, and provides various output formats like flame graphs and interactive textual user interfaces. Currently at version 1.19.2, Memray is actively maintained with a consistent release cadence, frequently delivering bug fixes, performance enhancements, and support for newer Python features and operating system environments.

Warnings

gotcha Memray relies on C extensions and can utilize system debug symbols (e.g., `elfutils` on Linux) for native stack traces. This might require C compilers (`gcc`, `clang`) and Python development headers (`python3-dev`) if pre-built wheels are unavailable or for certain advanced features. Past versions have also addressed platform-specific issues like infinite loops on ARM Linux.
Fix: Ensure appropriate build tools and Python development headers are installed. Check `memray`'s GitHub issues for known platform-specific quirks.
gotcha While designed for low overhead, `memray` is a profiler and introduces some performance impact and memory usage to the profiled application. The overhead can vary significantly based on the application's allocation patterns and the system it's running on.
Fix: Be aware of potential performance implications when using `memray` in performance-critical environments. Profile on representative workloads, but do not expect zero overhead.
breaking The `memray` Textual User Interface (TUI) reporter has specific compatibility requirements with the `textual` library. `memray` v1.16.0 added support for Textual 2.0, and v1.17.0 for Textual 3.x. Using an incompatible `textual` version with `memray` might lead to runtime errors or incorrect display.
Fix: If using the TUI, ensure your `textual` dependency is within the supported range for your `memray` version. Consider installing `memray` with the `textual` extra (`pip install memray[textual]`) to automatically manage this dependency.
gotcha Memray primarily tracks memory *allocations* and deallocations, not necessarily the *live memory* held by objects that have already been allocated. This distinction is crucial for interpreting reports: a high allocation count doesn't always mean a memory leak if objects are properly deallocated.
Fix: Understand that `memray` helps identify *where* memory is being allocated. For tracking live object graphs, other tools like `objgraph` or `gc.get_objects()` might be complementary.
gotcha Older `memray` versions might not provide complete or accurate native stack traces for Python 3.14+ due to changes in its tail call interpreter. Version 1.19.2 specifically added support for this.
Fix: Upgrade to `memray` 1.19.2 or newer when profiling applications on Python 3.14 or later to ensure correct native stack trace analysis.

Install

pip install memray Install latest stable version

Imports

Tracker
```
from memray import Tracker
```

Quickstart

This quickstart demonstrates how to programmatically use `memray.Tracker` to profile a section of code and save the allocation data to a binary file. The output file can then be analyzed using `memray`'s CLI tools (e.g., `memray flamegraph`) or processed programmatically.

import memray
import os

def allocate_some_memory():
    return [0] * 1024 * 1024 # Allocate 8MB

if __name__ == "__main__":
    output_file = "memray_output.bin"
    with memray.Tracker(output_file):
        my_data = allocate_some_memory()
    print(f"Memory profile saved to {output_file}")
    # To generate a flame graph, run from your shell:
    # memray flamegraph memray_output.bin
    # To programmatically create a report:
    # from memray import Metadata, MemrayFile
    # with MemrayFile(output_file) as f:
    #    metadata = Metadata.parse_file(f)
    #    print(f"Total allocations: {len(f.iter_records())}")

view raw JSON →