{"library":"memray","title":"Memray: A Memory Profiler for Python Applications","description":"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.","status":"active","version":"1.19.2","language":"en","source_language":"en","source_url":"https://github.com/bloomberg/memray","tags":["memory-profiler","profiler","diagnostics","performance","memory-leak","debugging"],"install":[{"cmd":"pip install memray","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Required for rich text output in CLI and reporting.","package":"rich","optional":false},{"reason":"Optional dependency for the TUI (Textual User Interface) reporter.","package":"textual","optional":true}],"imports":[{"symbol":"Tracker","correct":"from memray import Tracker"}],"quickstart":{"code":"import memray\nimport os\n\ndef allocate_some_memory():\n    return [0] * 1024 * 1024 # Allocate 8MB\n\nif __name__ == \"__main__\":\n    output_file = \"memray_output.bin\"\n    with memray.Tracker(output_file):\n        my_data = allocate_some_memory()\n    print(f\"Memory profile saved to {output_file}\")\n    # To generate a flame graph, run from your shell:\n    # memray flamegraph memray_output.bin\n    # To programmatically create a report:\n    # from memray import Metadata, MemrayFile\n    # with MemrayFile(output_file) as f:\n    #    metadata = Metadata.parse_file(f)\n    #    print(f\"Total allocations: {len(f.iter_records())}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure appropriate build tools and Python development headers are installed. Check `memray`'s GitHub issues for known platform-specific quirks.","message":"Memray 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.","severity":"gotcha","affected_versions":"All versions, especially when building from source or on less common platforms."},{"fix":"Be aware of potential performance implications when using `memray` in performance-critical environments. Profile on representative workloads, but do not expect zero overhead.","message":"While 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.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"The `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.","severity":"breaking","affected_versions":"Versions 1.16.0+"},{"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.","message":"Memray 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.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"Older `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.","severity":"gotcha","affected_versions":"<1.19.2 when profiling Python 3.14+"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}