---
id: pytest-memray
version: "1.10.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# pytest-memray — A simple plugin to use with pytest

License: permissive · Maintenance: active · Downloads: 2.9M/mo

## What it is and what it does

pytest-memray is a pytest plugin that wraps memray's memory profiling capabilities for test-driven memory debugging. It activates via the `--memray` CLI flag and tracks heap allocations throughout each test, then generates a summary report showing total memory used, allocation counts, and the call stacks responsible for the largest allocations. You can set per-test memory limits using the `limit_memory` marker and fail tests that exceed them; the plugin also supports tracking memory growth across runs with `--fail-on-increase` to catch regressions.

The plugin is designed for developers who need to catch memory leaks or excessive allocations in their test suite without manually instrumenting code. It outputs allocation histograms, identifies the functions and line numbers responsible for the biggest memory consumers, and can optionally show native C-level frames for deeper profiling. Configuration is available both via CLI flags and pytest INI settings.

Use it for:

- Catch memory leaks in unit tests by setting per-test memory limits and failing tests that exceed them.
- Identify which functions allocate the most memory during test execution for optimization.
- Track memory usage trends across test runs and fail if a test's memory footprint grows unexpectedly.
- Debug memory issues in CI/CD pipelines by generating detailed allocation reports for each test.
- Profile Python allocator behavior separately from native allocations using `--trace-python-allocators`.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A pytest plugin that integrates memray memory profiling into test runs, tracking memory allocations per test and reporting detailed allocation breakdowns.

Yes. The plugin is actively maintained, has low install friction, carries no security vulnerabilities, and solves a real problem—memory profiling in tests—that is otherwise tedious to set up. It's well-suited for projects concerned with memory efficiency or regression detection. The Apache-2.0 license is permissive and poses no barrier to adoption.

## Install

pip install pytest-memray
uv add pytest-memray
poetry add pytest-memray

## Installing pytest-memray

Before you install: Low friction install with a pure-Python wheel. Actively maintained with a release within the past week. Requires only memray and pytest as runtime dependencies, both widely available.

License in practice: Apache-2.0 permissive license allows use in commercial and private projects with minimal restrictions; you must include a copy of the license.

Quickstart:

pip install pytest-memray

pytest --memray tests/

# In a test file:
import pytest

@pytest.mark.limit_memory("100.0KiB")
def test_my_function():
    data = [i for i in range(10)]
    assert len(data) == 10

Requires Python 3.8 or higher; memray itself only runs on Linux and macOS.

Verify before relying:

- Whether the plugin works with pytest fixtures and parametrized tests without additional configuration.
- Performance overhead of native frame tracking and Python allocator tracing modes on large test suites.
- Compatibility with other pytest plugins that also instrument memory or test execution.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest memory profiling plugin, test memory tracking, memory allocation debugging, pytest memray integration, memory limit testing, allocation tracking pytest, memory regression detection, memory-profiling, pytest-plugin, performance-testing

[View on SkillFed](https://skillfed.io/packages/pytest-memray) · [View on PyPI](https://pypi.org/project/pytest-memray/)