tracemalloc — Trace memory allocations — Python 3.9.25 documentation

to observe the small memory usage after the sum is computed as well as the peak memory usage during the computations:

importtracemalloctracemalloc.start()# Example code: compute a sum with a large temporary listlarge_sum=sum(list(range(100000)))first_size,first_peak=tracemalloc.get_traced_memory()tracemalloc.reset_peak()# Example code: compute a sum with a small temporary listsmall_sum=sum(list(range(1000)))second_size,second_peak=tracemalloc.get_traced_memory()print(f"{first_size=}, {first_peak=}")print(f"{second_size=}, {second_peak=}")Output:

first_size=664,first_peak=3592984second_size=804,second_peak=29704Using

ensured we could accurately record the peak during the computation of small_sum, even though it is much smaller than the overall peak size of memory blocks since the

call. Without the call to

, second_peak would still be the peak from the computation large_sum (that is, equal to first_peak). In this case, both peaks are much higher than the final memory usage, and which suggests we could optimise (by removing the unnecessary call to

list

, and writing sum(range(...))).

API

Functions

tracemalloc.clear_traces()

Clear traces of memory blocks allocated by Python.

See also

stop()

tracemalloc.get_object_traceback(obj)

Get the traceback where the Python object obj was allocated. Return a

Traceback

instance, or None if the

module is not tracing memory allocations or did not trace the allocation of the object.

See also

gc.get_referrers()

and

sys.getsizeof()

functions.

tracemalloc.get_traceback_limit()

Get the maximum number of frames stored in the traceback of a trace.

The

module must be tracing memory allocations to get the limit, otherwise an exception is raised.

The limit is set by the

function.

tracemalloc.get_traced_memory()

Get the current size and peak size of memory blocks traced by the

module as a tuple: (current:int,peak:int).

tracemalloc.reset_peak()

Set the peak size of memory blocks traced by the

module to the current size.

Do nothing if the

module is not tracing memory allocations.

This function only modifies the recorded peak size, and does not modify or clear any traces, unlike

clear_traces()

. Snapshots taken with

take_snapshot()

before a call to

can be meaningfully compared to snapshots taken after the call.

See also

get_traced_memory()

New in version 3.9.

tracemalloc.get_tracemalloc_memory()

Get the memory usage in bytes of the

module used to store traces of memory blocks. Return an

int

tracemalloc.is_tracing()

True if the

module is tracing Python memory allocations, False otherwise.

See also

and

stop()

functions.

tracemalloc.start(nframe: int=1)

Start tracing Python memory allocations: install hooks on Python memory allocators. Collected tracebacks of traces will be limited to nframe frames. By default, a trace of a memory block only stores the most recent frame: the limit is 1. nframe must be greater or equal to 1.

You can still read the original number of total frames that composed the traceback by looking at the

Traceback.total_nframe

attribute.

Storing more than 1 frame is only useful to compute statistics grouped by 'traceback' or to compute cumulative statistics: see the

Snapshot.compare_to()

and

Snapshot.statistics()

methods.

Storing more frames increases the memory and CPU overhead of the

module. Use the

get_tracemalloc_memory()

function to measure how much memory is used by the

module.

The

PYTHONTRACEMALLOC

environment variable (PYTHONTRACEMALLOC=NFRAME) and the

-X

tracemalloc=NFRAME command line option can be used to start tracing at startup.

See also

stop()

is_tracing()

and

get_traceback_limit()

functions.

tracemalloc.stop()

Stop tracing Python memory allocations: uninstall hooks on Python memory allocators. Also clears all previously collected traces of memory blocks allocated by Python.

Call

take_snapshot()

function to take a snapshot of traces before clearing them.

See also

is_tracing()

and

clear_traces()

functions.

tracemalloc.take_snapshot()

Take a snapshot of traces of memory blocks allocated by Python. Return a new

Snapshot

instance.

The snapshot does not include memory blocks allocated before the

module started to trace memory allocations.

Tracebacks of traces are limited to

get_traceback_limit()

frames. Use the nframe parameter of the

function to store more frames.

The

module must be tracing memory allocations to take a snapshot, see the