memray

library1.20.0pypypi✓ verified 25d ago

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.

observability testing

pip install memray

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MEMRAY

memray

observabilitypythonv1.20.0

Install

4.1s avg

Import

180ms

Disk

71MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.20.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.190s · 73.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.1s · import 0.170s · 69MB

71MB installed

● package 71MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Tracker

✓ from memray import Tracker

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())}")

memray --version

Debug

Known issues

gotchaMemray 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.

affects: All versions, especially when building from source or on less common platforms.

gotchaWhile 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.

affects: All versions.

breakingThe `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.

affects: Versions 1.16.0+

gotchaMemray 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.

affects: All versions.

gotchaOlder `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.

affects: <1.19.2 when profiling Python 3.14+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'memray'

The 'memray' package is not installed in the Python environment being used, or the Python interpreter running the script is different from the one where 'memray' was installed.

fix

Install memray using pip: `pip install memray`. Ensure the correct Python interpreter is active or explicitly specified when running your application.

Could not attach to process. If your uid matches the uid of the target process, check the setting of /proc/sys/kernel/yama/ptrace_scope, or try again as the root user.

The `memray attach` command requires debugger privileges (PTRACE capability) to inject code into a running process, which is often restricted by default for security reasons on Linux systems or within containers.

fix

To allow attaching to processes owned by the same user, temporarily set `/proc/sys/kernel/yama/ptrace_scope` to `0` (e.g., `echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope`). For containers, ensure the `SYS_PTRACE` capability is explicitly enabled in the container's security context. Alternatively, run the `memray attach` command as the root user.

ImportError: cannot import name 'AllocationRecord' from 'memray._memray' (unknown location)

This error occurs when the `memray` package, specifically its compiled C extensions (`_memray.so`), is installed for one Python version but then used with a different Python version, particularly in environments like distroless containers where dependencies are copied.

fix

Ensure that `memray` is installed in the *same* Python environment and for the *exact same* Python version that will be used to run the application. When building container images, install `memray` directly within the final container environment using its target Python version.

memray run: error: argument --live: not allowed with argument -o/--output

The `memray run` command offers two mutually exclusive output modes: live reporting (e.g., `--live` or `--live-remote` for a TUI) and saving to a binary capture file (e.g., `-o` or `--output`). These cannot be used simultaneously.

fix

Choose either live reporting (`memray run --live-remote my_script.py`) or specify an output file (`memray run -o output.bin my_script.py`), but do not provide both `--live` (or `--live-remote`) and `-o` (or `--output`) in the same command.

Upgrade

Version history

1.20.0latest on PyPI · released Aug 7, 2026

Audit

Dependencies

richrequiredRequired for rich text output in CLI and reporting.

textualoptionalOptional dependency for the TUI (Textual User Interface) reporter.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bloomberg/memray ↗

packagehttps://pypi.org/project/memray/ ↗

homepagehttps://bloomberg.github.io/memray/ ↗