parthtamu/rag-code-assistant
0
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4 <head>5 <meta charset="utf-8" />6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="tracemalloc — Trace memory allocations" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/tracemalloc.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/tracemalloc.py The tracemalloc module is a debug tool to trace memory blocks allocated by Python. It provides the following information: Traceback where an object was allocated, St..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_tracemalloc_eb56fb08.png" />15<meta property="og:image:alt" content="Source code: Lib/tracemalloc.py The tracemalloc module is a debug tool to trace memory blocks allocated by Python. It provides the following information: Traceback where an object was allocated, St..." />16<meta name="description" content="Source code: Lib/tracemalloc.py The tracemalloc module is a debug tool to trace memory blocks allocated by Python. It provides the following information: Traceback where an object was allocated, St..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>tracemalloc — Trace memory allocations — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="Software Packaging and Distribution" href="distribution.html" />43 <link rel="prev" title="trace — Trace or track Python statement execution" href="trace.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/tracemalloc.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> — Trace memory allocations</a><ul>108<li><a class="reference internal" href="#examples">Examples</a><ul>109<li><a class="reference internal" href="#display-the-top-10">Display the top 10</a></li>110<li><a class="reference internal" href="#compute-differences">Compute differences</a></li>111<li><a class="reference internal" href="#get-the-traceback-of-a-memory-block">Get the traceback of a memory block</a></li>112<li><a class="reference internal" href="#pretty-top">Pretty top</a><ul>113<li><a class="reference internal" href="#record-the-current-and-peak-size-of-all-traced-memory-blocks">Record the current and peak size of all traced memory blocks</a></li>114</ul>115</li>116</ul>117</li>118<li><a class="reference internal" href="#api">API</a><ul>119<li><a class="reference internal" href="#functions">Functions</a></li>120<li><a class="reference internal" href="#domainfilter">DomainFilter</a></li>121<li><a class="reference internal" href="#filter">Filter</a></li>122<li><a class="reference internal" href="#frame">Frame</a></li>123<li><a class="reference internal" href="#snapshot">Snapshot</a></li>124<li><a class="reference internal" href="#statistic">Statistic</a></li>125<li><a class="reference internal" href="#statisticdiff">StatisticDiff</a></li>126<li><a class="reference internal" href="#trace">Trace</a></li>127<li><a class="reference internal" href="#traceback">Traceback</a></li>128</ul>129</li>130</ul>131</li>132</ul>133 134 </div>135 <div>136 <h4>Previous topic</h4>137 <p class="topless"><a href="trace.html"138 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">trace</span></code> — Trace or track Python statement execution</a></p>139 </div>140 <div>141 <h4>Next topic</h4>142 <p class="topless"><a href="distribution.html"143 title="next chapter">Software Packaging and Distribution</a></p>144 </div>145 <script>146 document.addEventListener('DOMContentLoaded', () => {147 const title = document.querySelector('meta[property="og:title"]').content;148 const elements = document.querySelectorAll('.improvepage');149 const pageurl = window.location.href.split('?')[0];150 elements.forEach(element => {151 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));152 url.searchParams.set('pagetitle', title);153 url.searchParams.set('pageurl', pageurl);154 url.searchParams.set('pagesource', "library/tracemalloc.rst");155 element.href = url.toString();156 });157 });158 </script>159 <div role="note" aria-label="source link">160 <h3>This page</h3>161 <ul class="this-page-menu">162 <li><a href="../bugs.html">Report a bug</a></li>163 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>164 <li>165 <a href="https://github.com/python/cpython/blob/main/Doc/library/tracemalloc.rst?plain=1"166 rel="nofollow">Show source167 </a>168 </li>169 170 </ul>171 </div>172 </nav>173 </div>174</div>175 176 177 <div class="related" role="navigation" aria-label="Related">178 <h3>Navigation</h3>179 <ul>180 <li class="right" style="margin-right: 10px">181 <a href="../genindex.html" title="General Index"182 accesskey="I">index</a></li>183 <li class="right" >184 <a href="../py-modindex.html" title="Python Module Index"185 >modules</a> |</li>186 <li class="right" >187 <a href="distribution.html" title="Software Packaging and Distribution"188 accesskey="N">next</a> |</li>189 <li class="right" >190 <a href="trace.html" title="trace — Trace or track Python statement execution"191 accesskey="P">previous</a> |</li>192 193 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>194 <li><a href="https://www.python.org/">Python</a> »</li>195 <li class="switchers">196 <div class="language_switcher_placeholder"></div>197 <div class="version_switcher_placeholder"></div>198 </li>199 <li>200 201 </li>202 <li id="cpython-language-and-version">203 <a href="../index.html">3.15.0a6 Documentation</a> »204 </li>205 206 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>207 <li class="nav-item nav-item-2"><a href="debug.html" accesskey="U">Debugging and profiling</a> »</li>208 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> — Trace memory allocations</a></li>209 <li class="right">210 211 212 <div class="inline-search" role="search">213 <form class="inline-search" action="../search.html" method="get">214 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">215 <input type="submit" value="Go">216 </form>217 </div>218 |219 </li>220 <li class="right">221<label class="theme-selector-label">222 Theme223 <select class="theme-selector" oninput="activateTheme(this.value)">224 <option value="auto" selected>Auto</option>225 <option value="light">Light</option>226 <option value="dark">Dark</option>227 </select>228</label> |</li>229 230 </ul>231 </div> 232 233 <div class="document">234 <div class="documentwrapper">235 <div class="bodywrapper">236 <div class="body" role="main">237 238 <section id="module-tracemalloc">239<span id="tracemalloc-trace-memory-allocations"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> — Trace memory allocations<a class="headerlink" href="#module-tracemalloc" title="Link to this heading">¶</a></h1>240<div class="versionadded">241<p><span class="versionmodified added">Added in version 3.4.</span></p>242</div>243<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/tracemalloc.py">Lib/tracemalloc.py</a></p>244<hr class="docutils" />245<p>The tracemalloc module is a debug tool to trace memory blocks allocated by246Python. It provides the following information:</p>247<ul class="simple">248<li><p>Traceback where an object was allocated</p></li>249<li><p>Statistics on allocated memory blocks per filename and per line number:250total size, number and average size of allocated memory blocks</p></li>251<li><p>Compute the differences between two snapshots to detect memory leaks</p></li>252</ul>253<p>To trace most memory blocks allocated by Python, the module should be started254as early as possible by setting the <span class="target" id="index-0"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONTRACEMALLOC"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONTRACEMALLOC</span></code></a> environment255variable to <code class="docutils literal notranslate"><span class="pre">1</span></code>, or by using <a class="reference internal" href="../using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span></code></a> <code class="docutils literal notranslate"><span class="pre">tracemalloc</span></code> command line256option. The <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code class="xref py py-func docutils literal notranslate"><span class="pre">tracemalloc.start()</span></code></a> function can be called at runtime to257start tracing Python memory allocations.</p>258<p>By default, a trace of an allocated memory block only stores the most recent259frame (1 frame). To store 25 frames at startup: set the260<span class="target" id="index-1"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONTRACEMALLOC"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONTRACEMALLOC</span></code></a> environment variable to <code class="docutils literal notranslate"><span class="pre">25</span></code>, or use the261<a class="reference internal" href="../using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span></code></a> <code class="docutils literal notranslate"><span class="pre">tracemalloc=25</span></code> command line option.</p>262<section id="examples">263<h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h2>264<section id="display-the-top-10">265<h3>Display the top 10<a class="headerlink" href="#display-the-top-10" title="Link to this heading">¶</a></h3>266<p>Display the 10 files allocating the most memory:</p>267<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">tracemalloc</span>268 269<span class="n">tracemalloc</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>270 271<span class="c1"># ... run your application ...</span>272 273<span class="n">snapshot</span> <span class="o">=</span> <span class="n">tracemalloc</span><span class="o">.</span><span class="n">take_snapshot</span><span class="p">()</span>274<span class="n">top_stats</span> <span class="o">=</span> <span class="n">snapshot</span><span class="o">.</span><span class="n">statistics</span><span class="p">(</span><span class="s1">'lineno'</span><span class="p">)</span>275 276<span class="nb">print</span><span class="p">(</span><span class="s2">"[ Top 10 ]"</span><span class="p">)</span>277<span class="k">for</span> <span class="n">stat</span> <span class="ow">in</span> <span class="n">top_stats</span><span class="p">[:</span><span class="mi">10</span><span class="p">]:</span>278 <span class="nb">print</span><span class="p">(</span><span class="n">stat</span><span class="p">)</span>279</pre></div>280</div>281<p>Example of output of the Python test suite:</p>282<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">[</span> <span class="n">Top</span> <span class="mi">10</span> <span class="p">]</span>283<span class="o"><</span><span class="n">frozen</span> <span class="n">importlib</span><span class="o">.</span><span class="n">_bootstrap</span><span class="o">></span><span class="p">:</span><span class="mi">716</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mi">4855</span> <span class="n">KiB</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">39328</span><span class="p">,</span> <span class="n">average</span><span class="o">=</span><span class="mi">126</span> <span class="n">B</span>284<span class="o"><</span><span class="n">frozen</span> <span class="n">importlib</span><span class="o">.</span><span class="n">_bootstrap</span><span class="o">></span><span class="p">:</span><span class="mi">284</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mi">521</span> <span class="n">KiB</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">3199</span><span class="p">,</span> <span class="n">average</span><span class="o">=</span><span class="mi">167</span> <span class="n">B</span>285<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">collections</span><span class="o">/</span><span class="fm">__init__</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">368</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mi">244</span> <span class="n">KiB</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">2315</span><span class="p">,</span> <span class="n">average</span><span class="o">=</span><span class="mi">108</span> <span class="n">B</span>286<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">unittest</span><span class="o">/</span><span class="n">case</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">381</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mi">185</span> <span class="n">KiB</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">779</span><span class="p">,</span> <span class="n">average</span><span class="o">=</span><span class="mi">243</span> <span class="n">B</span>287<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">unittest</span><span class="o">/</span><span class="n">case</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">402</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mi">154</span> <span class="n">KiB</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">378</span><span class="p">,</span> <span class="n">average</span><span class="o">=</span><span class="mi">416</span> <span class="n">B</span>288<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">abc</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">133</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mf">88.7</span> <span class="n">KiB</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">347</span><span class="p">,</span> <span class="n">average</span><span class="o">=</span><span class="mi">262</span> <span class="n">B</span>289<span class="o"><</span><span class="n">frozen</span> <span class="n">importlib</span><span class="o">.</span><span class="n">_bootstrap</span><span class="o">></span><span class="p">:</span><span class="mi">1446</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mf">70.4</span> <span class="n">KiB</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">911</span><span class="p">,</span> <span class="n">average</span><span class="o">=</span><span class="mi">79</span> <span class="n">B</span>290<span class="o"><</span><span class="n">frozen</span> <span class="n">importlib</span><span class="o">.</span><span class="n">_bootstrap</span><span class="o">></span><span class="p">:</span><span class="mi">1454</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mf">52.0</span> <span class="n">KiB</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">25</span><span class="p">,</span> <span class="n">average</span><span class="o">=</span><span class="mi">2131</span> <span class="n">B</span>291<span class="o"><</span><span class="n">string</span><span class="o">></span><span class="p">:</span><span class="mi">5</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mf">49.7</span> <span class="n">KiB</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">148</span><span class="p">,</span> <span class="n">average</span><span class="o">=</span><span class="mi">344</span> <span class="n">B</span>292<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">sysconfig</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">411</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mf">48.0</span> <span class="n">KiB</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">average</span><span class="o">=</span><span class="mf">48.0</span> <span class="n">KiB</span>293</pre></div>294</div>295<p>We can see that Python loaded <code class="docutils literal notranslate"><span class="pre">4855</span> <span class="pre">KiB</span></code> data (bytecode and constants) from296modules and that the <a class="reference internal" href="collections.html#module-collections" title="collections: Container datatypes"><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections</span></code></a> module allocated <code class="docutils literal notranslate"><span class="pre">244</span> <span class="pre">KiB</span></code> to build297<a class="reference internal" href="collections.html#collections.namedtuple" title="collections.namedtuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">namedtuple</span></code></a> types.</p>298<p>See <a class="reference internal" href="#tracemalloc.Snapshot.statistics" title="tracemalloc.Snapshot.statistics"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Snapshot.statistics()</span></code></a> for more options.</p>299</section>300<section id="compute-differences">301<h3>Compute differences<a class="headerlink" href="#compute-differences" title="Link to this heading">¶</a></h3>302<p>Take two snapshots and display the differences:</p>303<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">tracemalloc</span>304<span class="n">tracemalloc</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>305<span class="c1"># ... start your application ...</span>306 307<span class="n">snapshot1</span> <span class="o">=</span> <span class="n">tracemalloc</span><span class="o">.</span><span class="n">take_snapshot</span><span class="p">()</span>308<span class="c1"># ... call the function leaking memory ...</span>309<span class="n">snapshot2</span> <span class="o">=</span> <span class="n">tracemalloc</span><span class="o">.</span><span class="n">take_snapshot</span><span class="p">()</span>310 311<span class="n">top_stats</span> <span class="o">=</span> <span class="n">snapshot2</span><span class="o">.</span><span class="n">compare_to</span><span class="p">(</span><span class="n">snapshot1</span><span class="p">,</span> <span class="s1">'lineno'</span><span class="p">)</span>312 313<span class="nb">print</span><span class="p">(</span><span class="s2">"[ Top 10 differences ]"</span><span class="p">)</span>314<span class="k">for</span> <span class="n">stat</span> <span class="ow">in</span> <span class="n">top_stats</span><span class="p">[:</span><span class="mi">10</span><span class="p">]:</span>315 <span class="nb">print</span><span class="p">(</span><span class="n">stat</span><span class="p">)</span>316</pre></div>317</div>318<p>Example of output before/after running some tests of the Python test suite:</p>319<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">[</span> <span class="n">Top</span> <span class="mi">10</span> <span class="n">differences</span> <span class="p">]</span>320<span class="o"><</span><span class="n">frozen</span> <span class="n">importlib</span><span class="o">.</span><span class="n">_bootstrap</span><span class="o">></span><span class="p">:</span><span class="mi">716</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mi">8173</span> <span class="n">KiB</span> <span class="p">(</span><span class="o">+</span><span class="mi">4428</span> <span class="n">KiB</span><span class="p">),</span> <span class="n">count</span><span class="o">=</span><span class="mi">71332</span> <span class="p">(</span><span class="o">+</span><span class="mi">39369</span><span class="p">),</span> <span class="n">average</span><span class="o">=</span><span class="mi">117</span> <span class="n">B</span>321<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">linecache</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">127</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mi">940</span> <span class="n">KiB</span> <span class="p">(</span><span class="o">+</span><span class="mi">940</span> <span class="n">KiB</span><span class="p">),</span> <span class="n">count</span><span class="o">=</span><span class="mi">8106</span> <span class="p">(</span><span class="o">+</span><span class="mi">8106</span><span class="p">),</span> <span class="n">average</span><span class="o">=</span><span class="mi">119</span> <span class="n">B</span>322<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">unittest</span><span class="o">/</span><span class="n">case</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">571</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mi">298</span> <span class="n">KiB</span> <span class="p">(</span><span class="o">+</span><span class="mi">298</span> <span class="n">KiB</span><span class="p">),</span> <span class="n">count</span><span class="o">=</span><span class="mi">589</span> <span class="p">(</span><span class="o">+</span><span class="mi">589</span><span class="p">),</span> <span class="n">average</span><span class="o">=</span><span class="mi">519</span> <span class="n">B</span>323<span class="o"><</span><span class="n">frozen</span> <span class="n">importlib</span><span class="o">.</span><span class="n">_bootstrap</span><span class="o">></span><span class="p">:</span><span class="mi">284</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mi">1005</span> <span class="n">KiB</span> <span class="p">(</span><span class="o">+</span><span class="mi">166</span> <span class="n">KiB</span><span class="p">),</span> <span class="n">count</span><span class="o">=</span><span class="mi">7423</span> <span class="p">(</span><span class="o">+</span><span class="mi">1526</span><span class="p">),</span> <span class="n">average</span><span class="o">=</span><span class="mi">139</span> <span class="n">B</span>324<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">mimetypes</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">217</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mi">112</span> <span class="n">KiB</span> <span class="p">(</span><span class="o">+</span><span class="mi">112</span> <span class="n">KiB</span><span class="p">),</span> <span class="n">count</span><span class="o">=</span><span class="mi">1334</span> <span class="p">(</span><span class="o">+</span><span class="mi">1334</span><span class="p">),</span> <span class="n">average</span><span class="o">=</span><span class="mi">86</span> <span class="n">B</span>325<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">http</span><span class="o">/</span><span class="n">server</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">848</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mf">96.0</span> <span class="n">KiB</span> <span class="p">(</span><span class="o">+</span><span class="mf">96.0</span> <span class="n">KiB</span><span class="p">),</span> <span class="n">count</span><span class="o">=</span><span class="mi">1</span> <span class="p">(</span><span class="o">+</span><span class="mi">1</span><span class="p">),</span> <span class="n">average</span><span class="o">=</span><span class="mf">96.0</span> <span class="n">KiB</span>326<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">inspect</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">1465</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mf">83.5</span> <span class="n">KiB</span> <span class="p">(</span><span class="o">+</span><span class="mf">83.5</span> <span class="n">KiB</span><span class="p">),</span> <span class="n">count</span><span class="o">=</span><span class="mi">109</span> <span class="p">(</span><span class="o">+</span><span class="mi">109</span><span class="p">),</span> <span class="n">average</span><span class="o">=</span><span class="mi">784</span> <span class="n">B</span>327<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">unittest</span><span class="o">/</span><span class="n">mock</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">491</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mf">77.7</span> <span class="n">KiB</span> <span class="p">(</span><span class="o">+</span><span class="mf">77.7</span> <span class="n">KiB</span><span class="p">),</span> <span class="n">count</span><span class="o">=</span><span class="mi">143</span> <span class="p">(</span><span class="o">+</span><span class="mi">143</span><span class="p">),</span> <span class="n">average</span><span class="o">=</span><span class="mi">557</span> <span class="n">B</span>328<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">urllib</span><span class="o">/</span><span class="n">parse</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">476</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mf">71.8</span> <span class="n">KiB</span> <span class="p">(</span><span class="o">+</span><span class="mf">71.8</span> <span class="n">KiB</span><span class="p">),</span> <span class="n">count</span><span class="o">=</span><span class="mi">969</span> <span class="p">(</span><span class="o">+</span><span class="mi">969</span><span class="p">),</span> <span class="n">average</span><span class="o">=</span><span class="mi">76</span> <span class="n">B</span>329<span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">python3</span><span class="mf">.4</span><span class="o">/</span><span class="n">contextlib</span><span class="o">.</span><span class="n">py</span><span class="p">:</span><span class="mi">38</span><span class="p">:</span> <span class="n">size</span><span class="o">=</span><span class="mf">67.2</span> <span class="n">KiB</span> <span class="p">(</span><span class="o">+</span><span class="mf">67.2</span> <span class="n">KiB</span><span class="p">),</span> <span class="n">count</span><span class="o">=</span><span class="mi">126</span> <span class="p">(</span><span class="o">+</span><span class="mi">126</span><span class="p">),</span> <span class="n">average</span><span class="o">=</span><span class="mi">546</span> <span class="n">B</span>330</pre></div>331</div>332<p>We can see that Python has loaded <code class="docutils literal notranslate"><span class="pre">8173</span> <span class="pre">KiB</span></code> of module data (bytecode and333constants), and that this is <code class="docutils literal notranslate"><span class="pre">4428</span> <span class="pre">KiB</span></code> more than had been loaded before the334tests, when the previous snapshot was taken. Similarly, the <a class="reference internal" href="linecache.html#module-linecache" title="linecache: Provides random access to individual lines from text files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">linecache</span></code></a>335module has cached <code class="docutils literal notranslate"><span class="pre">940</span> <span class="pre">KiB</span></code> of Python source code to format tracebacks, all336of it since the previous snapshot.</p>337<p>If the system has little free memory, snapshots can be written on disk using338the <a class="reference internal" href="#tracemalloc.Snapshot.dump" title="tracemalloc.Snapshot.dump"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Snapshot.dump()</span></code></a> method to analyze the snapshot offline. Then use the339<a class="reference internal" href="#tracemalloc.Snapshot.load" title="tracemalloc.Snapshot.load"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Snapshot.load()</span></code></a> method reload the snapshot.</p>340</section>341<section id="get-the-traceback-of-a-memory-block">342<h3>Get the traceback of a memory block<a class="headerlink" href="#get-the-traceback-of-a-memory-block" title="Link to this heading">¶</a></h3>343<p>Code to display the traceback of the biggest memory block:</p>344<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">tracemalloc</span>345 346<span class="c1"># Store 25 frames</span>347<span class="n">tracemalloc</span><span class="o">.</span><span class="n">start</span><span class="p">(</span><span class="mi">25</span><span class="p">)</span>348 349<span class="c1"># ... run your application ...</span>350 351<span class="n">snapshot</span> <span class="o">=</span> <span class="n">tracemalloc</span><span class="o">.</span><span class="n">take_snapshot</span><span class="p">()</span>352<span class="n">top_stats</span> <span class="o">=</span> <span class="n">snapshot</span><span class="o">.</span><span class="n">statistics</span><span class="p">(</span><span class="s1">'traceback'</span><span class="p">)</span>353 354<span class="c1"># pick the biggest memory block</span>355<span class="n">stat</span> <span class="o">=</span> <span class="n">top_stats</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>356<span class="nb">print</span><span class="p">(</span><span class="s2">"</span><span class="si">%s</span><span class="s2"> memory blocks: </span><span class="si">%.1f</span><span class="s2"> KiB"</span> <span class="o">%</span> <span class="p">(</span><span class="n">stat</span><span class="o">.</span><span class="n">count</span><span class="p">,</span> <span class="n">stat</span><span class="o">.</span><span class="n">size</span> <span class="o">/</span> <span class="mi">1024</span><span class="p">))</span>357<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">stat</span><span class="o">.</span><span class="n">traceback</span><span class="o">.</span><span class="n">format</span><span class="p">():</span>358 <span class="nb">print</span><span class="p">(</span><span class="n">line</span><span class="p">)</span>359</pre></div>360</div>361<p>Example of output of the Python test suite (traceback limited to 25 frames):</p>362<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="mi">903</span> <span class="n">memory</span> <span class="n">blocks</span><span class="p">:</span> <span class="mf">870.1</span> <span class="n">KiB</span>363 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">716</span>364 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">1036</span>365 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">934</span>366 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">1068</span>367 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">619</span>368 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">1581</span>369 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">1614</span>370 <span class="n">File</span> <span class="s2">"/usr/lib/python3.4/doctest.py"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">101</span>371 <span class="kn">import</span><span class="w"> </span><span class="nn">pdb</span>372 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">284</span>373 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">938</span>374 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">1068</span>375 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">619</span>376 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">1581</span>377 <span class="n">File</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">1614</span>378 <span class="n">File</span> <span class="s2">"/usr/lib/python3.4/test/support/__init__.py"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">1728</span>379 <span class="kn">import</span><span class="w"> </span><span class="nn">doctest</span>380 <span class="n">File</span> <span class="s2">"/usr/lib/python3.4/test/test_pickletools.py"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">21</span>381 <span class="n">support</span><span class="o">.</span><span class="n">run_doctest</span><span class="p">(</span><span class="n">pickletools</span><span class="p">)</span>382 <span class="n">File</span> <span class="s2">"/usr/lib/python3.4/test/regrtest.py"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">1276</span>383 <span class="n">test_runner</span><span class="p">()</span>384 <span class="n">File</span> <span class="s2">"/usr/lib/python3.4/test/regrtest.py"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">976</span>385 <span class="n">display_failure</span><span class="o">=</span><span class="ow">not</span> <span class="n">verbose</span><span class="p">)</span>386 <span class="n">File</span> <span class="s2">"/usr/lib/python3.4/test/regrtest.py"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">761</span>387 <span class="n">match_tests</span><span class="o">=</span><span class="n">ns</span><span class="o">.</span><span class="n">match_tests</span><span class="p">)</span>388 <span class="n">File</span> <span class="s2">"/usr/lib/python3.4/test/regrtest.py"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">1563</span>389 <span class="n">main</span><span class="p">()</span>390 <span class="n">File</span> <span class="s2">"/usr/lib/python3.4/test/__main__.py"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">3</span>391 <span class="n">regrtest</span><span class="o">.</span><span class="n">main_in_temp_cwd</span><span class="p">()</span>392 <span class="n">File</span> <span class="s2">"/usr/lib/python3.4/runpy.py"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">73</span>393 <span class="n">exec</span><span class="p">(</span><span class="n">code</span><span class="p">,</span> <span class="n">run_globals</span><span class="p">)</span>394 <span class="n">File</span> <span class="s2">"/usr/lib/python3.4/runpy.py"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">160</span>395 <span class="s2">"__main__"</span><span class="p">,</span> <span class="n">fname</span><span class="p">,</span> <span class="n">loader</span><span class="p">,</span> <span class="n">pkg_name</span><span class="p">)</span>396</pre></div>397</div>398<p>We can see that the most memory was allocated in the <a class="reference internal" href="importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib</span></code></a> module to399load data (bytecode and constants) from modules: <code class="docutils literal notranslate"><span class="pre">870.1</span> <span class="pre">KiB</span></code>. The traceback is400where the <code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib</span></code> loaded data most recently: on the <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">pdb</span></code>401line of the <a class="reference internal" href="doctest.html#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> module. The traceback may change if a new module is402loaded.</p>403</section>404<section id="pretty-top">405<h3>Pretty top<a class="headerlink" href="#pretty-top" title="Link to this heading">¶</a></h3>406<p>Code to display the 10 lines allocating the most memory with a pretty output,407ignoring <code class="docutils literal notranslate"><span class="pre"><frozen</span> <span class="pre">importlib._bootstrap></span></code> and <code class="docutils literal notranslate"><span class="pre"><unknown></span></code> files:</p>408<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">linecache</span>409<span class="kn">import</span><span class="w"> </span><span class="nn">os</span>410<span class="kn">import</span><span class="w"> </span><span class="nn">tracemalloc</span>411 412<span class="k">def</span><span class="w"> </span><span class="nf">display_top</span><span class="p">(</span><span class="n">snapshot</span><span class="p">,</span> <span class="n">key_type</span><span class="o">=</span><span class="s1">'lineno'</span><span class="p">,</span> <span class="n">limit</span><span class="o">=</span><span class="mi">10</span><span class="p">):</span>413 <span class="n">snapshot</span> <span class="o">=</span> <span class="n">snapshot</span><span class="o">.</span><span class="n">filter_traces</span><span class="p">((</span>414 <span class="n">tracemalloc</span><span class="o">.</span><span class="n">Filter</span><span class="p">(</span><span class="kc">False</span><span class="p">,</span> <span class="s2">"<frozen importlib._bootstrap>"</span><span class="p">),</span>415 <span class="n">tracemalloc</span><span class="o">.</span><span class="n">Filter</span><span class="p">(</span><span class="kc">False</span><span class="p">,</span> <span class="s2">"<unknown>"</span><span class="p">),</span>416 <span class="p">))</span>417 <span class="n">top_stats</span> <span class="o">=</span> <span class="n">snapshot</span><span class="o">.</span><span class="n">statistics</span><span class="p">(</span><span class="n">key_type</span><span class="p">)</span>418 419 <span class="nb">print</span><span class="p">(</span><span class="s2">"Top </span><span class="si">%s</span><span class="s2"> lines"</span> <span class="o">%</span> <span class="n">limit</span><span class="p">)</span>420 <span class="k">for</span> <span class="n">index</span><span class="p">,</span> <span class="n">stat</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">top_stats</span><span class="p">[:</span><span class="n">limit</span><span class="p">],</span> <span class="mi">1</span><span class="p">):</span>421 <span class="n">frame</span> <span class="o">=</span> <span class="n">stat</span><span class="o">.</span><span class="n">traceback</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>422 <span class="nb">print</span><span class="p">(</span><span class="s2">"#</span><span class="si">%s</span><span class="s2">: </span><span class="si">%s</span><span class="s2">:</span><span class="si">%s</span><span class="s2">: </span><span class="si">%.1f</span><span class="s2"> KiB"</span>423 <span class="o">%</span> <span class="p">(</span><span class="n">index</span><span class="p">,</span> <span class="n">frame</span><span class="o">.</span><span class="n">filename</span><span class="p">,</span> <span class="n">frame</span><span class="o">.</span><span class="n">lineno</span><span class="p">,</span> <span class="n">stat</span><span class="o">.</span><span class="n">size</span> <span class="o">/</span> <span class="mi">1024</span><span class="p">))</span>424 <span class="n">line</span> <span class="o">=</span> <span class="n">linecache</span><span class="o">.</span><span class="n">getline</span><span class="p">(</span><span class="n">frame</span><span class="o">.</span><span class="n">filename</span><span class="p">,</span> <span class="n">frame</span><span class="o">.</span><span class="n">lineno</span><span class="p">)</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span>425 <span class="k">if</span> <span class="n">line</span><span class="p">:</span>426 <span class="nb">print</span><span class="p">(</span><span class="s1">' </span><span class="si">%s</span><span class="s1">'</span> <span class="o">%</span> <span class="n">line</span><span class="p">)</span>427 428 <span class="n">other</span> <span class="o">=</span> <span class="n">top_stats</span><span class="p">[</span><span class="n">limit</span><span class="p">:]</span>429 <span class="k">if</span> <span class="n">other</span><span class="p">:</span>430 <span class="n">size</span> <span class="o">=</span> <span class="nb">sum</span><span class="p">(</span><span class="n">stat</span><span class="o">.</span><span class="n">size</span> <span class="k">for</span> <span class="n">stat</span> <span class="ow">in</span> <span class="n">other</span><span class="p">)</span>431 <span class="nb">print</span><span class="p">(</span><span class="s2">"</span><span class="si">%s</span><span class="s2"> other: </span><span class="si">%.1f</span><span class="s2"> KiB"</span> <span class="o">%</span> <span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">other</span><span class="p">),</span> <span class="n">size</span> <span class="o">/</span> <span class="mi">1024</span><span class="p">))</span>432 <span class="n">total</span> <span class="o">=</span> <span class="nb">sum</span><span class="p">(</span><span class="n">stat</span><span class="o">.</span><span class="n">size</span> <span class="k">for</span> <span class="n">stat</span> <span class="ow">in</span> <span class="n">top_stats</span><span class="p">)</span>433 <span class="nb">print</span><span class="p">(</span><span class="s2">"Total allocated size: </span><span class="si">%.1f</span><span class="s2"> KiB"</span> <span class="o">%</span> <span class="p">(</span><span class="n">total</span> <span class="o">/</span> <span class="mi">1024</span><span class="p">))</span>434 435<span class="n">tracemalloc</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>436 437<span class="c1"># ... run your application ...</span>438 439<span class="n">snapshot</span> <span class="o">=</span> <span class="n">tracemalloc</span><span class="o">.</span><span class="n">take_snapshot</span><span class="p">()</span>440<span class="n">display_top</span><span class="p">(</span><span class="n">snapshot</span><span class="p">)</span>441</pre></div>442</div>443<p>Example of output of the Python test suite:</p>444<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Top</span> <span class="mi">10</span> <span class="n">lines</span>445<span class="c1">#1: Lib/base64.py:414: 419.8 KiB</span>446 <span class="n">_b85chars2</span> <span class="o">=</span> <span class="p">[(</span><span class="n">a</span> <span class="o">+</span> <span class="n">b</span><span class="p">)</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="n">_b85chars</span> <span class="k">for</span> <span class="n">b</span> <span class="ow">in</span> <span class="n">_b85chars</span><span class="p">]</span>447<span class="c1">#2: Lib/base64.py:306: 419.8 KiB</span>448 <span class="n">_a85chars2</span> <span class="o">=</span> <span class="p">[(</span><span class="n">a</span> <span class="o">+</span> <span class="n">b</span><span class="p">)</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="n">_a85chars</span> <span class="k">for</span> <span class="n">b</span> <span class="ow">in</span> <span class="n">_a85chars</span><span class="p">]</span>449<span class="c1">#3: collections/__init__.py:368: 293.6 KiB</span>450 <span class="n">exec</span><span class="p">(</span><span class="n">class_definition</span><span class="p">,</span> <span class="n">namespace</span><span class="p">)</span>451<span class="c1">#4: Lib/abc.py:133: 115.2 KiB</span>452 <span class="bp">cls</span> <span class="o">=</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__new__</span><span class="p">(</span><span class="n">mcls</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">bases</span><span class="p">,</span> <span class="n">namespace</span><span class="p">)</span>453<span class="c1">#5: unittest/case.py:574: 103.1 KiB</span>454 <span class="n">testMethod</span><span class="p">()</span>455<span class="c1">#6: Lib/linecache.py:127: 95.4 KiB</span>456 <span class="n">lines</span> <span class="o">=</span> <span class="n">fp</span><span class="o">.</span><span class="n">readlines</span><span class="p">()</span>457<span class="c1">#7: urllib/parse.py:476: 71.8 KiB</span>458 <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="n">_hexdig</span> <span class="k">for</span> <span class="n">b</span> <span class="ow">in</span> <span class="n">_hexdig</span><span class="p">}</span>459<span class="c1">#8: <string>:5: 62.0 KiB</span>460<span class="c1">#9: Lib/_weakrefset.py:37: 60.0 KiB</span>461 <span class="bp">self</span><span class="o">.</span><span class="n">data</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>462<span class="c1">#10: Lib/base64.py:142: 59.8 KiB</span>463 <span class="n">_b32tab2</span> <span class="o">=</span> <span class="p">[</span><span class="n">a</span> <span class="o">+</span> <span class="n">b</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="n">_b32tab</span> <span class="k">for</span> <span class="n">b</span> <span class="ow">in</span> <span class="n">_b32tab</span><span class="p">]</span>464<span class="mi">6220</span> <span class="n">other</span><span class="p">:</span> <span class="mf">3602.8</span> <span class="n">KiB</span>465<span class="n">Total</span> <span class="n">allocated</span> <span class="n">size</span><span class="p">:</span> <span class="mf">5303.1</span> <span class="n">KiB</span>466</pre></div>467</div>468<p>See <a class="reference internal" href="#tracemalloc.Snapshot.statistics" title="tracemalloc.Snapshot.statistics"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Snapshot.statistics()</span></code></a> for more options.</p>469<section id="record-the-current-and-peak-size-of-all-traced-memory-blocks">470<h4>Record the current and peak size of all traced memory blocks<a class="headerlink" href="#record-the-current-and-peak-size-of-all-traced-memory-blocks" title="Link to this heading">¶</a></h4>471<p>The following code computes two sums like <code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre">+</span> <span class="pre">1</span> <span class="pre">+</span> <span class="pre">2</span> <span class="pre">+</span> <span class="pre">...</span></code> inefficiently, by472creating a list of those numbers. This list consumes a lot of memory473temporarily. We can use <a class="reference internal" href="#tracemalloc.get_traced_memory" title="tracemalloc.get_traced_memory"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_traced_memory()</span></code></a> and <a class="reference internal" href="#tracemalloc.reset_peak" title="tracemalloc.reset_peak"><code class="xref py py-func docutils literal notranslate"><span class="pre">reset_peak()</span></code></a> to474observe the small memory usage after the sum is computed as well as the peak475memory usage during the computations:</p>476<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">tracemalloc</span>477 478<span class="n">tracemalloc</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>479 480<span class="c1"># Example code: compute a sum with a large temporary list</span>481<span class="n">large_sum</span> <span class="o">=</span> <span class="nb">sum</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">100000</span><span class="p">)))</span>482 483<span class="n">first_size</span><span class="p">,</span> <span class="n">first_peak</span> <span class="o">=</span> <span class="n">tracemalloc</span><span class="o">.</span><span class="n">get_traced_memory</span><span class="p">()</span>484 485<span class="n">tracemalloc</span><span class="o">.</span><span class="n">reset_peak</span><span class="p">()</span>486 487<span class="c1"># Example code: compute a sum with a small temporary list</span>488<span class="n">small_sum</span> <span class="o">=</span> <span class="nb">sum</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">1000</span><span class="p">)))</span>489 490<span class="n">second_size</span><span class="p">,</span> <span class="n">second_peak</span> <span class="o">=</span> <span class="n">tracemalloc</span><span class="o">.</span><span class="n">get_traced_memory</span><span class="p">()</span>491 492<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">first_size</span><span class="si">=}</span><span class="s2">, </span><span class="si">{</span><span class="n">first_peak</span><span class="si">=}</span><span class="s2">"</span><span class="p">)</span>493<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">second_size</span><span class="si">=}</span><span class="s2">, </span><span class="si">{</span><span class="n">second_peak</span><span class="si">=}</span><span class="s2">"</span><span class="p">)</span>494</pre></div>495</div>496<p>Output:</p>497<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">first_size</span><span class="o">=</span><span class="mi">664</span><span class="p">,</span> <span class="n">first_peak</span><span class="o">=</span><span class="mi">3592984</span>498<span class="n">second_size</span><span class="o">=</span><span class="mi">804</span><span class="p">,</span> <span class="n">second_peak</span><span class="o">=</span><span class="mi">29704</span>499</pre></div>500</div>501<p>Using <a class="reference internal" href="#tracemalloc.reset_peak" title="tracemalloc.reset_peak"><code class="xref py py-func docutils literal notranslate"><span class="pre">reset_peak()</span></code></a> ensured we could accurately record the peak during the502computation of <code class="docutils literal notranslate"><span class="pre">small_sum</span></code>, even though it is much smaller than the overall503peak size of memory blocks since the <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code class="xref py py-func docutils literal notranslate"><span class="pre">start()</span></code></a> call. Without the call to504<code class="xref py py-func docutils literal notranslate"><span class="pre">reset_peak()</span></code>, <code class="docutils literal notranslate"><span class="pre">second_peak</span></code> would still be the peak from the505computation <code class="docutils literal notranslate"><span class="pre">large_sum</span></code> (that is, equal to <code class="docutils literal notranslate"><span class="pre">first_peak</span></code>). In this case,506both peaks are much higher than the final memory usage, and which suggests we507could optimise (by removing the unnecessary call to <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>, and writing508<code class="docutils literal notranslate"><span class="pre">sum(range(...))</span></code>).</p>509</section>510</section>511</section>512<section id="api">513<h2>API<a class="headerlink" href="#api" title="Link to this heading">¶</a></h2>514<section id="functions">515<h3>Functions<a class="headerlink" href="#functions" title="Link to this heading">¶</a></h3>516<dl class="py function">517<dt class="sig sig-object py" id="tracemalloc.clear_traces">518<span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">clear_traces</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.clear_traces" title="Link to this definition">¶</a></dt>519<dd><p>Clear traces of memory blocks allocated by Python.</p>520<p>See also <a class="reference internal" href="#tracemalloc.stop" title="tracemalloc.stop"><code class="xref py py-func docutils literal notranslate"><span class="pre">stop()</span></code></a>.</p>521</dd></dl>522 523<dl class="py function">524<dt class="sig sig-object py" id="tracemalloc.get_object_traceback">525<span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">get_object_traceback</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.get_object_traceback" title="Link to this definition">¶</a></dt>526<dd><p>Get the traceback where the Python object <em>obj</em> was allocated.527Return a <a class="reference internal" href="#tracemalloc.Traceback" title="tracemalloc.Traceback"><code class="xref py py-class docutils literal notranslate"><span class="pre">Traceback</span></code></a> instance, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if the <code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code>528module is not tracing memory allocations or did not trace the allocation of529the object.</p>530<p>See also <a class="reference internal" href="gc.html#gc.get_referrers" title="gc.get_referrers"><code class="xref py py-func docutils literal notranslate"><span class="pre">gc.get_referrers()</span></code></a> and <a class="reference internal" href="sys.html#sys.getsizeof" title="sys.getsizeof"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getsizeof()</span></code></a> functions.</p>531</dd></dl>532 533<dl class="py function">534<dt class="sig sig-object py" id="tracemalloc.get_traceback_limit">535<span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">get_traceback_limit</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.get_traceback_limit" title="Link to this definition">¶</a></dt>536<dd><p>Get the maximum number of frames stored in the traceback of a trace.</p>537<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> module must be tracing memory allocations to538get the limit, otherwise an exception is raised.</p>539<p>The limit is set by the <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code class="xref py py-func docutils literal notranslate"><span class="pre">start()</span></code></a> function.</p>540</dd></dl>541 542<dl class="py function">543<dt class="sig sig-object py" id="tracemalloc.get_traced_memory">544<span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">get_traced_memory</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.get_traced_memory" title="Link to this definition">¶</a></dt>545<dd><p>Get the current size and peak size of memory blocks traced by the546<code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> module as a tuple: <code class="docutils literal notranslate"><span class="pre">(current:</span> <span class="pre">int,</span> <span class="pre">peak:</span> <span class="pre">int)</span></code>.</p>547</dd></dl>548 549<dl class="py function">550<dt class="sig sig-object py" id="tracemalloc.reset_peak">551<span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">reset_peak</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.reset_peak" title="Link to this definition">¶</a></dt>552<dd><p>Set the peak size of memory blocks traced by the <code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> module553to the current size.</p>554<p>Do nothing if the <code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> module is not tracing memory555allocations.</p>556<p>This function only modifies the recorded peak size, and does not modify or557clear any traces, unlike <a class="reference internal" href="#tracemalloc.clear_traces" title="tracemalloc.clear_traces"><code class="xref py py-func docutils literal notranslate"><span class="pre">clear_traces()</span></code></a>. Snapshots taken with558<a class="reference internal" href="#tracemalloc.take_snapshot" title="tracemalloc.take_snapshot"><code class="xref py py-func docutils literal notranslate"><span class="pre">take_snapshot()</span></code></a> before a call to <code class="xref py py-func docutils literal notranslate"><span class="pre">reset_peak()</span></code> can be559meaningfully compared to snapshots taken after the call.</p>560<p>See also <a class="reference internal" href="#tracemalloc.get_traced_memory" title="tracemalloc.get_traced_memory"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_traced_memory()</span></code></a>.</p>561<div class="versionadded">562<p><span class="versionmodified added">Added in version 3.9.</span></p>563</div>564</dd></dl>565 566<dl class="py function">567<dt class="sig sig-object py" id="tracemalloc.get_tracemalloc_memory">568<span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">get_tracemalloc_memory</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.get_tracemalloc_memory" title="Link to this definition">¶</a></dt>569<dd><p>Get the memory usage in bytes of the <code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> module used to store570traces of memory blocks.571Return an <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>.</p>572</dd></dl>573 574<dl class="py function">575<dt class="sig sig-object py" id="tracemalloc.is_tracing">576<span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">is_tracing</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.is_tracing" title="Link to this definition">¶</a></dt>577<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the <code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> module is tracing Python memory578allocations, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.</p>579<p>See also <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code class="xref py py-func docutils literal notranslate"><span class="pre">start()</span></code></a> and <a class="reference internal" href="#tracemalloc.stop" title="tracemalloc.stop"><code class="xref py py-func docutils literal notranslate"><span class="pre">stop()</span></code></a> functions.</p>580</dd></dl>581 582<dl class="py function">583<dt class="sig sig-object py" id="tracemalloc.start">584<span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">start</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">nframe</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.start" title="Link to this definition">¶</a></dt>585<dd><p>Start tracing Python memory allocations: install hooks on Python memory586allocators. Collected tracebacks of traces will be limited to <em>nframe</em>587frames. By default, a trace of a memory block only stores the most recent588frame: the limit is <code class="docutils literal notranslate"><span class="pre">1</span></code>. <em>nframe</em> must be greater or equal to <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>589<p>You can still read the original number of total frames that composed the590traceback by looking at the <a class="reference internal" href="#tracemalloc.Traceback.total_nframe" title="tracemalloc.Traceback.total_nframe"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Traceback.total_nframe</span></code></a> attribute.</p>591<p>Storing more than <code class="docutils literal notranslate"><span class="pre">1</span></code> frame is only useful to compute statistics grouped592by <code class="docutils literal notranslate"><span class="pre">'traceback'</span></code> or to compute cumulative statistics: see the593<a class="reference internal" href="#tracemalloc.Snapshot.compare_to" title="tracemalloc.Snapshot.compare_to"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Snapshot.compare_to()</span></code></a> and <a class="reference internal" href="#tracemalloc.Snapshot.statistics" title="tracemalloc.Snapshot.statistics"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Snapshot.statistics()</span></code></a> methods.</p>594<p>Storing more frames increases the memory and CPU overhead of the595<code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> module. Use the <a class="reference internal" href="#tracemalloc.get_tracemalloc_memory" title="tracemalloc.get_tracemalloc_memory"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_tracemalloc_memory()</span></code></a> function596to measure how much memory is used by the <code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> module.</p>597<p>The <span class="target" id="index-2"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONTRACEMALLOC"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONTRACEMALLOC</span></code></a> environment variable598(<code class="docutils literal notranslate"><span class="pre">PYTHONTRACEMALLOC=NFRAME</span></code>) and the <a class="reference internal" href="../using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span></code></a> <code class="docutils literal notranslate"><span class="pre">tracemalloc=NFRAME</span></code>599command line option can be used to start tracing at startup.</p>600<p>See also <a class="reference internal" href="#tracemalloc.stop" title="tracemalloc.stop"><code class="xref py py-func docutils literal notranslate"><span class="pre">stop()</span></code></a>, <a class="reference internal" href="#tracemalloc.is_tracing" title="tracemalloc.is_tracing"><code class="xref py py-func docutils literal notranslate"><span class="pre">is_tracing()</span></code></a> and <a class="reference internal" href="#tracemalloc.get_traceback_limit" title="tracemalloc.get_traceback_limit"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_traceback_limit()</span></code></a>601functions.</p>602</dd></dl>603 604<dl class="py function">605<dt class="sig sig-object py" id="tracemalloc.stop">606<span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">stop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.stop" title="Link to this definition">¶</a></dt>607<dd><p>Stop tracing Python memory allocations: uninstall hooks on Python memory608allocators. Also clears all previously collected traces of memory blocks609allocated by Python.</p>610<p>Call <a class="reference internal" href="#tracemalloc.take_snapshot" title="tracemalloc.take_snapshot"><code class="xref py py-func docutils literal notranslate"><span class="pre">take_snapshot()</span></code></a> function to take a snapshot of traces before611clearing them.</p>612<p>See also <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code class="xref py py-func docutils literal notranslate"><span class="pre">start()</span></code></a>, <a class="reference internal" href="#tracemalloc.is_tracing" title="tracemalloc.is_tracing"><code class="xref py py-func docutils literal notranslate"><span class="pre">is_tracing()</span></code></a> and <a class="reference internal" href="#tracemalloc.clear_traces" title="tracemalloc.clear_traces"><code class="xref py py-func docutils literal notranslate"><span class="pre">clear_traces()</span></code></a>613functions.</p>614</dd></dl>615 616<dl class="py function">617<dt class="sig sig-object py" id="tracemalloc.take_snapshot">618<span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">take_snapshot</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.take_snapshot" title="Link to this definition">¶</a></dt>619<dd><p>Take a snapshot of traces of memory blocks allocated by Python. Return a new620<a class="reference internal" href="#tracemalloc.Snapshot" title="tracemalloc.Snapshot"><code class="xref py py-class docutils literal notranslate"><span class="pre">Snapshot</span></code></a> instance.</p>621<p>The snapshot does not include memory blocks allocated before the622<code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> module started to trace memory allocations.</p>623<p>Tracebacks of traces are limited to <a class="reference internal" href="#tracemalloc.get_traceback_limit" title="tracemalloc.get_traceback_limit"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_traceback_limit()</span></code></a> frames. Use624the <em>nframe</em> parameter of the <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code class="xref py py-func docutils literal notranslate"><span class="pre">start()</span></code></a> function to store more frames.</p>625<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> module must be tracing memory allocations to take a626snapshot, see the <a class="reference internal" href="#tracemalloc.start" title="tracemalloc.start"><code class="xref py py-func docutils literal notranslate"><span class="pre">start()</span></code></a> function.</p>627<p>See also the <a class="reference internal" href="#tracemalloc.get_object_traceback" title="tracemalloc.get_object_traceback"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_object_traceback()</span></code></a> function.</p>628</dd></dl>629 630</section>631<section id="domainfilter">632<h3>DomainFilter<a class="headerlink" href="#domainfilter" title="Link to this heading">¶</a></h3>633<dl class="py class">634<dt class="sig sig-object py" id="tracemalloc.DomainFilter">635<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">DomainFilter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">inclusive</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#bool" title="bool"><span class="pre">bool</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">domain</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.DomainFilter" title="Link to this definition">¶</a></dt>636<dd><p>Filter traces of memory blocks by their address space (domain).</p>637<div class="versionadded">638<p><span class="versionmodified added">Added in version 3.6.</span></p>639</div>640<dl class="py attribute">641<dt class="sig sig-object py" id="tracemalloc.DomainFilter.inclusive">642<span class="sig-name descname"><span class="pre">inclusive</span></span><a class="headerlink" href="#tracemalloc.DomainFilter.inclusive" title="Link to this definition">¶</a></dt>643<dd><p>If <em>inclusive</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (include), match memory blocks allocated644in the address space <a class="reference internal" href="#tracemalloc.DomainFilter.domain" title="tracemalloc.DomainFilter.domain"><code class="xref py py-attr docutils literal notranslate"><span class="pre">domain</span></code></a>.</p>645<p>If <em>inclusive</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> (exclude), match memory blocks not allocated646in the address space <a class="reference internal" href="#tracemalloc.DomainFilter.domain" title="tracemalloc.DomainFilter.domain"><code class="xref py py-attr docutils literal notranslate"><span class="pre">domain</span></code></a>.</p>647</dd></dl>648 649<dl class="py attribute">650<dt class="sig sig-object py" id="tracemalloc.DomainFilter.domain">651<span class="sig-name descname"><span class="pre">domain</span></span><a class="headerlink" href="#tracemalloc.DomainFilter.domain" title="Link to this definition">¶</a></dt>652<dd><p>Address space of a memory block (<code class="docutils literal notranslate"><span class="pre">int</span></code>). Read-only property.</p>653</dd></dl>654 655</dd></dl>656 657</section>658<section id="filter">659<h3>Filter<a class="headerlink" href="#filter" title="Link to this heading">¶</a></h3>660<dl class="py class">661<dt class="sig sig-object py" id="tracemalloc.Filter">662<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">Filter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">inclusive</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#bool" title="bool"><span class="pre">bool</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">filename_pattern</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="stdtypes.html#str" title="str"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">lineno</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">all_frames</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#bool" title="bool"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">domain</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.Filter" title="Link to this definition">¶</a></dt>663<dd><p>Filter on traces of memory blocks.</p>664<p>See the <a class="reference internal" href="fnmatch.html#fnmatch.fnmatch" title="fnmatch.fnmatch"><code class="xref py py-func docutils literal notranslate"><span class="pre">fnmatch.fnmatch()</span></code></a> function for the syntax of665<em>filename_pattern</em>. The <code class="docutils literal notranslate"><span class="pre">'.pyc'</span></code> file extension is666replaced with <code class="docutils literal notranslate"><span class="pre">'.py'</span></code>.</p>667<p>Examples:</p>668<ul class="simple">669<li><p><code class="docutils literal notranslate"><span class="pre">Filter(True,</span> <span class="pre">subprocess.__file__)</span></code> only includes traces of the670<a class="reference internal" href="subprocess.html#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> module</p></li>671<li><p><code class="docutils literal notranslate"><span class="pre">Filter(False,</span> <span class="pre">tracemalloc.__file__)</span></code> excludes traces of the672<code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> module</p></li>673<li><p><code class="docutils literal notranslate"><span class="pre">Filter(False,</span> <span class="pre">"<unknown>")</span></code> excludes empty tracebacks</p></li>674</ul>675<div class="versionchanged">676<p><span class="versionmodified changed">Changed in version 3.5: </span>The <code class="docutils literal notranslate"><span class="pre">'.pyo'</span></code> file extension is no longer replaced with <code class="docutils literal notranslate"><span class="pre">'.py'</span></code>.</p>677</div>678<div class="versionchanged">679<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 class="xref py py-attr docutils literal notranslate"><span class="pre">domain</span></code></a> attribute.</p>680</div>681<dl class="py attribute">682<dt class="sig sig-object py" id="tracemalloc.Filter.domain">683<span class="sig-name descname"><span class="pre">domain</span></span><a class="headerlink" href="#tracemalloc.Filter.domain" title="Link to this definition">¶</a></dt>684<dd><p>Address space of a memory block (<code class="docutils literal notranslate"><span class="pre">int</span></code> or <code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>685<p>tracemalloc uses the domain <code class="docutils literal notranslate"><span class="pre">0</span></code> to trace memory allocations made by686Python. C extensions can use other domains to trace other resources.</p>687</dd></dl>688 689<dl class="py attribute">690<dt class="sig sig-object py" id="tracemalloc.Filter.inclusive">691<span class="sig-name descname"><span class="pre">inclusive</span></span><a class="headerlink" href="#tracemalloc.Filter.inclusive" title="Link to this definition">¶</a></dt>692<dd><p>If <em>inclusive</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (include), only match memory blocks allocated693in a file with a name matching <a class="reference internal" href="#tracemalloc.Filter.filename_pattern" title="tracemalloc.Filter.filename_pattern"><code class="xref py py-attr docutils literal notranslate"><span class="pre">filename_pattern</span></code></a> at line number694<a class="reference internal" href="#tracemalloc.Filter.lineno" title="tracemalloc.Filter.lineno"><code class="xref py py-attr docutils literal notranslate"><span class="pre">lineno</span></code></a>.</p>695<p>If <em>inclusive</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> (exclude), ignore memory blocks allocated in696a file with a name matching <a class="reference internal" href="#tracemalloc.Filter.filename_pattern" title="tracemalloc.Filter.filename_pattern"><code class="xref py py-attr docutils literal notranslate"><span class="pre">filename_pattern</span></code></a> at line number697<a class="reference internal" href="#tracemalloc.Filter.lineno" title="tracemalloc.Filter.lineno"><code class="xref py py-attr docutils literal notranslate"><span class="pre">lineno</span></code></a>.</p>698</dd></dl>699 700<dl class="py attribute">701<dt class="sig sig-object py" id="tracemalloc.Filter.lineno">702<span class="sig-name descname"><span class="pre">lineno</span></span><a class="headerlink" href="#tracemalloc.Filter.lineno" title="Link to this definition">¶</a></dt>703<dd><p>Line number (<code class="docutils literal notranslate"><span class="pre">int</span></code>) of the filter. If <em>lineno</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, the filter704matches any line number.</p>705</dd></dl>706 707<dl class="py attribute">708<dt class="sig sig-object py" id="tracemalloc.Filter.filename_pattern">709<span class="sig-name descname"><span class="pre">filename_pattern</span></span><a class="headerlink" href="#tracemalloc.Filter.filename_pattern" title="Link to this definition">¶</a></dt>710<dd><p>Filename pattern of the filter (<code class="docutils literal notranslate"><span class="pre">str</span></code>). Read-only property.</p>711</dd></dl>712 713<dl class="py attribute">714<dt class="sig sig-object py" id="tracemalloc.Filter.all_frames">715<span class="sig-name descname"><span class="pre">all_frames</span></span><a class="headerlink" href="#tracemalloc.Filter.all_frames" title="Link to this definition">¶</a></dt>716<dd><p>If <em>all_frames</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, all frames of the traceback are checked. If717<em>all_frames</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, only the most recent frame is checked.</p>718<p>This attribute has no effect if the traceback limit is <code class="docutils literal notranslate"><span class="pre">1</span></code>. See the719<a class="reference internal" href="#tracemalloc.get_traceback_limit" title="tracemalloc.get_traceback_limit"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_traceback_limit()</span></code></a> function and <a class="reference internal" href="#tracemalloc.Snapshot.traceback_limit" title="tracemalloc.Snapshot.traceback_limit"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Snapshot.traceback_limit</span></code></a>720attribute.</p>721</dd></dl>722 723</dd></dl>724 725</section>726<section id="frame">727<h3>Frame<a class="headerlink" href="#frame" title="Link to this heading">¶</a></h3>728<dl class="py class">729<dt class="sig sig-object py" id="tracemalloc.Frame">730<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">Frame</span></span><a class="headerlink" href="#tracemalloc.Frame" title="Link to this definition">¶</a></dt>731<dd><p>Frame of a traceback.</p>732<p>The <a class="reference internal" href="#tracemalloc.Traceback" title="tracemalloc.Traceback"><code class="xref py py-class docutils literal notranslate"><span class="pre">Traceback</span></code></a> class is a sequence of <code class="xref py py-class docutils literal notranslate"><span class="pre">Frame</span></code> instances.</p>733<dl class="py attribute">734<dt class="sig sig-object py" id="tracemalloc.Frame.filename">735<span class="sig-name descname"><span class="pre">filename</span></span><a class="headerlink" href="#tracemalloc.Frame.filename" title="Link to this definition">¶</a></dt>736<dd><p>Filename (<code class="docutils literal notranslate"><span class="pre">str</span></code>).</p>737</dd></dl>738 739<dl class="py attribute">740<dt class="sig sig-object py" id="tracemalloc.Frame.lineno">741<span class="sig-name descname"><span class="pre">lineno</span></span><a class="headerlink" href="#tracemalloc.Frame.lineno" title="Link to this definition">¶</a></dt>742<dd><p>Line number (<code class="docutils literal notranslate"><span class="pre">int</span></code>).</p>743</dd></dl>744 745</dd></dl>746 747</section>748<section id="snapshot">749<h3>Snapshot<a class="headerlink" href="#snapshot" title="Link to this heading">¶</a></h3>750<dl class="py class">751<dt class="sig sig-object py" id="tracemalloc.Snapshot">752<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">Snapshot</span></span><a class="headerlink" href="#tracemalloc.Snapshot" title="Link to this definition">¶</a></dt>753<dd><p>Snapshot of traces of memory blocks allocated by Python.</p>754<p>The <a class="reference internal" href="#tracemalloc.take_snapshot" title="tracemalloc.take_snapshot"><code class="xref py py-func docutils literal notranslate"><span class="pre">take_snapshot()</span></code></a> function creates a snapshot instance.</p>755<dl class="py method">756<dt class="sig sig-object py" id="tracemalloc.Snapshot.compare_to">757<span class="sig-name descname"><span class="pre">compare_to</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">old_snapshot</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Snapshot</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">key_type</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="stdtypes.html#str" title="str"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">cumulative</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#bool" title="bool"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.Snapshot.compare_to" title="Link to this definition">¶</a></dt>758<dd><p>Compute the differences with an old snapshot. Get statistics as a sorted759list of <a class="reference internal" href="#tracemalloc.StatisticDiff" title="tracemalloc.StatisticDiff"><code class="xref py py-class docutils literal notranslate"><span class="pre">StatisticDiff</span></code></a> instances grouped by <em>key_type</em>.</p>760<p>See the <a class="reference internal" href="#tracemalloc.Snapshot.statistics" title="tracemalloc.Snapshot.statistics"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Snapshot.statistics()</span></code></a> method for <em>key_type</em> and <em>cumulative</em>761parameters.</p>762<p>The result is sorted from the biggest to the smallest by: absolute value763of <a class="reference internal" href="#tracemalloc.StatisticDiff.size_diff" title="tracemalloc.StatisticDiff.size_diff"><code class="xref py py-attr docutils literal notranslate"><span class="pre">StatisticDiff.size_diff</span></code></a>, <a class="reference internal" href="#tracemalloc.StatisticDiff.size" title="tracemalloc.StatisticDiff.size"><code class="xref py py-attr docutils literal notranslate"><span class="pre">StatisticDiff.size</span></code></a>, absolute764value of <a class="reference internal" href="#tracemalloc.StatisticDiff.count_diff" title="tracemalloc.StatisticDiff.count_diff"><code class="xref py py-attr docutils literal notranslate"><span class="pre">StatisticDiff.count_diff</span></code></a>, <a class="reference internal" href="#tracemalloc.Statistic.count" title="tracemalloc.Statistic.count"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Statistic.count</span></code></a> and765then by <a class="reference internal" href="#tracemalloc.StatisticDiff.traceback" title="tracemalloc.StatisticDiff.traceback"><code class="xref py py-attr docutils literal notranslate"><span class="pre">StatisticDiff.traceback</span></code></a>.</p>766</dd></dl>767 768<dl class="py method">769<dt class="sig sig-object py" id="tracemalloc.Snapshot.dump">770<span class="sig-name descname"><span class="pre">dump</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.Snapshot.dump" title="Link to this definition">¶</a></dt>771<dd><p>Write the snapshot into a file.</p>772<p>Use <a class="reference internal" href="#tracemalloc.Snapshot.load" title="tracemalloc.Snapshot.load"><code class="xref py py-meth docutils literal notranslate"><span class="pre">load()</span></code></a> to reload the snapshot.</p>773</dd></dl>774 775<dl class="py method">776<dt class="sig sig-object py" id="tracemalloc.Snapshot.filter_traces">777<span class="sig-name descname"><span class="pre">filter_traces</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filters</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.Snapshot.filter_traces" title="Link to this definition">¶</a></dt>778<dd><p>Create a new <code class="xref py py-class docutils literal notranslate"><span class="pre">Snapshot</span></code> instance with a filtered <a class="reference internal" href="#tracemalloc.Snapshot.traces" title="tracemalloc.Snapshot.traces"><code class="xref py py-attr docutils literal notranslate"><span class="pre">traces</span></code></a>779sequence, <em>filters</em> is a list of <a class="reference internal" href="#tracemalloc.DomainFilter" title="tracemalloc.DomainFilter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DomainFilter</span></code></a> and780<a class="reference internal" href="#tracemalloc.Filter" title="tracemalloc.Filter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Filter</span></code></a> instances. If <em>filters</em> is an empty list, return a new781<code class="xref py py-class docutils literal notranslate"><span class="pre">Snapshot</span></code> instance with a copy of the traces.</p>782<p>All inclusive filters are applied at once, a trace is ignored if no783inclusive filters match it. A trace is ignored if at least one exclusive784filter matches it.</p>785<div class="versionchanged">786<p><span class="versionmodified changed">Changed in version 3.6: </span><a class="reference internal" href="#tracemalloc.DomainFilter" title="tracemalloc.DomainFilter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DomainFilter</span></code></a> instances are now also accepted in <em>filters</em>.</p>787</div>788</dd></dl>789 790<dl class="py method">791<dt class="sig sig-object py" id="tracemalloc.Snapshot.load">792<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">load</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.Snapshot.load" title="Link to this definition">¶</a></dt>793<dd><p>Load a snapshot from a file.</p>794<p>See also <a class="reference internal" href="#tracemalloc.Snapshot.dump" title="tracemalloc.Snapshot.dump"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dump()</span></code></a>.</p>795</dd></dl>796 797<dl class="py method">798<dt class="sig sig-object py" id="tracemalloc.Snapshot.statistics">799<span class="sig-name descname"><span class="pre">statistics</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key_type</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="stdtypes.html#str" title="str"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">cumulative</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#bool" title="bool"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.Snapshot.statistics" title="Link to this definition">¶</a></dt>800<dd><p>Get statistics as a sorted list of <a class="reference internal" href="#tracemalloc.Statistic" title="tracemalloc.Statistic"><code class="xref py py-class docutils literal notranslate"><span class="pre">Statistic</span></code></a> instances grouped801by <em>key_type</em>:</p>802<table class="docutils align-default">803<thead>804<tr class="row-odd"><th class="head"><p>key_type</p></th>805<th class="head"><p>description</p></th>806</tr>807</thead>808<tbody>809<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'filename'</span></code></p></td>810<td><p>filename</p></td>811</tr>812<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'lineno'</span></code></p></td>813<td><p>filename and line number</p></td>814</tr>815<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'traceback'</span></code></p></td>816<td><p>traceback</p></td>817</tr>818</tbody>819</table>820<p>If <em>cumulative</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, cumulate size and count of memory blocks of821all frames of the traceback of a trace, not only the most recent frame.822The cumulative mode can only be used with <em>key_type</em> equal to823<code class="docutils literal notranslate"><span class="pre">'filename'</span></code> and <code class="docutils literal notranslate"><span class="pre">'lineno'</span></code>.</p>824<p>The result is sorted from the biggest to the smallest by:825<a class="reference internal" href="#tracemalloc.Statistic.size" title="tracemalloc.Statistic.size"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Statistic.size</span></code></a>, <a class="reference internal" href="#tracemalloc.Statistic.count" title="tracemalloc.Statistic.count"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Statistic.count</span></code></a> and then by826<a class="reference internal" href="#tracemalloc.Statistic.traceback" title="tracemalloc.Statistic.traceback"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Statistic.traceback</span></code></a>.</p>827</dd></dl>828 829<dl class="py attribute">830<dt class="sig sig-object py" id="tracemalloc.Snapshot.traceback_limit">831<span class="sig-name descname"><span class="pre">traceback_limit</span></span><a class="headerlink" href="#tracemalloc.Snapshot.traceback_limit" title="Link to this definition">¶</a></dt>832<dd><p>Maximum number of frames stored in the traceback of <a class="reference internal" href="#tracemalloc.Snapshot.traces" title="tracemalloc.Snapshot.traces"><code class="xref py py-attr docutils literal notranslate"><span class="pre">traces</span></code></a>:833result of the <a class="reference internal" href="#tracemalloc.get_traceback_limit" title="tracemalloc.get_traceback_limit"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_traceback_limit()</span></code></a> when the snapshot was taken.</p>834</dd></dl>835 836<dl class="py attribute">837<dt class="sig sig-object py" id="tracemalloc.Snapshot.traces">838<span class="sig-name descname"><span class="pre">traces</span></span><a class="headerlink" href="#tracemalloc.Snapshot.traces" title="Link to this definition">¶</a></dt>839<dd><p>Traces of all memory blocks allocated by Python: sequence of840<a class="reference internal" href="#tracemalloc.Trace" title="tracemalloc.Trace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Trace</span></code></a> instances.</p>841<p>The sequence has an undefined order. Use the <a class="reference internal" href="#tracemalloc.Snapshot.statistics" title="tracemalloc.Snapshot.statistics"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Snapshot.statistics()</span></code></a>842method to get a sorted list of statistics.</p>843</dd></dl>844 845</dd></dl>846 847</section>848<section id="statistic">849<h3>Statistic<a class="headerlink" href="#statistic" title="Link to this heading">¶</a></h3>850<dl class="py class">851<dt class="sig sig-object py" id="tracemalloc.Statistic">852<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">Statistic</span></span><a class="headerlink" href="#tracemalloc.Statistic" title="Link to this definition">¶</a></dt>853<dd><p>Statistic on memory allocations.</p>854<p><a class="reference internal" href="#tracemalloc.Snapshot.statistics" title="tracemalloc.Snapshot.statistics"><code class="xref py py-func docutils literal notranslate"><span class="pre">Snapshot.statistics()</span></code></a> returns a list of <code class="xref py py-class docutils literal notranslate"><span class="pre">Statistic</span></code> instances.</p>855<p>See also the <a class="reference internal" href="#tracemalloc.StatisticDiff" title="tracemalloc.StatisticDiff"><code class="xref py py-class docutils literal notranslate"><span class="pre">StatisticDiff</span></code></a> class.</p>856<dl class="py attribute">857<dt class="sig sig-object py" id="tracemalloc.Statistic.count">858<span class="sig-name descname"><span class="pre">count</span></span><a class="headerlink" href="#tracemalloc.Statistic.count" title="Link to this definition">¶</a></dt>859<dd><p>Number of memory blocks (<code class="docutils literal notranslate"><span class="pre">int</span></code>).</p>860</dd></dl>861 862<dl class="py attribute">863<dt class="sig sig-object py" id="tracemalloc.Statistic.size">864<span class="sig-name descname"><span class="pre">size</span></span><a class="headerlink" href="#tracemalloc.Statistic.size" title="Link to this definition">¶</a></dt>865<dd><p>Total size of memory blocks in bytes (<code class="docutils literal notranslate"><span class="pre">int</span></code>).</p>866</dd></dl>867 868<dl class="py attribute">869<dt class="sig sig-object py" id="tracemalloc.Statistic.traceback">870<span class="sig-name descname"><span class="pre">traceback</span></span><a class="headerlink" href="#tracemalloc.Statistic.traceback" title="Link to this definition">¶</a></dt>871<dd><p>Traceback where the memory block was allocated, <a class="reference internal" href="#tracemalloc.Traceback" title="tracemalloc.Traceback"><code class="xref py py-class docutils literal notranslate"><span class="pre">Traceback</span></code></a>872instance.</p>873</dd></dl>874 875</dd></dl>876 877</section>878<section id="statisticdiff">879<h3>StatisticDiff<a class="headerlink" href="#statisticdiff" title="Link to this heading">¶</a></h3>880<dl class="py class">881<dt class="sig sig-object py" id="tracemalloc.StatisticDiff">882<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">StatisticDiff</span></span><a class="headerlink" href="#tracemalloc.StatisticDiff" title="Link to this definition">¶</a></dt>883<dd><p>Statistic difference on memory allocations between an old and a new884<a class="reference internal" href="#tracemalloc.Snapshot" title="tracemalloc.Snapshot"><code class="xref py py-class docutils literal notranslate"><span class="pre">Snapshot</span></code></a> instance.</p>885<p><a class="reference internal" href="#tracemalloc.Snapshot.compare_to" title="tracemalloc.Snapshot.compare_to"><code class="xref py py-func docutils literal notranslate"><span class="pre">Snapshot.compare_to()</span></code></a> returns a list of <code class="xref py py-class docutils literal notranslate"><span class="pre">StatisticDiff</span></code>886instances. See also the <a class="reference internal" href="#tracemalloc.Statistic" title="tracemalloc.Statistic"><code class="xref py py-class docutils literal notranslate"><span class="pre">Statistic</span></code></a> class.</p>887<dl class="py attribute">888<dt class="sig sig-object py" id="tracemalloc.StatisticDiff.count">889<span class="sig-name descname"><span class="pre">count</span></span><a class="headerlink" href="#tracemalloc.StatisticDiff.count" title="Link to this definition">¶</a></dt>890<dd><p>Number of memory blocks in the new snapshot (<code class="docutils literal notranslate"><span class="pre">int</span></code>): <code class="docutils literal notranslate"><span class="pre">0</span></code> if891the memory blocks have been released in the new snapshot.</p>892</dd></dl>893 894<dl class="py attribute">895<dt class="sig sig-object py" id="tracemalloc.StatisticDiff.count_diff">896<span class="sig-name descname"><span class="pre">count_diff</span></span><a class="headerlink" href="#tracemalloc.StatisticDiff.count_diff" title="Link to this definition">¶</a></dt>897<dd><p>Difference of number of memory blocks between the old and the new898snapshots (<code class="docutils literal notranslate"><span class="pre">int</span></code>): <code class="docutils literal notranslate"><span class="pre">0</span></code> if the memory blocks have been allocated in899the new snapshot.</p>900</dd></dl>901 902<dl class="py attribute">903<dt class="sig sig-object py" id="tracemalloc.StatisticDiff.size">904<span class="sig-name descname"><span class="pre">size</span></span><a class="headerlink" href="#tracemalloc.StatisticDiff.size" title="Link to this definition">¶</a></dt>905<dd><p>Total size of memory blocks in bytes in the new snapshot (<code class="docutils literal notranslate"><span class="pre">int</span></code>):906<code class="docutils literal notranslate"><span class="pre">0</span></code> if the memory blocks have been released in the new snapshot.</p>907</dd></dl>908 909<dl class="py attribute">910<dt class="sig sig-object py" id="tracemalloc.StatisticDiff.size_diff">911<span class="sig-name descname"><span class="pre">size_diff</span></span><a class="headerlink" href="#tracemalloc.StatisticDiff.size_diff" title="Link to this definition">¶</a></dt>912<dd><p>Difference of total size of memory blocks in bytes between the old and913the new snapshots (<code class="docutils literal notranslate"><span class="pre">int</span></code>): <code class="docutils literal notranslate"><span class="pre">0</span></code> if the memory blocks have been914allocated in the new snapshot.</p>915</dd></dl>916 917<dl class="py attribute">918<dt class="sig sig-object py" id="tracemalloc.StatisticDiff.traceback">919<span class="sig-name descname"><span class="pre">traceback</span></span><a class="headerlink" href="#tracemalloc.StatisticDiff.traceback" title="Link to this definition">¶</a></dt>920<dd><p>Traceback where the memory blocks were allocated, <a class="reference internal" href="#tracemalloc.Traceback" title="tracemalloc.Traceback"><code class="xref py py-class docutils literal notranslate"><span class="pre">Traceback</span></code></a>921instance.</p>922</dd></dl>923 924</dd></dl>925 926</section>927<section id="trace">928<h3>Trace<a class="headerlink" href="#trace" title="Link to this heading">¶</a></h3>929<dl class="py class">930<dt class="sig sig-object py" id="tracemalloc.Trace">931<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">Trace</span></span><a class="headerlink" href="#tracemalloc.Trace" title="Link to this definition">¶</a></dt>932<dd><p>Trace of a memory block.</p>933<p>The <a class="reference internal" href="#tracemalloc.Snapshot.traces" title="tracemalloc.Snapshot.traces"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Snapshot.traces</span></code></a> attribute is a sequence of <code class="xref py py-class docutils literal notranslate"><span class="pre">Trace</span></code>934instances.</p>935<div class="versionchanged">936<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 class="xref py py-attr docutils literal notranslate"><span class="pre">domain</span></code></a> attribute.</p>937</div>938<dl class="py attribute">939<dt class="sig sig-object py" id="tracemalloc.Trace.domain">940<span class="sig-name descname"><span class="pre">domain</span></span><a class="headerlink" href="#tracemalloc.Trace.domain" title="Link to this definition">¶</a></dt>941<dd><p>Address space of a memory block (<code class="docutils literal notranslate"><span class="pre">int</span></code>). Read-only property.</p>942<p>tracemalloc uses the domain <code class="docutils literal notranslate"><span class="pre">0</span></code> to trace memory allocations made by943Python. C extensions can use other domains to trace other resources.</p>944</dd></dl>945 946<dl class="py attribute">947<dt class="sig sig-object py" id="tracemalloc.Trace.size">948<span class="sig-name descname"><span class="pre">size</span></span><a class="headerlink" href="#tracemalloc.Trace.size" title="Link to this definition">¶</a></dt>949<dd><p>Size of the memory block in bytes (<code class="docutils literal notranslate"><span class="pre">int</span></code>).</p>950</dd></dl>951 952<dl class="py attribute">953<dt class="sig sig-object py" id="tracemalloc.Trace.traceback">954<span class="sig-name descname"><span class="pre">traceback</span></span><a class="headerlink" href="#tracemalloc.Trace.traceback" title="Link to this definition">¶</a></dt>955<dd><p>Traceback where the memory block was allocated, <a class="reference internal" href="#tracemalloc.Traceback" title="tracemalloc.Traceback"><code class="xref py py-class docutils literal notranslate"><span class="pre">Traceback</span></code></a>956instance.</p>957</dd></dl>958 959</dd></dl>960 961</section>962<section id="traceback">963<h3>Traceback<a class="headerlink" href="#traceback" title="Link to this heading">¶</a></h3>964<dl class="py class">965<dt class="sig sig-object py" id="tracemalloc.Traceback">966<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tracemalloc.</span></span><span class="sig-name descname"><span class="pre">Traceback</span></span><a class="headerlink" href="#tracemalloc.Traceback" title="Link to this definition">¶</a></dt>967<dd><p>Sequence of <a class="reference internal" href="#tracemalloc.Frame" title="tracemalloc.Frame"><code class="xref py py-class docutils literal notranslate"><span class="pre">Frame</span></code></a> instances sorted from the oldest frame to the968most recent frame.</p>969<p>A traceback contains at least <code class="docutils literal notranslate"><span class="pre">1</span></code> frame. If the <code class="docutils literal notranslate"><span class="pre">tracemalloc</span></code> module970failed to get a frame, the filename <code class="docutils literal notranslate"><span class="pre">"<unknown>"</span></code> at line number <code class="docutils literal notranslate"><span class="pre">0</span></code> is971used.</p>972<p>When a snapshot is taken, tracebacks of traces are limited to973<a class="reference internal" href="#tracemalloc.get_traceback_limit" title="tracemalloc.get_traceback_limit"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_traceback_limit()</span></code></a> frames. See the <a class="reference internal" href="#tracemalloc.take_snapshot" title="tracemalloc.take_snapshot"><code class="xref py py-func docutils literal notranslate"><span class="pre">take_snapshot()</span></code></a> function.974The original number of frames of the traceback is stored in the975<a class="reference internal" href="#tracemalloc.Traceback.total_nframe" title="tracemalloc.Traceback.total_nframe"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Traceback.total_nframe</span></code></a> attribute. That allows one to know if a traceback976has been truncated by the traceback limit.</p>977<p>The <a class="reference internal" href="#tracemalloc.Trace.traceback" title="tracemalloc.Trace.traceback"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Trace.traceback</span></code></a> attribute is a <code class="xref py py-class docutils literal notranslate"><span class="pre">Traceback</span></code> instance.</p>978<div class="versionchanged">979<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>980</div>981<dl class="py attribute">982<dt class="sig sig-object py" id="tracemalloc.Traceback.total_nframe">983<span class="sig-name descname"><span class="pre">total_nframe</span></span><a class="headerlink" href="#tracemalloc.Traceback.total_nframe" title="Link to this definition">¶</a></dt>984<dd><p>Total number of frames that composed the traceback before truncation.985This attribute can be set to <code class="docutils literal notranslate"><span class="pre">None</span></code> if the information is not986available.</p>987</dd></dl>988 989<div class="versionchanged">990<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 class="xref py py-attr docutils literal notranslate"><span class="pre">Traceback.total_nframe</span></code></a> attribute was added.</p>991</div>992<dl class="py method">993<dt class="sig sig-object py" id="tracemalloc.Traceback.format">994<span class="sig-name descname"><span class="pre">format</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">limit</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">most_recent_first</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tracemalloc.Traceback.format" title="Link to this definition">¶</a></dt>995<dd><p>Format the traceback as a list of lines. Use the <a class="reference internal" href="linecache.html#module-linecache" title="linecache: Provides random access to individual lines from text files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">linecache</span></code></a> module to996retrieve lines from the source code. If <em>limit</em> is set, format the <em>limit</em>997most recent frames if <em>limit</em> is positive. Otherwise, format the998<code class="docutils literal notranslate"><span class="pre">abs(limit)</span></code> oldest frames. If <em>most_recent_first</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the order999of the formatted frames is reversed, returning the most recent frame first1000instead of last.</p>1001<p>Similar to the <a class="reference internal" href="traceback.html#traceback.format_tb" title="traceback.format_tb"><code class="xref py py-func docutils literal notranslate"><span class="pre">traceback.format_tb()</span></code></a> function, except that1002<code class="xref py py-meth docutils literal notranslate"><span class="pre">format()</span></code> does not include newlines.</p>1003<p>Example:</p>1004<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="s2">"Traceback (most recent call first):"</span><span class="p">)</span>1005<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">traceback</span><span class="p">:</span>1006 <span class="nb">print</span><span class="p">(</span><span class="n">line</span><span class="p">)</span>1007</pre></div>1008</div>1009<p>Output:</p>1010<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">first</span><span class="p">):</span>1011 <span class="n">File</span> <span class="s2">"test.py"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">9</span>1012 <span class="n">obj</span> <span class="o">=</span> <span class="n">Object</span><span class="p">()</span>1013 <span class="n">File</span> <span class="s2">"test.py"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">12</span>1014 <span class="n">tb</span> <span class="o">=</span> <span class="n">tracemalloc</span><span class="o">.</span><span class="n">get_object_traceback</span><span class="p">(</span><span class="n">f</span><span class="p">())</span>1015</pre></div>1016</div>1017</dd></dl>1018 1019</dd></dl>1020 1021</section>1022</section>1023</section>1024 1025 1026 <div class="clearer"></div>1027 </div>1028 </div>1029 </div>1030 <div class="sphinxsidebar" role="navigation" aria-label="Main">1031 <div class="sphinxsidebarwrapper">1032 <div>1033 <h3><a href="../contents.html">Table of Contents</a></h3>1034 <ul>1035<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> — Trace memory allocations</a><ul>1036<li><a class="reference internal" href="#examples">Examples</a><ul>1037<li><a class="reference internal" href="#display-the-top-10">Display the top 10</a></li>1038<li><a class="reference internal" href="#compute-differences">Compute differences</a></li>1039<li><a class="reference internal" href="#get-the-traceback-of-a-memory-block">Get the traceback of a memory block</a></li>1040<li><a class="reference internal" href="#pretty-top">Pretty top</a><ul>1041<li><a class="reference internal" href="#record-the-current-and-peak-size-of-all-traced-memory-blocks">Record the current and peak size of all traced memory blocks</a></li>1042</ul>1043</li>1044</ul>1045</li>1046<li><a class="reference internal" href="#api">API</a><ul>1047<li><a class="reference internal" href="#functions">Functions</a></li>1048<li><a class="reference internal" href="#domainfilter">DomainFilter</a></li>1049<li><a class="reference internal" href="#filter">Filter</a></li>1050<li><a class="reference internal" href="#frame">Frame</a></li>1051<li><a class="reference internal" href="#snapshot">Snapshot</a></li>1052<li><a class="reference internal" href="#statistic">Statistic</a></li>1053<li><a class="reference internal" href="#statisticdiff">StatisticDiff</a></li>1054<li><a class="reference internal" href="#trace">Trace</a></li>1055<li><a class="reference internal" href="#traceback">Traceback</a></li>1056</ul>1057</li>1058</ul>1059</li>1060</ul>1061 1062 </div>1063 <div>1064 <h4>Previous topic</h4>1065 <p class="topless"><a href="trace.html"1066 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">trace</span></code> — Trace or track Python statement execution</a></p>1067 </div>1068 <div>1069 <h4>Next topic</h4>1070 <p class="topless"><a href="distribution.html"1071 title="next chapter">Software Packaging and Distribution</a></p>1072 </div>1073 <script>1074 document.addEventListener('DOMContentLoaded', () => {1075 const title = document.querySelector('meta[property="og:title"]').content;1076 const elements = document.querySelectorAll('.improvepage');1077 const pageurl = window.location.href.split('?')[0];1078 elements.forEach(element => {1079 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));1080 url.searchParams.set('pagetitle', title);1081 url.searchParams.set('pageurl', pageurl);1082 url.searchParams.set('pagesource', "library/tracemalloc.rst");1083 element.href = url.toString();1084 });1085 });1086 </script>1087 <div role="note" aria-label="source link">1088 <h3>This page</h3>1089 <ul class="this-page-menu">1090 <li><a href="../bugs.html">Report a bug</a></li>1091 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>1092 <li>1093 <a href="https://github.com/python/cpython/blob/main/Doc/library/tracemalloc.rst?plain=1"1094 rel="nofollow">Show source1095 </a>1096 </li>1097 1098 </ul>1099 </div>1100 </div>1101<div id="sidebarbutton" title="Collapse sidebar">1102<span>«</span>1103</div>1104 1105 </div>1106 <div class="clearer"></div>1107 </div> 1108 <div class="related" role="navigation" aria-label="Related">1109 <h3>Navigation</h3>1110 <ul>1111 <li class="right" style="margin-right: 10px">1112 <a href="../genindex.html" title="General Index"1113 >index</a></li>1114 <li class="right" >1115 <a href="../py-modindex.html" title="Python Module Index"1116 >modules</a> |</li>1117 <li class="right" >1118 <a href="distribution.html" title="Software Packaging and Distribution"1119 >next</a> |</li>1120 <li class="right" >1121 <a href="trace.html" title="trace — Trace or track Python statement execution"1122 >previous</a> |</li>1123 1124 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>1125 <li><a href="https://www.python.org/">Python</a> »</li>1126 <li class="switchers">1127 <div class="language_switcher_placeholder"></div>1128 <div class="version_switcher_placeholder"></div>1129 </li>1130 <li>1131 1132 </li>1133 <li id="cpython-language-and-version">1134 <a href="../index.html">3.15.0a6 Documentation</a> »1135 </li>1136 1137 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>1138 <li class="nav-item nav-item-2"><a href="debug.html" >Debugging and profiling</a> »</li>1139 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">tracemalloc</span></code> — Trace memory allocations</a></li>1140 <li class="right">1141 1142 1143 <div class="inline-search" role="search">1144 <form class="inline-search" action="../search.html" method="get">1145 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">1146 <input type="submit" value="Go">1147 </form>1148 </div>1149 |1150 </li>1151 <li class="right">1152<label class="theme-selector-label">1153 Theme1154 <select class="theme-selector" oninput="activateTheme(this.value)">1155 <option value="auto" selected>Auto</option>1156 <option value="light">Light</option>1157 <option value="dark">Dark</option>1158 </select>1159</label> |</li>1160 1161 </ul>1162 </div> 1163 <div class="footer">1164 © <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.1165 <br>1166 This page is licensed under the Python Software Foundation License Version 2.1167 <br>1168 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.1169 <br>1170 1171 See <a href="/license.html">History and License</a> for more information.<br>1172 1173 1174 <br>1175 1176 The Python Software Foundation is a non-profit corporation.1177<a href="https://www.python.org/psf/donations/">Please donate.</a>1178<br>1179 <br>1180 Last updated on Mar 10, 2026 (08:58 UTC).1181 1182 <a href="/bugs.html">Found a bug</a>?1183 1184 <br>1185 1186 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.1187 </div>1188 1189 </body>1190</html>