Repolode
Submit
bloomberg

bloomberg/memray

A memory profiler for Python that tracks allocations in Python code, native extensions, and the interpreter, with several report types.

View on GitHubWebsite
Stars
15,389
Forks
480
Open issues
37
Last commit
2 days ago

What is it?

Memray is a memory profiler for Python. It records memory allocations made by Python code, by native C/C++ extension modules, and by the Python interpreter itself, then turns the captured data into reports such as flame graphs, tables, trees and terminal summaries. It is most often run as a command-line tool with `memray run`, and it can also be used as a library through a Tracker context manager.

Unlike sampling profilers, Memray traces every function call, so call stacks are recorded accurately. Native tracking is opt-in with `--native` and adds the C/C++ frames to the results, which helps when extensions such as numpy or pandas are involved. A live mode shows allocations in a terminal interface while the program runs, and attach can start tracking an already-running process.

Memray targets common memory problems: finding the code responsible for high memory usage, locating leaks, and identifying hotspots that allocate heavily. It supports Python threads and native threads. It runs on Linux and macOS only, and requires Python 3.9 or newer. A pytest plugin, pytest-memray, is available as a separate project.

Key features

  • 01Traces every function call for accurate call stacks, unlike sampling profilers
  • 02Tracks allocations in Python code and native C/C++ extensions with --native
  • 03Generates flame graphs, HTML tables, terminal trees and summaries
  • 04Live terminal interface for inspecting allocations while a program runs
  • 05Can attach to an already-running Python process
  • 06Usable as a Python library via a Tracker context manager

Use cases

  • Finding the cause of high memory usage in a Python service or script
  • Locating memory leaks in long-running applications
  • Identifying code hotspots that allocate large amounts of memory
  • Profiling Python programs that depend on C extensions such as numpy or pandas

Quick start

  1. 1

    Install Memray from PyPI with pip

    python3 -m pip install memray
  2. 2

    Run your script under the profiler to record allocations

    python3 -m memray run my_script.py
  3. 3

    Generate an HTML flame graph from the results file

    memray flamegraph memray-my_script.py.2369.bin

Things to know

  • Works only on Linux and macOS; it cannot be installed on Windows.
  • Building from source requires system libraries such as libunwind, lz4 and libdebuginfod.

Topics

#python#memory-profiler#memory-leak#profiling#debugging#performance#native-extensions#hacktoberfest#memory#memory-leak-detection

FAQ

What is memray?
A memory profiler for Python that tracks allocations in Python code, native extensions, and the interpreter, with several report types. Memray is a memory profiler for Python. It records memory allocations made by Python code, by native C/C++ extension modules, and by the Python interpreter itself, then turns the captured data into reports such as flame graphs, tables, trees and terminal summaries. It is most often run as a command-line tool with `memray run`, and it can also be used as a library through a Tracker context manager.
Is memray free to use? What license does it have?
memray is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is memray still maintained?
Actively maintained. The last commit to memray was on Oct 19, 2026.
What can I use memray for?
Finding the cause of high memory usage in a Python service or script Locating memory leaks in long-running applications Identifying code hotspots that allocate large amounts of memory Profiling Python programs that depend on C extensions such as numpy or pandas
How do I install memray?
Install Memray from PyPI with pip: python3 -m pip install memray Run your script under the profiler to record allocations: python3 -m memray run my_script.py Generate an HTML flame graph from the results file: memray flamegraph memray-my_script.py.2369.bin
Where can I get memray?
The source code and installation instructions are on GitHub: https://github.com/bloomberg/memray

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects