pytest-memray

1.8.0 · active · verified Sat Apr 11

pytest-memray is a pytest plugin for easy integration of memray, a powerful memory profiler for Python. It allows developers to analyze memory allocations, detect memory leaks, and identify memory-intensive hotspots directly within their pytest test suite. The current version, 1.8.0, supports Python 3.8 and higher, and is actively maintained with regular releases.

Warnings

gotcha Python's internal object allocators, caches (e.g., `re`, `logging`), and pytest's output capturing can result in reported allocations that are not true application-level memory leaks. Interpreting memory reports requires understanding these internal behaviors.
Fix: Account for Python and pytest internal allocations. Run tests in a loop or with `current_thread_only=True` in markers for clearer leak detection. Consider `memray`'s own documentation on 'false positives'.
gotcha The underlying `memray` library, which `pytest-memray` integrates with, primarily supports Linux and macOS. While the Python package can be installed elsewhere, full functionality and development might be limited or require a POSIX-compliant system, especially for native-level tracking.
Fix: Run tests and profiling on Linux or macOS environments for optimal results and full feature access.
gotcha Prior to version 1.3.2, `pytest-memray` had compatibility issues with `pytest-xdist` when running tests in parallel, potentially leading to incorrect or failed memory tracking. Users on older versions might experience instability.
Fix: Upgrade to `pytest-memray` version 1.3.2 or newer to ensure proper compatibility with `pytest-xdist`.
gotcha Using very long test names or file paths can lead to `OSError` exceptions due to file system limitations when `memray` attempts to write its binary capture files. This can prevent reports from being generated.
Fix: Keep test file paths and test function names reasonably short, especially if encountering `OSError` related to filename length.
breaking The `limit_memory` and `limit_leaks` markers in versions prior to 1.6.0 tracked all memory allocations across all threads. Version 1.6.0 introduced a `current_thread_only=True` keyword argument to these markers, allowing more precise tracking of allocations solely within the test's thread. Existing tests on older versions might report higher memory usage if other threads were active.
Fix: Upgrade to `pytest-memray` 1.6.0 or newer and consider adding `current_thread_only=True` to your markers for more focused memory tracking, if appropriate for your tests.

Install

pip install pytest-memray Install stable version

Imports

pytest.mark.limit_memory
```
import pytest

@pytest.mark.limit_memory('100 MB')
def test_something_memory_intensive():
    # ... test code ...
```
pytest-memray is primarily used via pytest command-line flags and markers; direct module imports are not common for end-users.
pytest.mark.limit_leaks
```
import pytest

@pytest.mark.limit_leaks('5 MB')
def test_something_that_might_leak():
    # ... test code ...
```
pytest-memray is primarily used via pytest command-line flags and markers; direct module imports are not common for end-users.

Quickstart

To activate `pytest-memray` during a test run, simply add the `--memray` flag to your `pytest` command. For granular control and enforcement within tests, use markers like `@pytest.mark.limit_memory` to set a peak memory limit or `@pytest.mark.limit_leaks` to detect memory leaks. If a test exceeds its limit, `pytest` will report a failure.

import pytest

@pytest.mark.limit_memory('24 MB')
def test_foobar():
    data = [i for i in range(1_000_000)] # Allocates ~8MB
    assert len(data) == 1_000_000

# To run this test with memory profiling:
# pytest --memray your_test_file.py

view raw JSON →