Memray: a Python memory profiler that traces every allocation, on Linux and macOS only

What Memray solves, and who ends up using it

A Python process that grows without bound is hard to diagnose with CPU tooling. Allocation is not the same event as execution, and the frame that allocates the memory is often not the frame that holds the reference. Memray targets that gap. The README lists three problems it is built for: analyzing allocations to find the cause of high memory usage, finding memory leaks, and finding hotspots in code that cause a lot of allocations.

The intended reader is someone who already has a Python process, a reproduction, and a suspicion. Memray is not an always-on agent. It is a tool you point at a script or application for one run, then read the results. The README notes that it is commonly used as a CLI tool but can also be used as a library for finer-grained profiling, so the same capture format backs both an interactive investigation and an automated one. The project targets CPython 3.9 and later, and the classifiers list Linux and macOS as the supported operating systems.

Tracing every call instead of sampling the heap

The mechanism that separates Memray from a sampling profiler is stated plainly in the README: it traces every function call so it can accurately represent the call stack. Sampling tools wake up periodically and record whatever is on the stack at that instant, which means short-lived allocations between samples are invisible and stacks can be approximate. Memray records the allocation event itself.

The second half of the mechanism is native code. Memray handles calls into C and C++ libraries so the entire call stack appears in the results, and it works with Python threads and with native threads such as C++ threads inside C extensions. That is why a leak inside a compiled dependency shows up with a stack rather than as anonymous growth. The cost is acknowledged in the README: tracking native code is somewhat slower, and it can be enabled or disabled on demand.

Captures are written to a binary results file, and the reporter commands convert that file into a view. The README's own example runs a script to `output.bin` and then renders a flame graph from it. The available modes are `run`, `flamegraph`, `table`, `live`, `tree`, `parse`, `summary` and `stats`. The HTML reporters ship JavaScript assets: the repository's `package.json` lists d3, d3-flame-graph, plotly.js-dist-min, DataTables and Bootstrap, and the Makefile builds them with webpack into the reporter templates.

Installing Memray and capturing a first profile

The README recommends installing the latest stable release from PyPI with pip. Memray contains a C extension, so releases are distributed as binary wheels as well as source; on Linux x86/x64 and macOS a wheel should be available. The package requires Python 3.9 or later.

python3 -m pip install memray

If no binary wheel exists for your system, the README says you need the binary dependencies present before installing: libdebuginfod-dev and libunwind for Linux, and liblz4. On a Debian-based system the README gives this example.

apt-get install build-essential python3-dev libdebuginfod-dev libunwind-dev liblz4-dev

On macOS the README shows installing lz4 with Homebrew, and notes that you may need to point the compiler at its headers and libraries.

export CPPFLAGS="-I$(brew --prefix lz4)/include" LDFLAGS="-L$(brew --prefix lz4)/lib -Wl,-rpath,$(brew --prefix lz4)/lib"

For a first real use, run your script under the `run` subcommand and write a capture file. The README's example uses exactly this shape.

python3 -m memray run -o output.bin my_script.py

Then render the peak-memory flame graph from the capture. The command prints an HTML file path, and opening that file shows the flame graph for peak memory usage.

python3 -m memray flamegraph output.bin

If you would rather not leave the terminal, `memray tree` produces a tree view for peak memory usage and `memray table` produces an HTML table of all records in the peak. The README does not document a rollback procedure for a capture, because a capture is a file: deleting it is the rollback.

Where Memray stops being the right tool

The README carries an explicit note: Memray only works on Linux and macOS, and cannot be installed on other platforms. That is not a documentation gap, it is a boundary. A team whose production fleet is Windows cannot reproduce a leak in the environment where it happens, and container images based on a Windows base image are equally out of reach.

The second constraint is overhead. The README describes profiling as slowing the application only slightly, with native-code tracking slower still. That phrasing is relative, and the project does not publish a figure in the README. The practical consequence is that you should not assume a Memray run is free at production request rates, and you should not assume the overhead you measure on a microbenchmark transfers to a long-running service. Because the tool traces every call, the volume of records scales with allocation activity, not with wall-clock time.

The third case is simpler: if your question is about CPU time, Memray is the wrong instrument. It captures memory usage. A CPU profiler answers a different question and the reports will not overlap.

Memray against a sampling memory profiler

The obvious alternative is a sampling memory profiler, the category that includes tools which periodically snapshot allocation state rather than instrumenting every allocation. The difference is in what you can conclude from the output. A sampling profiler gives you a statistical picture and a bounded cost that you can dial down by lowering the sampling rate. Memray gives you a complete record of allocation events with full call stacks, including stacks that pass through C extensions, and pays for it with per-call tracing overhead.

That distinction decides the choice. If you need to know that a specific line inside a Cython or C extension is responsible for growth, sampling is likely to miss it or attribute it to a wrapper. If you need a cheap continuous signal in a latency-sensitive service, the sampling approach is the one that survives contact with production. Memray's own reporters are the other half of the comparison: flame graph, table, tree and a live terminal view are all derived from one binary capture, so the same run can be re-read several ways without re-running the program.

Licence, releases and the cost of keeping up

Memray is licensed under Apache-2.0, and the `pyproject.toml` declares `license = { text = "Apache 2.0" }` with the classifier `License :: OSI Approved :: Apache Software License`. For most users that means permissive use with the usual notice and attribution conditions; the LICENSE file at the repository root is the authoritative text, and this is not legal advice.

The maintenance picture is visible from the repository itself. The last push was on 2026-09-21, and the most recent release is v1.20.0, dated 2026-08-07, following v1.19.3 on 2026-04-08 and v1.19.2 on 2026-03-13. The `pyproject.toml` classifiers list CPython 3.9 through 3.15, so an upgrade path exists but you should expect to reinstall or rebuild when your interpreter moves. Because the package ships a C extension, the upgrade cost is not just a version bump: if you installed from source, a new Python version means satisfying libunwind, liblz4 and libdebuginfod-dev again. The `runtime` dependencies are small (jinja2, rich, textual), so the Python-level surface is not where the maintenance burden sits.

Editorial conclusion

Adopt Memray if you are debugging high memory usage or a suspected leak in a CPython application that runs on Linux or macOS and you need call stacks that include C extensions. Skip it if you must profile on Windows, or if a sampling profiler's lower overhead already answers your question. Before committing, run `python3 -m memray run -o output.bin` on the workload you care about and check the capture size, then confirm the reporter you need (`flamegraph`, `table`, `tree` or `live`) produces the view you expect.

Frequently asked questions

Official sources

1. bloomberg/memray on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases