memray: Profile Python Memory Allocations

Overview

Memray is a Python memory profiler for developers investigating where an application allocates memory, why its peak usage is high, or what may be causing a leak. Unlike sampling profilers, it traces function calls to show allocation call stacks, and can include allocations made in native extensions and the Python interpreter.

It can run a script or module from the command line, monitor allocations interactively, and turn captured data into reports such as flame graphs and tables. A Python API is available for profiling a chosen section of a running program.

Key Features

• Trace Python allocation call stacks rather than sampling them.
• Optionally include native C and C++ calls in profiles.
• Generate HTML flame graphs and tables, plus terminal tree, summary, and statistics reports.
• Inspect allocations interactively in a terminal while a program runs.
• Profile Python threads and native threads.
• Use a Tracker context manager to capture memory from selected code.
• Integrate allocation checks into tests using the separate pytest-memray plugin.

Use Cases

• Python application developers can trace a memory spike to the functions and call paths responsible.
• Teams investigating suspected leaks can capture a workload and examine repeated or unexpected allocations.
• Developers using extensions such as NumPy or pandas can enable native tracking to inspect allocations beyond Python code.
• Test maintainers can use pytest-memray to report allocation behavior or set memory limits for selected tests.
• Engineers working on long-running scripts can use live mode to inspect allocation patterns before a run finishes.

Project Facts

• Language: Python
• License: Apache-2.0
• Stars: 15.3k
• Forks: 470
• Topics: hacktoberfest, memory, memory-leak, memory-leak-detection, memory-profiler, profiler, python, python3
• Archived: No

Getting Started

Install from PyPI and profile a script:

python3 -m pip install memray
python3 -m memray run -o output.bin my_script.py
python3 -m memray flamegraph output.bin

See the README and documentation for module execution, native tracking, other reports, and API usage.

Considerations

• Memray supports Linux and macOS only; it cannot be installed on other platforms.
• It requires Python 3.9 or later.
• Memray includes a C extension. If a suitable binary wheel is unavailable, building from source requires system dependencies, including liblz4 and platform-specific libraries.
• Native tracking provides broader visibility into C and C++ allocations, but the README notes it is slower than tracking without native code.