Usage¶

Installation¶

This plugin can be installed using pip:

pip install pytest-memray

pytest-memray is a pytest plugin. It is enabled when you pass --memray to pytest:

pytest tests/ --memray

Allocation tracking¶

By default, the plugin will track allocations at the high watermark in all tests. This information is reported after tests run ends:

$ pytest --memray /w/demo 
/v/share/python3.13/site-packages/pytest_cython/__init__.py:2: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  from pkg_resources import get_distribution
Traceback (most recent call last):
  File "/v/bin/pytest", line 8, in <module>
    sys.exit(console_main())
             ~~~~~~~~~~~~^^
  File "/v/share/python3.13/site-packages/_pytest/config/__init__.py", line 201, in console_main
    code = main()
  File "/v/share/python3.13/site-packages/_pytest/config/__init__.py", line 156, in main
    config = _prepareconfig(args, plugins)
  File "/v/share/python3.13/site-packages/_pytest/config/__init__.py", line 342, in _prepareconfig
    config = pluginmanager.hook.pytest_cmdline_parse(
        pluginmanager=pluginmanager, args=args
    )
  File "/v/share/python3.13/site-packages/pluggy/_hooks.py", line 513, in __call__
    return self._hookexec(self.name, self._hookimpls.copy(), kwargs, firstresult)
           ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/v/share/python3.13/site-packages/pluggy/_manager.py", line 120, in _hookexec
    return self._inner_hookexec(hook_name, methods, kwargs, firstresult)
           ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/v/share/python3.13/site-packages/pluggy/_callers.py", line 139, in _multicall
    raise exception.with_traceback(exception.__traceback__)
  File "/v/share/python3.13/site-packages/pluggy/_callers.py", line 122, in _multicall
    teardown.throw(exception)  # type: ignore[union-attr]
    ~~~~~~~~~~~~~~^^^^^^^^^^^
  File "/v/share/python3.13/site-packages/_pytest/helpconfig.py", line 112, in pytest_cmdline_parse
    config = yield
             ^^^^^
  File "/v/share/python3.13/site-packages/pluggy/_callers.py", line 103, in _multicall
    res = hook_impl.function(*args)
  File "/v/share/python3.13/site-packages/_pytest/config/__init__.py", line 1146, in pytest_cmdline_parse
    self.parse(args)
    ~~~~~~~~~~^^^^^^
  File "/v/share/python3.13/site-packages/_pytest/config/__init__.py", line 1527, in parse
    self._preparse(args, addopts=addopts)
    ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
  File "/v/share/python3.13/site-packages/_pytest/config/__init__.py", line 1417, in _preparse
    self.known_args_namespace = self._parser.parse_known_args(
                                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
        args, namespace=copy.copy(self.known_args_namespace)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/v/share/python3.13/site-packages/_pytest/config/argparsing.py", line 155, in parse_known_args
    return self.parse_known_and_unknown_args(args, namespace=namespace)[0]
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/v/share/python3.13/site-packages/_pytest/config/argparsing.py", line 169, in parse_known_and_unknown_args
    optparser = self._getparser()
  File "/v/share/python3.13/site-packages/_pytest/config/argparsing.py", line 128, in _getparser
    arggroup.add_argument(*n, **a)
    ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/v/lib64/python3.13/argparse.py", line 1517, in add_argument
    return self._add_action(action)
           ~~~~~~~~~~~~~~~~^^^^^^^^
  File "/v/lib64/python3.13/argparse.py", line 1724, in _add_action
    action = super(_ArgumentGroup, self)._add_action(action)
  File "/v/lib64/python3.13/argparse.py", line 1531, in _add_action
    self._check_conflict(action)
    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^
  File "/v/lib64/python3.13/argparse.py", line 1673, in _check_conflict
    conflict_handler(action, confl_optionals)
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/v/lib64/python3.13/argparse.py", line 1682, in _handle_conflict_error
    raise ArgumentError(action, message % conflict_string)
argparse.ArgumentError: argument --benchmark-columns: conflicting option string: --benchmark-columns

Markers¶

This plugin provides markers that can be used to enforce additional checks and validations on tests.

pytest.mark.limit_memory(memory_limit: str, current_thread_only: bool = False)¶

Fail the execution of the test if the test allocates more peak memory than allowed.

When this marker is applied to a test, it will cause the test to fail if the execution of the test allocates more memory (at the peak/high watermark) than allowed. It takes a single argument with a string indicating the maximum memory that the test can allocate.

The format for the string is <NUMBER> ([KMGTP]B|B). The marker will raise ValueError if the string format cannot be parsed correctly.

If the optional keyword-only argument current_thread_only is set to True, the plugin will only track memory allocations made by the current thread and all other allocations will be ignored.

Warning

As the Python interpreter has its own object allocator it’s possible that memory is not immediately released to the system when objects are deleted, so tests using this marker may need to give some room to account for this.

Example of usage:

@pytest.mark.limit_memory("24 MB")
def test_foobar():
    pass  # do some stuff that allocates memory

pytest.mark.limit_leaks(location_limit: str, filter_fn: LeaksFilterFunction | None = None, current_thread_only: bool = False)¶

Fail the execution of the test if any call stack in the test leaks more memory than allowed.

Important

To detect leaks, Memray needs to intercept calls to the Python allocators and report native call frames. This is adds significant overhead, and will slow your test down.

When this marker is applied to a test, the plugin will analyze the memory allocations that are made while the test body runs and not freed by the time the test body function returns. It groups them by the call stack leading to the allocation, and sums the amount leaked by each distinct call stack. If the total amount leaked from any particular call stack is greater than the configured limit, the test will fail.

Important

It’s recommended to run your API or code in a loop when utilizing this plugin. This practice helps in distinguishing genuine leaks from the “noise” generated by internal caches and other incidental allocations.

The format for the string is <NUMBER> ([KMGTP]B|B). The marker will raise ValueError if the string format cannot be parsed correctly.

The marker also takes an optional keyword-only argument filter_fn. This argument represents a filtering function that will be called once for each distinct call stack that leaked more memory than allowed. If it returns True, leaks from that location will be included in the final report. If it returns False, leaks associated with the stack it was called with will be ignored. If all leaks are ignored, the test will not fail. This can be used to discard any known false positives.

If the optional keyword-only argument current_thread_only is set to True, the plugin will only track memory allocations made by the current thread and all other allocations will be ignored.

Tip

You can pass the --memray-bin-path argument to pytest to specify a directory where Memray will store the binary files with the results. You can then use the memray CLI to further investigate the allocations and the leaks using any Memray reporters you’d like. Check the memray docs for more information.

Example of usage:

@pytest.mark.limit_leaks("1 MB")
def test_foobar():
    # Run the function we're testing in a loop to ensure
    # we can differentiate leaks from memory held by
    # caches inside the Python interpreter.
    for _ in range(100):
        do_some_stuff()

Warning

It is very challenging to write tests that do not “leak” memory in some way, due to circumstances beyond your control.

There are many caches inside the Python interpreter itself. Just a few examples:

The re module caches compiled regexes.
The logging module caches whether a given log level is active for a particular logger the first time you try to log something at that level.
A limited number of objects of certain heavily used types are cached for reuse so that object.__new__ does not always need to allocate memory.
The mapping from bytecode index to line number for each Python function is cached when it is first needed.

There are many more such caches. Also, within pytest, any message that you log or print is captured, so that it can be included in the output if the test fails.

Memray sees these all as “leaks”, because something was allocated while the test ran and it was not freed by the time the test body finished. We don’t know that it’s due to an implementation detail of the interpreter or pytest that the memory wasn’t freed. Morever, because these caches are implementation details, the amount of memory allocated, the call stack of the allocation, and even the allocator that was used can all change from one version to another.

Because of this, you will almost certainly need to allow some small amount of leaked memory per call stack, or use the filter_fn argument to filter out false-positive leak reports based on the call stack they’re associated with.