+1
日增长
15,418
stars
489
forks
62
watchers
688
prs
291
issues
35
releases
README
---
Memray is a memory profiler for Python. It can track memory allocations in Python code, in native extension
modules, and in the Python interpreter itself. It can generate several different types of reports to help you
analyze the captured memory usage data. While commonly used as a CLI tool, it can also be used as a library to
perform more fine-grained profiling tasks.
Notable features:
- 🕵️♀️ Traces every function call so it can accurately represent the call stack, unlike sampling profilers.
- ℭ Also handles native calls in C/C++ libraries so the entire call stack is present in the results.
- 🏎 Blazing fast! Profiling slows the application only slightly. Tracking native code is somewhat slower,
but this can be enabled or disabled on demand.
- 📈 It can generate various reports about the collected memory usage data, like flame graphs.
- 🧵 Works with Python threads.
- 👽🧵 Works with native-threads (e.g. C++ threads in C extensions).
Memray can help with the following problems:
- Analyze allocations in applications to help discover the cause of high memory usage.
- Find memory leaks.
- Find hotspots in code that cause a lot of allocations.
Note
Memray only works on Linux and MacOS, and cannot be installed on other platforms.
Help us improve Memray!
We are constantly looking for feedback from our awesome community ❤️. If you
have used Memray to solve a problem, profile an application, find a memory leak
or anything else, please let us know! We would love to hear about your
experience and how Memray helped you.
Please, consider writing your story in the Success
Stories discussion page.
It really makes a difference!
Installation
Memray requires Python 3.9+ and can be easily installed using most common Python
packaging tools. We recommend installing the latest stable release from
PyPI with pip:
shell
python3 -m pip install memray
Notice that Memray contains a C extension so releases are distributed as binary
wheels as well as the source code. If a binary wheel is not available for your system
(Linux i686, x86-64, or aarch64, or macOS), you'll need to ensure that all the dependencies are satisfied on the
system where you are doing the installation.
Building from source
If you wish to build Memray from source you need the following binary dependencies in your system:
- libdebuginfod-dev (for Linux)
- libunwind (for Linux)
- liblz4
Check your package manager on how to install these dependencies (for example apt-get install build-essential python3-dev libdebuginfod-dev libunwind-dev liblz4-dev in Debian-based systems
or brew install lz4 in MacOS). Note that you may need to teach the compiler where to find the header and library files of the dependencies. For
example, in MacOS with brew you may need to run:
shell
export CPPFLAGS="-I$(brew --prefix lz4)/include" LDFLAGS="-L$(brew --prefix lz4)/lib -Wl,-rpath,$(brew --prefix lz4)/lib"
before installing memray. Check the documentation of your package manageTop issues
#577Making memray third-party allocator-aware25 comments · 2024-04-10#557Move the runner into a separate package with minimal dependencies10 comments · 2024-03-03#802Allocation record processing fails while trying to calculate the high watermark of a 1.5+ GB bin output file9 comments · 2025-07-30#779Disjoint stacks with embedded Python interpreter9 comments · 2025-06-10#829Attaching to a running compiled & cythonized app6 comments · 2025-09-25#997Stabilize temporal allocation records as a public API5 comments · 2026-08-14#39Remote monitoring configurable host5 comments · 2022-04-21#1007Make hook-reachable C++ independent from the process allocator4 comments · 2026-08-28
Discussions
#1088How to deal with large capture files?0 comments · 2026-11-13#992v1.20.00 comments · 2026-08-07#951Single flame graph output for multiprocessing?1 comments · 2026-06-15#869It seems that `memray attach` is not correctly tracking all new allocated memory.1 comments · 2026-01-21#868Mimalloc1 comments · 2026-01-15#864Memray for Windows?1 comments · 2025-12-30#858Tracker context vs --aggregate CLI option1 comments · 2025-11-24#852Using Memray for profiling distributed data processing pipelines.2 comments · 2025-11-13
Latest release
v1.20.0 v1.20.0 2026-08-07What's Changed Features - Add a light/dark theme toggle to the flame graph and table HTML reports, which respects the system color scheme and remembers the user's choice. (650) - Recognize deallocations performed with the free_sized and free_aligned_sized functions introduced in C23. (725) - Improve error reporting after a failure to record a memory capture by logging the reported error string and including it in the exception message. (747) - Add a --buffered-file-io option to memray run (and a buffered=True argument to memray.FileDestination) that writes the capture file using buffer