path: root/devdocs/python~3.12/library%2Ftracemalloc.html

 <span id="tracemalloc-trace-memory-allocations"></span><h1>tracemalloc — Trace memory allocations</h1> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/tracemalloc.py">Lib/tracemalloc.py</a></p>  <p>The tracemalloc module is a debug tool to trace memory blocks allocated by Python. It provides the following information:</p> <ul class="simple"> <li>Traceback where an object was allocated</li> <li>Statistics on allocated memory blocks per filename and per line number: total size, number and average size of allocated memory blocks</li> <li>Compute the differences between two snapshots to detect memory leaks</li> </ul> <p>To trace most memory blocks allocated by Python, the module should be started as early as possible by setting the <span class="target" id="index-0"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONTRACEMALLOC"><code>PYTHONTRACEMALLOC</code></a> environment variable to <code>1</code>, or by using <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X</code></a> <code>tracemalloc</code> command line option. The <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code>tracemalloc.start()</code></a> function can be called at runtime to start tracing Python memory allocations.</p> <p>By default, a trace of an allocated memory block only stores the most recent frame (1 frame). To store 25 frames at startup: set the <span class="target" id="index-1"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONTRACEMALLOC"><code>PYTHONTRACEMALLOC</code></a> environment variable to <code>25</code>, or use the <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X</code></a> <code>tracemalloc=25</code> command line option.</p> <section id="examples"> <h2>Examples</h2> <section id="display-the-top-10"> <h3>Display the top 10</h3> <p>Display the 10 files allocating the most memory:</p> <pre data-language="python">import tracemalloc

tracemalloc.start()

# ... run your application ...

snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('lineno')

print("[ Top 10 ]")
for stat in top_stats[:10]:
    print(stat)
</pre> <p>Example of output of the Python test suite:</p> <pre data-language="python">[ Top 10 ]
&lt;frozen importlib._bootstrap&gt;:716: size=4855 KiB, count=39328, average=126 B
&lt;frozen importlib._bootstrap&gt;:284: size=521 KiB, count=3199, average=167 B
/usr/lib/python3.4/collections/__init__.py:368: size=244 KiB, count=2315, average=108 B
/usr/lib/python3.4/unittest/case.py:381: size=185 KiB, count=779, average=243 B
/usr/lib/python3.4/unittest/case.py:402: size=154 KiB, count=378, average=416 B
/usr/lib/python3.4/abc.py:133: size=88.7 KiB, count=347, average=262 B
&lt;frozen importlib._bootstrap&gt;:1446: size=70.4 KiB, count=911, average=79 B
&lt;frozen importlib._bootstrap&gt;:1454: size=52.0 KiB, count=25, average=2131 B
&lt;string&gt;:5: size=49.7 KiB, count=148, average=344 B
/usr/lib/python3.4/sysconfig.py:411: size=48.0 KiB, count=1, average=48.0 KiB
</pre> <p>We can see that Python loaded <code>4855 KiB</code> data (bytecode and constants) from modules and that the <a class="reference internal" href="collections#module-collections" title="collections: Container datatypes"><code>collections</code></a> module allocated <code>244 KiB</code> to build <a class="reference internal" href="collections#collections.namedtuple" title="collections.namedtuple"><code>namedtuple</code></a> types.</p> <p>See <a class="reference internal" href="#tracemalloc.Snapshot.statistics" title="tracemalloc.Snapshot.statistics"><code>Snapshot.statistics()</code></a> for more options.</p> </section> <section id="compute-differences"> <h3>Compute differences</h3> <p>Take two snapshots and display the differences:</p> <pre data-language="python">import tracemalloc
tracemalloc.start()
# ... start your application ...

snapshot1 = tracemalloc.take_snapshot()
# ... call the function leaking memory ...
snapshot2 = tracemalloc.take_snapshot()

top_stats = snapshot2.compare_to(snapshot1, 'lineno')

print("[ Top 10 differences ]")
for stat in top_stats[:10]:
    print(stat)
</pre> <p>Example of output before/after running some tests of the Python test suite:</p> <pre data-language="python">[ Top 10 differences ]
&lt;frozen importlib._bootstrap&gt;:716: size=8173 KiB (+4428 KiB), count=71332 (+39369), average=117 B
/usr/lib/python3.4/linecache.py:127: size=940 KiB (+940 KiB), count=8106 (+8106), average=119 B
/usr/lib/python3.4/unittest/case.py:571: size=298 KiB (+298 KiB), count=589 (+589), average=519 B
&lt;frozen importlib._bootstrap&gt;:284: size=1005 KiB (+166 KiB), count=7423 (+1526), average=139 B
/usr/lib/python3.4/mimetypes.py:217: size=112 KiB (+112 KiB), count=1334 (+1334), average=86 B
/usr/lib/python3.4/http/server.py:848: size=96.0 KiB (+96.0 KiB), count=1 (+1), average=96.0 KiB
/usr/lib/python3.4/inspect.py:1465: size=83.5 KiB (+83.5 KiB), count=109 (+109), average=784 B
/usr/lib/python3.4/unittest/mock.py:491: size=77.7 KiB (+77.7 KiB), count=143 (+143), average=557 B
/usr/lib/python3.4/urllib/parse.py:476: size=71.8 KiB (+71.8 KiB), count=969 (+969), average=76 B
/usr/lib/python3.4/contextlib.py:38: size=67.2 KiB (+67.2 KiB), count=126 (+126), average=546 B
</pre> <p>We can see that Python has loaded <code>8173 KiB</code> of module data (bytecode and constants), and that this is <code>4428 KiB</code> more than had been loaded before the tests, when the previous snapshot was taken. Similarly, the <a class="reference internal" href="linecache#module-linecache" title="linecache: Provides random access to individual lines from text files."><code>linecache</code></a> module has cached <code>940 KiB</code> of Python source code to format tracebacks, all of it since the previous snapshot.</p> <p>If the system has little free memory, snapshots can be written on disk using the <a class="reference internal" href="#tracemalloc.Snapshot.dump" title="tracemalloc.Snapshot.dump"><code>Snapshot.dump()</code></a> method to analyze the snapshot offline. Then use the <a class="reference internal" href="#tracemalloc.Snapshot.load" title="tracemalloc.Snapshot.load"><code>Snapshot.load()</code></a> method reload the snapshot.</p> </section> <section id="get-the-traceback-of-a-memory-block"> <h3>Get the traceback of a memory block</h3> <p>Code to display the traceback of the biggest memory block:</p> <pre data-language="python">import tracemalloc

# Store 25 frames
tracemalloc.start(25)

# ... run your application ...

snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('traceback')

# pick the biggest memory block
stat = top_stats[0]
print("%s memory blocks: %.1f KiB" % (stat.count, stat.size / 1024))
for line in stat.traceback.format():
    print(line)
</pre> <p>Example of output of the Python test suite (traceback limited to 25 frames):</p> <pre data-language="python">903 memory blocks: 870.1 KiB
  File "&lt;frozen importlib._bootstrap&gt;", line 716
  File "&lt;frozen importlib._bootstrap&gt;", line 1036
  File "&lt;frozen importlib._bootstrap&gt;", line 934
  File "&lt;frozen importlib._bootstrap&gt;", line 1068
  File "&lt;frozen importlib._bootstrap&gt;", line 619
  File "&lt;frozen importlib._bootstrap&gt;", line 1581
  File "&lt;frozen importlib._bootstrap&gt;", line 1614
  File "/usr/lib/python3.4/doctest.py", line 101
    import pdb
  File "&lt;frozen importlib._bootstrap&gt;", line 284
  File "&lt;frozen importlib._bootstrap&gt;", line 938
  File "&lt;frozen importlib._bootstrap&gt;", line 1068
  File "&lt;frozen importlib._bootstrap&gt;", line 619
  File "&lt;frozen importlib._bootstrap&gt;", line 1581
  File "&lt;frozen importlib._bootstrap&gt;", line 1614
  File "/usr/lib/python3.4/test/support/__init__.py", line 1728
    import doctest
  File "/usr/lib/python3.4/test/test_pickletools.py", line 21
    support.run_doctest(pickletools)
  File "/usr/lib/python3.4/test/regrtest.py", line 1276
    test_runner()
  File "/usr/lib/python3.4/test/regrtest.py", line 976
    display_failure=not verbose)
  File "/usr/lib/python3.4/test/regrtest.py", line 761
    match_tests=ns.match_tests)
  File "/usr/lib/python3.4/test/regrtest.py", line 1563
    main()
  File "/usr/lib/python3.4/test/__main__.py", line 3
    regrtest.main_in_temp_cwd()
  File "/usr/lib/python3.4/runpy.py", line 73
    exec(code, run_globals)
  File "/usr/lib/python3.4/runpy.py", line 160
    "__main__", fname, loader, pkg_name)
</pre> <p>We can see that the most memory was allocated in the <a class="reference internal" href="importlib#module-importlib" title="importlib: The implementation of the import machinery."><code>importlib</code></a> module to load data (bytecode and constants) from modules: <code>870.1 KiB</code>. The traceback is where the <a class="reference internal" href="importlib#module-importlib" title="importlib: The implementation of the import machinery."><code>importlib</code></a> loaded data most recently: on the <code>import pdb</code> line of the <a class="reference internal" href="doctest#module-doctest" title="doctest: Test pieces of code within docstrings."><code>doctest</code></a> module. The traceback may change if a new module is loaded.</p> </section> <section id="pretty-top"> <h3>Pretty top</h3> <p>Code to display the 10 lines allocating the most memory with a pretty output, ignoring <code>&lt;frozen importlib._bootstrap&gt;</code> and <code>&lt;unknown&gt;</code> files:</p> <pre data-language="python">import linecache
import os
import tracemalloc

def display_top(snapshot, key_type='lineno', limit=10):
    snapshot = snapshot.filter_traces((
        tracemalloc.Filter(False, "&lt;frozen importlib._bootstrap&gt;"),
        tracemalloc.Filter(False, "&lt;unknown&gt;"),
    ))
    top_stats = snapshot.statistics(key_type)

    print("Top %s lines" % limit)
    for index, stat in enumerate(top_stats[:limit], 1):
        frame = stat.traceback[0]
        print("#%s: %s:%s: %.1f KiB"
              % (index, frame.filename, frame.lineno, stat.size / 1024))
        line = linecache.getline(frame.filename, frame.lineno).strip()
        if line:
            print('    %s' % line)

    other = top_stats[limit:]
    if other:
        size = sum(stat.size for stat in other)
        print("%s other: %.1f KiB" % (len(other), size / 1024))
    total = sum(stat.size for stat in top_stats)
    print("Total allocated size: %.1f KiB" % (total / 1024))

tracemalloc.start()

# ... run your application ...

snapshot = tracemalloc.take_snapshot()
display_top(snapshot)
</pre> <p>Example of output of the Python test suite:</p> <pre data-language="python">Top 10 lines
#1: Lib/base64.py:414: 419.8 KiB
    _b85chars2 = [(a + b) for a in _b85chars for b in _b85chars]
#2: Lib/base64.py:306: 419.8 KiB
    _a85chars2 = [(a + b) for a in _a85chars for b in _a85chars]
#3: collections/__init__.py:368: 293.6 KiB
    exec(class_definition, namespace)
#4: Lib/abc.py:133: 115.2 KiB
    cls = super().__new__(mcls, name, bases, namespace)
#5: unittest/case.py:574: 103.1 KiB
    testMethod()
#6: Lib/linecache.py:127: 95.4 KiB
    lines = fp.readlines()
#7: urllib/parse.py:476: 71.8 KiB
    for a in _hexdig for b in _hexdig}
#8: &lt;string&gt;:5: 62.0 KiB
#9: Lib/_weakrefset.py:37: 60.0 KiB
    self.data = set()
#10: Lib/base64.py:142: 59.8 KiB
    _b32tab2 = [a + b for a in _b32tab for b in _b32tab]
6220 other: 3602.8 KiB
Total allocated size: 5303.1 KiB
</pre> <p>See <a class="reference internal" href="#tracemalloc.Snapshot.statistics" title="tracemalloc.Snapshot.statistics"><code>Snapshot.statistics()</code></a> for more options.</p> <section id="record-the-current-and-peak-size-of-all-traced-memory-blocks"> <h4>Record the current and peak size of all traced memory blocks</h4> <p>The following code computes two sums like <code>0 + 1 + 2 + ...</code> inefficiently, by creating a list of those numbers. This list consumes a lot of memory temporarily. We can use <a class="reference internal" href="#tracemalloc.get_traced_memory" title="tracemalloc.get_traced_memory"><code>get_traced_memory()</code></a> and <a class="reference internal" href="#tracemalloc.reset_peak" title="tracemalloc.reset_peak"><code>reset_peak()</code></a> to observe the small memory usage after the sum is computed as well as the peak memory usage during the computations:</p> <pre data-language="python">import tracemalloc

tracemalloc.start()

# Example code: compute a sum with a large temporary list
large_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 list
small_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=}")
</pre> <p>Output:</p> <pre data-language="python">first_size=664, first_peak=3592984
second_size=804, second_peak=29704
</pre> <p>Using <a class="reference internal" href="#tracemalloc.reset_peak" title="tracemalloc.reset_peak"><code>reset_peak()</code></a> ensured we could accurately record the peak during the computation of <code>small_sum</code>, even though it is much smaller than the overall peak size of memory blocks since the <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code>start()</code></a> call. Without the call to <a class="reference internal" href="#tracemalloc.reset_peak" title="tracemalloc.reset_peak"><code>reset_peak()</code></a>, <code>second_peak</code> would still be the peak from the computation <code>large_sum</code> (that is, equal to <code>first_peak</code>). 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 <a class="reference internal" href="stdtypes#list" title="list"><code>list</code></a>, and writing <code>sum(range(...))</code>).</p> </section> </section> </section> <section id="api"> <h2>API</h2> <section id="functions"> <h3>Functions</h3> <dl class="py function"> <dt class="sig sig-object py" id="tracemalloc.clear_traces">
<code>tracemalloc.clear_traces()</code> </dt> <dd>
<p>Clear traces of memory blocks allocated by Python.</p> <p>See also <a class="reference internal" href="#tracemalloc.stop" title="tracemalloc.stop"><code>stop()</code></a>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="tracemalloc.get_object_traceback">
<code>tracemalloc.get_object_traceback(obj)</code> </dt> <dd>
<p>Get the traceback where the Python object <em>obj</em> was allocated. Return a <a class="reference internal" href="#tracemalloc.Traceback" title="tracemalloc.Traceback"><code>Traceback</code></a> instance, or <code>None</code> if the <a class="reference internal" href="#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a> module is not tracing memory allocations or did not trace the allocation of the object.</p> <p>See also <a class="reference internal" href="gc#gc.get_referrers" title="gc.get_referrers"><code>gc.get_referrers()</code></a> and <a class="reference internal" href="sys#sys.getsizeof" title="sys.getsizeof"><code>sys.getsizeof()</code></a> functions.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="tracemalloc.get_traceback_limit">
<code>tracemalloc.get_traceback_limit()</code> </dt> <dd>
<p>Get the maximum number of frames stored in the traceback of a trace.</p> <p>The <a class="reference internal" href="#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a> module must be tracing memory allocations to get the limit, otherwise an exception is raised.</p> <p>The limit is set by the <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code>start()</code></a> function.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="tracemalloc.get_traced_memory">
<code>tracemalloc.get_traced_memory()</code> </dt> <dd>
<p>Get the current size and peak size of memory blocks traced by the <a class="reference internal" href="#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a> module as a tuple: <code>(current: int, peak: int)</code>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="tracemalloc.reset_peak">
<code>tracemalloc.reset_peak()</code> </dt> <dd>
<p>Set the peak size of memory blocks traced by the <a class="reference internal" href="#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a> module to the current size.</p> <p>Do nothing if the <a class="reference internal" href="#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a> module is not tracing memory allocations.</p> <p>This function only modifies the recorded peak size, and does not modify or clear any traces, unlike <a class="reference internal" href="#tracemalloc.clear_traces" title="tracemalloc.clear_traces"><code>clear_traces()</code></a>. Snapshots taken with <a class="reference internal" href="#tracemalloc.take_snapshot" title="tracemalloc.take_snapshot"><code>take_snapshot()</code></a> before a call to <a class="reference internal" href="#tracemalloc.reset_peak" title="tracemalloc.reset_peak"><code>reset_peak()</code></a> can be meaningfully compared to snapshots taken after the call.</p> <p>See also <a class="reference internal" href="#tracemalloc.get_traced_memory" title="tracemalloc.get_traced_memory"><code>get_traced_memory()</code></a>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.9.</span></p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="tracemalloc.get_tracemalloc_memory">
<code>tracemalloc.get_tracemalloc_memory()</code> </dt> <dd>
<p>Get the memory usage in bytes of the <a class="reference internal" href="#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a> module used to store traces of memory blocks. Return an <a class="reference internal" href="functions#int" title="int"><code>int</code></a>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="tracemalloc.is_tracing">
<code>tracemalloc.is_tracing()</code> </dt> <dd>
<p><code>True</code> if the <a class="reference internal" href="#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a> module is tracing Python memory allocations, <code>False</code> otherwise.</p> <p>See also <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code>start()</code></a> and <a class="reference internal" href="#tracemalloc.stop" title="tracemalloc.stop"><code>stop()</code></a> functions.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="tracemalloc.start">
<code>tracemalloc.start(nframe: int = 1)</code> </dt> <dd>
<p>Start tracing Python memory allocations: install hooks on Python memory allocators. Collected tracebacks of traces will be limited to <em>nframe</em> frames. By default, a trace of a memory block only stores the most recent frame: the limit is <code>1</code>. <em>nframe</em> must be greater or equal to <code>1</code>.</p> <p>You can still read the original number of total frames that composed the traceback by looking at the <a class="reference internal" href="#tracemalloc.Traceback.total_nframe" title="tracemalloc.Traceback.total_nframe"><code>Traceback.total_nframe</code></a> attribute.</p> <p>Storing more than <code>1</code> frame is only useful to compute statistics grouped by <code>'traceback'</code> or to compute cumulative statistics: see the <a class="reference internal" href="#tracemalloc.Snapshot.compare_to" title="tracemalloc.Snapshot.compare_to"><code>Snapshot.compare_to()</code></a> and <a class="reference internal" href="#tracemalloc.Snapshot.statistics" title="tracemalloc.Snapshot.statistics"><code>Snapshot.statistics()</code></a> methods.</p> <p>Storing more frames increases the memory and CPU overhead of the <a class="reference internal" href="#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a> module. Use the <a class="reference internal" href="#tracemalloc.get_tracemalloc_memory" title="tracemalloc.get_tracemalloc_memory"><code>get_tracemalloc_memory()</code></a> function to measure how much memory is used by the <a class="reference internal" href="#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a> module.</p> <p>The <span class="target" id="index-2"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONTRACEMALLOC"><code>PYTHONTRACEMALLOC</code></a> environment variable (<code>PYTHONTRACEMALLOC=NFRAME</code>) and the <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X</code></a> <code>tracemalloc=NFRAME</code> command line option can be used to start tracing at startup.</p> <p>See also <a class="reference internal" href="#tracemalloc.stop" title="tracemalloc.stop"><code>stop()</code></a>, <a class="reference internal" href="#tracemalloc.is_tracing" title="tracemalloc.is_tracing"><code>is_tracing()</code></a> and <a class="reference internal" href="#tracemalloc.get_traceback_limit" title="tracemalloc.get_traceback_limit"><code>get_traceback_limit()</code></a> functions.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="tracemalloc.stop">
<code>tracemalloc.stop()</code> </dt> <dd>
<p>Stop tracing Python memory allocations: uninstall hooks on Python memory allocators. Also clears all previously collected traces of memory blocks allocated by Python.</p> <p>Call <a class="reference internal" href="#tracemalloc.take_snapshot" title="tracemalloc.take_snapshot"><code>take_snapshot()</code></a> function to take a snapshot of traces before clearing them.</p> <p>See also <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code>start()</code></a>, <a class="reference internal" href="#tracemalloc.is_tracing" title="tracemalloc.is_tracing"><code>is_tracing()</code></a> and <a class="reference internal" href="#tracemalloc.clear_traces" title="tracemalloc.clear_traces"><code>clear_traces()</code></a> functions.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="tracemalloc.take_snapshot">
<code>tracemalloc.take_snapshot()</code> </dt> <dd>
<p>Take a snapshot of traces of memory blocks allocated by Python. Return a new <a class="reference internal" href="#tracemalloc.Snapshot" title="tracemalloc.Snapshot"><code>Snapshot</code></a> instance.</p> <p>The snapshot does not include memory blocks allocated before the <a class="reference internal" href="#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a> module started to trace memory allocations.</p> <p>Tracebacks of traces are limited to <a class="reference internal" href="#tracemalloc.get_traceback_limit" title="tracemalloc.get_traceback_limit"><code>get_traceback_limit()</code></a> frames. Use the <em>nframe</em> parameter of the <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code>start()</code></a> function to store more frames.</p> <p>The <a class="reference internal" href="#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a> module must be tracing memory allocations to take a snapshot, see the <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code>start()</code></a> function.</p> <p>See also the <a class="reference internal" href="#tracemalloc.get_object_traceback" title="tracemalloc.get_object_traceback"><code>get_object_traceback()</code></a> function.</p> </dd>
</dl> </section> <section id="domainfilter"> <h3>DomainFilter</h3> <dl class="py class"> <dt class="sig sig-object py" id="tracemalloc.DomainFilter">
<code>class tracemalloc.DomainFilter(inclusive: bool, domain: int)</code> </dt> <dd>
<p>Filter traces of memory blocks by their address space (domain).</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.6.</span></p> </div> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.DomainFilter.inclusive">
<code>inclusive</code> </dt> <dd>
<p>If <em>inclusive</em> is <code>True</code> (include), match memory blocks allocated in the address space <a class="reference internal" href="#tracemalloc.DomainFilter.domain" title="tracemalloc.DomainFilter.domain"><code>domain</code></a>.</p> <p>If <em>inclusive</em> is <code>False</code> (exclude), match memory blocks not allocated in the address space <a class="reference internal" href="#tracemalloc.DomainFilter.domain" title="tracemalloc.DomainFilter.domain"><code>domain</code></a>.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.DomainFilter.domain">
<code>domain</code> </dt> <dd>
<p>Address space of a memory block (<code>int</code>). Read-only property.</p> </dd>
</dl> </dd>
</dl> </section> <section id="filter"> <h3>Filter</h3> <dl class="py class"> <dt class="sig sig-object py" id="tracemalloc.Filter">
<code>class tracemalloc.Filter(inclusive: bool, filename_pattern: str, lineno: int = None, all_frames: bool = False, domain: int = None)</code> </dt> <dd>
<p>Filter on traces of memory blocks.</p> <p>See the <a class="reference internal" href="fnmatch#fnmatch.fnmatch" title="fnmatch.fnmatch"><code>fnmatch.fnmatch()</code></a> function for the syntax of <em>filename_pattern</em>. The <code>'.pyc'</code> file extension is replaced with <code>'.py'</code>.</p> <p>Examples:</p> <ul class="simple"> <li>
<code>Filter(True, subprocess.__file__)</code> only includes traces of the <a class="reference internal" href="subprocess#module-subprocess" title="subprocess: Subprocess management."><code>subprocess</code></a> module</li> <li>
<code>Filter(False, tracemalloc.__file__)</code> excludes traces of the <a class="reference internal" href="#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a> module</li> <li>
<code>Filter(False, "&lt;unknown&gt;")</code> excludes empty tracebacks</li> </ul> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>The <code>'.pyo'</code> file extension is no longer replaced with <code>'.py'</code>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span>Added the <a class="reference internal" href="#tracemalloc.Filter.domain" title="tracemalloc.Filter.domain"><code>domain</code></a> attribute.</p> </div> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Filter.domain">
<code>domain</code> </dt> <dd>
<p>Address space of a memory block (<code>int</code> or <code>None</code>).</p> <p>tracemalloc uses the domain <code>0</code> to trace memory allocations made by Python. C extensions can use other domains to trace other resources.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Filter.inclusive">
<code>inclusive</code> </dt> <dd>
<p>If <em>inclusive</em> is <code>True</code> (include), only match memory blocks allocated in a file with a name matching <a class="reference internal" href="#tracemalloc.Filter.filename_pattern" title="tracemalloc.Filter.filename_pattern"><code>filename_pattern</code></a> at line number <a class="reference internal" href="#tracemalloc.Filter.lineno" title="tracemalloc.Filter.lineno"><code>lineno</code></a>.</p> <p>If <em>inclusive</em> is <code>False</code> (exclude), ignore memory blocks allocated in a file with a name matching <a class="reference internal" href="#tracemalloc.Filter.filename_pattern" title="tracemalloc.Filter.filename_pattern"><code>filename_pattern</code></a> at line number <a class="reference internal" href="#tracemalloc.Filter.lineno" title="tracemalloc.Filter.lineno"><code>lineno</code></a>.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Filter.lineno">
<code>lineno</code> </dt> <dd>
<p>Line number (<code>int</code>) of the filter. If <em>lineno</em> is <code>None</code>, the filter matches any line number.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Filter.filename_pattern">
<code>filename_pattern</code> </dt> <dd>
<p>Filename pattern of the filter (<code>str</code>). Read-only property.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Filter.all_frames">
<code>all_frames</code> </dt> <dd>
<p>If <em>all_frames</em> is <code>True</code>, all frames of the traceback are checked. If <em>all_frames</em> is <code>False</code>, only the most recent frame is checked.</p> <p>This attribute has no effect if the traceback limit is <code>1</code>. See the <a class="reference internal" href="#tracemalloc.get_traceback_limit" title="tracemalloc.get_traceback_limit"><code>get_traceback_limit()</code></a> function and <a class="reference internal" href="#tracemalloc.Snapshot.traceback_limit" title="tracemalloc.Snapshot.traceback_limit"><code>Snapshot.traceback_limit</code></a> attribute.</p> </dd>
</dl> </dd>
</dl> </section> <section id="frame"> <h3>Frame</h3> <dl class="py class"> <dt class="sig sig-object py" id="tracemalloc.Frame">
<code>class tracemalloc.Frame</code> </dt> <dd>
<p>Frame of a traceback.</p> <p>The <a class="reference internal" href="#tracemalloc.Traceback" title="tracemalloc.Traceback"><code>Traceback</code></a> class is a sequence of <a class="reference internal" href="#tracemalloc.Frame" title="tracemalloc.Frame"><code>Frame</code></a> instances.</p> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Frame.filename">
<code>filename</code> </dt> <dd>
<p>Filename (<code>str</code>).</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Frame.lineno">
<code>lineno</code> </dt> <dd>
<p>Line number (<code>int</code>).</p> </dd>
</dl> </dd>
</dl> </section> <section id="snapshot"> <h3>Snapshot</h3> <dl class="py class"> <dt class="sig sig-object py" id="tracemalloc.Snapshot">
<code>class tracemalloc.Snapshot</code> </dt> <dd>
<p>Snapshot of traces of memory blocks allocated by Python.</p> <p>The <a class="reference internal" href="#tracemalloc.take_snapshot" title="tracemalloc.take_snapshot"><code>take_snapshot()</code></a> function creates a snapshot instance.</p> <dl class="py method"> <dt class="sig sig-object py" id="tracemalloc.Snapshot.compare_to">
<code>compare_to(old_snapshot: Snapshot, key_type: str, cumulative: bool = False)</code> </dt> <dd>
<p>Compute the differences with an old snapshot. Get statistics as a sorted list of <a class="reference internal" href="#tracemalloc.StatisticDiff" title="tracemalloc.StatisticDiff"><code>StatisticDiff</code></a> instances grouped by <em>key_type</em>.</p> <p>See the <a class="reference internal" href="#tracemalloc.Snapshot.statistics" title="tracemalloc.Snapshot.statistics"><code>Snapshot.statistics()</code></a> method for <em>key_type</em> and <em>cumulative</em> parameters.</p> <p>The result is sorted from the biggest to the smallest by: absolute value of <a class="reference internal" href="#tracemalloc.StatisticDiff.size_diff" title="tracemalloc.StatisticDiff.size_diff"><code>StatisticDiff.size_diff</code></a>, <a class="reference internal" href="#tracemalloc.StatisticDiff.size" title="tracemalloc.StatisticDiff.size"><code>StatisticDiff.size</code></a>, absolute value of <a class="reference internal" href="#tracemalloc.StatisticDiff.count_diff" title="tracemalloc.StatisticDiff.count_diff"><code>StatisticDiff.count_diff</code></a>, <a class="reference internal" href="#tracemalloc.Statistic.count" title="tracemalloc.Statistic.count"><code>Statistic.count</code></a> and then by <a class="reference internal" href="#tracemalloc.StatisticDiff.traceback" title="tracemalloc.StatisticDiff.traceback"><code>StatisticDiff.traceback</code></a>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="tracemalloc.Snapshot.dump">
<code>dump(filename)</code> </dt> <dd>
<p>Write the snapshot into a file.</p> <p>Use <a class="reference internal" href="#tracemalloc.Snapshot.load" title="tracemalloc.Snapshot.load"><code>load()</code></a> to reload the snapshot.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="tracemalloc.Snapshot.filter_traces">
<code>filter_traces(filters)</code> </dt> <dd>
<p>Create a new <a class="reference internal" href="#tracemalloc.Snapshot" title="tracemalloc.Snapshot"><code>Snapshot</code></a> instance with a filtered <a class="reference internal" href="#tracemalloc.Snapshot.traces" title="tracemalloc.Snapshot.traces"><code>traces</code></a> sequence, <em>filters</em> is a list of <a class="reference internal" href="#tracemalloc.DomainFilter" title="tracemalloc.DomainFilter"><code>DomainFilter</code></a> and <a class="reference internal" href="#tracemalloc.Filter" title="tracemalloc.Filter"><code>Filter</code></a> instances. If <em>filters</em> is an empty list, return a new <a class="reference internal" href="#tracemalloc.Snapshot" title="tracemalloc.Snapshot"><code>Snapshot</code></a> instance with a copy of the traces.</p> <p>All inclusive filters are applied at once, a trace is ignored if no inclusive filters match it. A trace is ignored if at least one exclusive filter matches it.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span><a class="reference internal" href="#tracemalloc.DomainFilter" title="tracemalloc.DomainFilter"><code>DomainFilter</code></a> instances are now also accepted in <em>filters</em>.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="tracemalloc.Snapshot.load">
<code>classmethod load(filename)</code> </dt> <dd>
<p>Load a snapshot from a file.</p> <p>See also <a class="reference internal" href="#tracemalloc.Snapshot.dump" title="tracemalloc.Snapshot.dump"><code>dump()</code></a>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="tracemalloc.Snapshot.statistics">
<code>statistics(key_type: str, cumulative: bool = False)</code> </dt> <dd>
<p>Get statistics as a sorted list of <a class="reference internal" href="#tracemalloc.Statistic" title="tracemalloc.Statistic"><code>Statistic</code></a> instances grouped by <em>key_type</em>:</p> <table class="docutils align-default">  <thead> <tr>
<th class="head"><p>key_type</p></th> <th class="head"><p>description</p></th> </tr> </thead>  <tr>
<td><p><code>'filename'</code></p></td> <td><p>filename</p></td> </tr> <tr>
<td><p><code>'lineno'</code></p></td> <td><p>filename and line number</p></td> </tr> <tr>
<td><p><code>'traceback'</code></p></td> <td><p>traceback</p></td> </tr>  </table> <p>If <em>cumulative</em> is <code>True</code>, cumulate size and count of memory blocks of all frames of the traceback of a trace, not only the most recent frame. The cumulative mode can only be used with <em>key_type</em> equals to <code>'filename'</code> and <code>'lineno'</code>.</p> <p>The result is sorted from the biggest to the smallest by: <a class="reference internal" href="#tracemalloc.Statistic.size" title="tracemalloc.Statistic.size"><code>Statistic.size</code></a>, <a class="reference internal" href="#tracemalloc.Statistic.count" title="tracemalloc.Statistic.count"><code>Statistic.count</code></a> and then by <a class="reference internal" href="#tracemalloc.Statistic.traceback" title="tracemalloc.Statistic.traceback"><code>Statistic.traceback</code></a>.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Snapshot.traceback_limit">
<code>traceback_limit</code> </dt> <dd>
<p>Maximum number of frames stored in the traceback of <a class="reference internal" href="#tracemalloc.Snapshot.traces" title="tracemalloc.Snapshot.traces"><code>traces</code></a>: result of the <a class="reference internal" href="#tracemalloc.get_traceback_limit" title="tracemalloc.get_traceback_limit"><code>get_traceback_limit()</code></a> when the snapshot was taken.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Snapshot.traces">
<code>traces</code> </dt> <dd>
<p>Traces of all memory blocks allocated by Python: sequence of <a class="reference internal" href="#tracemalloc.Trace" title="tracemalloc.Trace"><code>Trace</code></a> instances.</p> <p>The sequence has an undefined order. Use the <a class="reference internal" href="#tracemalloc.Snapshot.statistics" title="tracemalloc.Snapshot.statistics"><code>Snapshot.statistics()</code></a> method to get a sorted list of statistics.</p> </dd>
</dl> </dd>
</dl> </section> <section id="statistic"> <h3>Statistic</h3> <dl class="py class"> <dt class="sig sig-object py" id="tracemalloc.Statistic">
<code>class tracemalloc.Statistic</code> </dt> <dd>
<p>Statistic on memory allocations.</p> <p><a class="reference internal" href="#tracemalloc.Snapshot.statistics" title="tracemalloc.Snapshot.statistics"><code>Snapshot.statistics()</code></a> returns a list of <a class="reference internal" href="#tracemalloc.Statistic" title="tracemalloc.Statistic"><code>Statistic</code></a> instances.</p> <p>See also the <a class="reference internal" href="#tracemalloc.StatisticDiff" title="tracemalloc.StatisticDiff"><code>StatisticDiff</code></a> class.</p> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Statistic.count">
<code>count</code> </dt> <dd>
<p>Number of memory blocks (<code>int</code>).</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Statistic.size">
<code>size</code> </dt> <dd>
<p>Total size of memory blocks in bytes (<code>int</code>).</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Statistic.traceback">
<code>traceback</code> </dt> <dd>
<p>Traceback where the memory block was allocated, <a class="reference internal" href="#tracemalloc.Traceback" title="tracemalloc.Traceback"><code>Traceback</code></a> instance.</p> </dd>
</dl> </dd>
</dl> </section> <section id="statisticdiff"> <h3>StatisticDiff</h3> <dl class="py class"> <dt class="sig sig-object py" id="tracemalloc.StatisticDiff">
<code>class tracemalloc.StatisticDiff</code> </dt> <dd>
<p>Statistic difference on memory allocations between an old and a new <a class="reference internal" href="#tracemalloc.Snapshot" title="tracemalloc.Snapshot"><code>Snapshot</code></a> instance.</p> <p><a class="reference internal" href="#tracemalloc.Snapshot.compare_to" title="tracemalloc.Snapshot.compare_to"><code>Snapshot.compare_to()</code></a> returns a list of <a class="reference internal" href="#tracemalloc.StatisticDiff" title="tracemalloc.StatisticDiff"><code>StatisticDiff</code></a> instances. See also the <a class="reference internal" href="#tracemalloc.Statistic" title="tracemalloc.Statistic"><code>Statistic</code></a> class.</p> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.StatisticDiff.count">
<code>count</code> </dt> <dd>
<p>Number of memory blocks in the new snapshot (<code>int</code>): <code>0</code> if the memory blocks have been released in the new snapshot.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.StatisticDiff.count_diff">
<code>count_diff</code> </dt> <dd>
<p>Difference of number of memory blocks between the old and the new snapshots (<code>int</code>): <code>0</code> if the memory blocks have been allocated in the new snapshot.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.StatisticDiff.size">
<code>size</code> </dt> <dd>
<p>Total size of memory blocks in bytes in the new snapshot (<code>int</code>): <code>0</code> if the memory blocks have been released in the new snapshot.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.StatisticDiff.size_diff">
<code>size_diff</code> </dt> <dd>
<p>Difference of total size of memory blocks in bytes between the old and the new snapshots (<code>int</code>): <code>0</code> if the memory blocks have been allocated in the new snapshot.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.StatisticDiff.traceback">
<code>traceback</code> </dt> <dd>
<p>Traceback where the memory blocks were allocated, <a class="reference internal" href="#tracemalloc.Traceback" title="tracemalloc.Traceback"><code>Traceback</code></a> instance.</p> </dd>
</dl> </dd>
</dl> </section> <section id="trace"> <h3>Trace</h3> <dl class="py class"> <dt class="sig sig-object py" id="tracemalloc.Trace">
<code>class tracemalloc.Trace</code> </dt> <dd>
<p>Trace of a memory block.</p> <p>The <a class="reference internal" href="#tracemalloc.Snapshot.traces" title="tracemalloc.Snapshot.traces"><code>Snapshot.traces</code></a> attribute is a sequence of <a class="reference internal" href="#tracemalloc.Trace" title="tracemalloc.Trace"><code>Trace</code></a> instances.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span>Added the <a class="reference internal" href="#tracemalloc.Trace.domain" title="tracemalloc.Trace.domain"><code>domain</code></a> attribute.</p> </div> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Trace.domain">
<code>domain</code> </dt> <dd>
<p>Address space of a memory block (<code>int</code>). Read-only property.</p> <p>tracemalloc uses the domain <code>0</code> to trace memory allocations made by Python. C extensions can use other domains to trace other resources.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Trace.size">
<code>size</code> </dt> <dd>
<p>Size of the memory block in bytes (<code>int</code>).</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Trace.traceback">
<code>traceback</code> </dt> <dd>
<p>Traceback where the memory block was allocated, <a class="reference internal" href="#tracemalloc.Traceback" title="tracemalloc.Traceback"><code>Traceback</code></a> instance.</p> </dd>
</dl> </dd>
</dl> </section> <section id="traceback"> <h3>Traceback</h3> <dl class="py class"> <dt class="sig sig-object py" id="tracemalloc.Traceback">
<code>class tracemalloc.Traceback</code> </dt> <dd>
<p>Sequence of <a class="reference internal" href="#tracemalloc.Frame" title="tracemalloc.Frame"><code>Frame</code></a> instances sorted from the oldest frame to the most recent frame.</p> <p>A traceback contains at least <code>1</code> frame. If the <code>tracemalloc</code> module failed to get a frame, the filename <code>"&lt;unknown&gt;"</code> at line number <code>0</code> is used.</p> <p>When a snapshot is taken, tracebacks of traces are limited to <a class="reference internal" href="#tracemalloc.get_traceback_limit" title="tracemalloc.get_traceback_limit"><code>get_traceback_limit()</code></a> frames. See the <a class="reference internal" href="#tracemalloc.take_snapshot" title="tracemalloc.take_snapshot"><code>take_snapshot()</code></a> function. The original number of frames of the traceback is stored in the <a class="reference internal" href="#tracemalloc.Traceback.total_nframe" title="tracemalloc.Traceback.total_nframe"><code>Traceback.total_nframe</code></a> attribute. That allows to know if a traceback has been truncated by the traceback limit.</p> <p>The <a class="reference internal" href="#tracemalloc.Trace.traceback" title="tracemalloc.Trace.traceback"><code>Trace.traceback</code></a> attribute is an instance of <a class="reference internal" href="#tracemalloc.Traceback" title="tracemalloc.Traceback"><code>Traceback</code></a> instance.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7: </span>Frames are now sorted from the oldest to the most recent, instead of most recent to oldest.</p> </div> <dl class="py attribute"> <dt class="sig sig-object py" id="tracemalloc.Traceback.total_nframe">
<code>total_nframe</code> </dt> <dd>
<p>Total number of frames that composed the traceback before truncation. This attribute can be set to <code>None</code> if the information is not available.</p> </dd>
</dl> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>The <a class="reference internal" href="#tracemalloc.Traceback.total_nframe" title="tracemalloc.Traceback.total_nframe"><code>Traceback.total_nframe</code></a> attribute was added.</p> </div> <dl class="py method"> <dt class="sig sig-object py" id="tracemalloc.Traceback.format">
<code>format(limit=None, most_recent_first=False)</code> </dt> <dd>
<p>Format the traceback as a list of lines. Use the <a class="reference internal" href="linecache#module-linecache" title="linecache: Provides random access to individual lines from text files."><code>linecache</code></a> module to retrieve lines from the source code. If <em>limit</em> is set, format the <em>limit</em> most recent frames if <em>limit</em> is positive. Otherwise, format the <code>abs(limit)</code> oldest frames. If <em>most_recent_first</em> is <code>True</code>, the order of the formatted frames is reversed, returning the most recent frame first instead of last.</p> <p>Similar to the <a class="reference internal" href="traceback#traceback.format_tb" title="traceback.format_tb"><code>traceback.format_tb()</code></a> function, except that <a class="reference internal" href="#tracemalloc.Traceback.format" title="tracemalloc.Traceback.format"><code>format()</code></a> does not include newlines.</p> <p>Example:</p> <pre data-language="python">print("Traceback (most recent call first):")
for line in traceback:
    print(line)
</pre> <p>Output:</p> <pre data-language="python">Traceback (most recent call first):
  File "test.py", line 9
    obj = Object()
  File "test.py", line 12
    tb = tracemalloc.get_object_traceback(f())
</pre> </dd>
</dl> </dd>
</dl> </section> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/library/tracemalloc.html" class="_attribution-link">https://docs.python.org/3.12/library/tracemalloc.html</a>
  </p>
</div>