1:mod:`tracemalloc` --- Trace memory allocations
2===============================================
3
4.. module:: tracemalloc
5   :synopsis: Trace memory allocations.
6
7.. versionadded:: 3.4
8
9**Source code:** :source:`Lib/tracemalloc.py`
10
11--------------
12
13The tracemalloc module is a debug tool to trace memory blocks allocated by
14Python. It provides the following information:
15
16* Traceback where an object was allocated
17* Statistics on allocated memory blocks per filename and per line number:
18  total size, number and average size of allocated memory blocks
19* Compute the differences between two snapshots to detect memory leaks
20
21To trace most memory blocks allocated by Python, the module should be started
22as early as possible by setting the :envvar:`PYTHONTRACEMALLOC` environment
23variable to ``1``, or by using :option:`-X` ``tracemalloc`` command line
24option. The :func:`tracemalloc.start` function can be called at runtime to
25start tracing Python memory allocations.
26
27By default, a trace of an allocated memory block only stores the most recent
28frame (1 frame). To store 25 frames at startup: set the
29:envvar:`PYTHONTRACEMALLOC` environment variable to ``25``, or use the
30:option:`-X` ``tracemalloc=25`` command line option.
31
32
33Examples
34--------
35
36Display the top 10
37^^^^^^^^^^^^^^^^^^
38
39Display the 10 files allocating the most memory::
40
41    import tracemalloc
42
43    tracemalloc.start()
44
45    # ... run your application ...
46
47    snapshot = tracemalloc.take_snapshot()
48    top_stats = snapshot.statistics('lineno')
49
50    print("[ Top 10 ]")
51    for stat in top_stats[:10]:
52        print(stat)
53
54
55Example of output of the Python test suite::
56
57    [ Top 10 ]
58    <frozen importlib._bootstrap>:716: size=4855 KiB, count=39328, average=126 B
59    <frozen importlib._bootstrap>:284: size=521 KiB, count=3199, average=167 B
60    /usr/lib/python3.4/collections/__init__.py:368: size=244 KiB, count=2315, average=108 B
61    /usr/lib/python3.4/unittest/case.py:381: size=185 KiB, count=779, average=243 B
62    /usr/lib/python3.4/unittest/case.py:402: size=154 KiB, count=378, average=416 B
63    /usr/lib/python3.4/abc.py:133: size=88.7 KiB, count=347, average=262 B
64    <frozen importlib._bootstrap>:1446: size=70.4 KiB, count=911, average=79 B
65    <frozen importlib._bootstrap>:1454: size=52.0 KiB, count=25, average=2131 B
66    <string>:5: size=49.7 KiB, count=148, average=344 B
67    /usr/lib/python3.4/sysconfig.py:411: size=48.0 KiB, count=1, average=48.0 KiB
68
69We can see that Python loaded ``4855 KiB`` data (bytecode and constants) from
70modules and that the :mod:`collections` module allocated ``244 KiB`` to build
71:class:`~collections.namedtuple` types.
72
73See :meth:`Snapshot.statistics` for more options.
74
75
76Compute differences
77^^^^^^^^^^^^^^^^^^^
78
79Take two snapshots and display the differences::
80
81    import tracemalloc
82    tracemalloc.start()
83    # ... start your application ...
84
85    snapshot1 = tracemalloc.take_snapshot()
86    # ... call the function leaking memory ...
87    snapshot2 = tracemalloc.take_snapshot()
88
89    top_stats = snapshot2.compare_to(snapshot1, 'lineno')
90
91    print("[ Top 10 differences ]")
92    for stat in top_stats[:10]:
93        print(stat)
94
95Example of output before/after running some tests of the Python test suite::
96
97    [ Top 10 differences ]
98    <frozen importlib._bootstrap>:716: size=8173 KiB (+4428 KiB), count=71332 (+39369), average=117 B
99    /usr/lib/python3.4/linecache.py:127: size=940 KiB (+940 KiB), count=8106 (+8106), average=119 B
100    /usr/lib/python3.4/unittest/case.py:571: size=298 KiB (+298 KiB), count=589 (+589), average=519 B
101    <frozen importlib._bootstrap>:284: size=1005 KiB (+166 KiB), count=7423 (+1526), average=139 B
102    /usr/lib/python3.4/mimetypes.py:217: size=112 KiB (+112 KiB), count=1334 (+1334), average=86 B
103    /usr/lib/python3.4/http/server.py:848: size=96.0 KiB (+96.0 KiB), count=1 (+1), average=96.0 KiB
104    /usr/lib/python3.4/inspect.py:1465: size=83.5 KiB (+83.5 KiB), count=109 (+109), average=784 B
105    /usr/lib/python3.4/unittest/mock.py:491: size=77.7 KiB (+77.7 KiB), count=143 (+143), average=557 B
106    /usr/lib/python3.4/urllib/parse.py:476: size=71.8 KiB (+71.8 KiB), count=969 (+969), average=76 B
107    /usr/lib/python3.4/contextlib.py:38: size=67.2 KiB (+67.2 KiB), count=126 (+126), average=546 B
108
109We can see that Python has loaded ``8173 KiB`` of module data (bytecode and
110constants), and that this is ``4428 KiB`` more than had been loaded before the
111tests, when the previous snapshot was taken. Similarly, the :mod:`linecache`
112module has cached ``940 KiB`` of Python source code to format tracebacks, all
113of it since the previous snapshot.
114
115If the system has little free memory, snapshots can be written on disk using
116the :meth:`Snapshot.dump` method to analyze the snapshot offline. Then use the
117:meth:`Snapshot.load` method reload the snapshot.
118
119
120Get the traceback of a memory block
121^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
122
123Code to display the traceback of the biggest memory block::
124
125    import tracemalloc
126
127    # Store 25 frames
128    tracemalloc.start(25)
129
130    # ... run your application ...
131
132    snapshot = tracemalloc.take_snapshot()
133    top_stats = snapshot.statistics('traceback')
134
135    # pick the biggest memory block
136    stat = top_stats[0]
137    print("%s memory blocks: %.1f KiB" % (stat.count, stat.size / 1024))
138    for line in stat.traceback.format():
139        print(line)
140
141Example of output of the Python test suite (traceback limited to 25 frames)::
142
143    903 memory blocks: 870.1 KiB
144      File "<frozen importlib._bootstrap>", line 716
145      File "<frozen importlib._bootstrap>", line 1036
146      File "<frozen importlib._bootstrap>", line 934
147      File "<frozen importlib._bootstrap>", line 1068
148      File "<frozen importlib._bootstrap>", line 619
149      File "<frozen importlib._bootstrap>", line 1581
150      File "<frozen importlib._bootstrap>", line 1614
151      File "/usr/lib/python3.4/doctest.py", line 101
152        import pdb
153      File "<frozen importlib._bootstrap>", line 284
154      File "<frozen importlib._bootstrap>", line 938
155      File "<frozen importlib._bootstrap>", line 1068
156      File "<frozen importlib._bootstrap>", line 619
157      File "<frozen importlib._bootstrap>", line 1581
158      File "<frozen importlib._bootstrap>", line 1614
159      File "/usr/lib/python3.4/test/support/__init__.py", line 1728
160        import doctest
161      File "/usr/lib/python3.4/test/test_pickletools.py", line 21
162        support.run_doctest(pickletools)
163      File "/usr/lib/python3.4/test/regrtest.py", line 1276
164        test_runner()
165      File "/usr/lib/python3.4/test/regrtest.py", line 976
166        display_failure=not verbose)
167      File "/usr/lib/python3.4/test/regrtest.py", line 761
168        match_tests=ns.match_tests)
169      File "/usr/lib/python3.4/test/regrtest.py", line 1563
170        main()
171      File "/usr/lib/python3.4/test/__main__.py", line 3
172        regrtest.main_in_temp_cwd()
173      File "/usr/lib/python3.4/runpy.py", line 73
174        exec(code, run_globals)
175      File "/usr/lib/python3.4/runpy.py", line 160
176        "__main__", fname, loader, pkg_name)
177
178We can see that the most memory was allocated in the :mod:`importlib` module to
179load data (bytecode and constants) from modules: ``870.1 KiB``. The traceback is
180where the :mod:`importlib` loaded data most recently: on the ``import pdb``
181line of the :mod:`doctest` module. The traceback may change if a new module is
182loaded.
183
184
185Pretty top
186^^^^^^^^^^
187
188Code to display the 10 lines allocating the most memory with a pretty output,
189ignoring ``<frozen importlib._bootstrap>`` and ``<unknown>`` files::
190
191    import linecache
192    import os
193    import tracemalloc
194
195    def display_top(snapshot, key_type='lineno', limit=10):
196        snapshot = snapshot.filter_traces((
197            tracemalloc.Filter(False, "<frozen importlib._bootstrap>"),
198            tracemalloc.Filter(False, "<unknown>"),
199        ))
200        top_stats = snapshot.statistics(key_type)
201
202        print("Top %s lines" % limit)
203        for index, stat in enumerate(top_stats[:limit], 1):
204            frame = stat.traceback[0]
205            # replace "/path/to/module/file.py" with "module/file.py"
206            filename = os.sep.join(frame.filename.split(os.sep)[-2:])
207            print("#%s: %s:%s: %.1f KiB"
208                  % (index, filename, frame.lineno, stat.size / 1024))
209            line = linecache.getline(frame.filename, frame.lineno).strip()
210            if line:
211                print('    %s' % line)
212
213        other = top_stats[limit:]
214        if other:
215            size = sum(stat.size for stat in other)
216            print("%s other: %.1f KiB" % (len(other), size / 1024))
217        total = sum(stat.size for stat in top_stats)
218        print("Total allocated size: %.1f KiB" % (total / 1024))
219
220    tracemalloc.start()
221
222    # ... run your application ...
223
224    snapshot = tracemalloc.take_snapshot()
225    display_top(snapshot)
226
227Example of output of the Python test suite::
228
229    Top 10 lines
230    #1: Lib/base64.py:414: 419.8 KiB
231        _b85chars2 = [(a + b) for a in _b85chars for b in _b85chars]
232    #2: Lib/base64.py:306: 419.8 KiB
233        _a85chars2 = [(a + b) for a in _a85chars for b in _a85chars]
234    #3: collections/__init__.py:368: 293.6 KiB
235        exec(class_definition, namespace)
236    #4: Lib/abc.py:133: 115.2 KiB
237        cls = super().__new__(mcls, name, bases, namespace)
238    #5: unittest/case.py:574: 103.1 KiB
239        testMethod()
240    #6: Lib/linecache.py:127: 95.4 KiB
241        lines = fp.readlines()
242    #7: urllib/parse.py:476: 71.8 KiB
243        for a in _hexdig for b in _hexdig}
244    #8: <string>:5: 62.0 KiB
245    #9: Lib/_weakrefset.py:37: 60.0 KiB
246        self.data = set()
247    #10: Lib/base64.py:142: 59.8 KiB
248        _b32tab2 = [a + b for a in _b32tab for b in _b32tab]
249    6220 other: 3602.8 KiB
250    Total allocated size: 5303.1 KiB
251
252See :meth:`Snapshot.statistics` for more options.
253
254
255API
256---
257
258Functions
259^^^^^^^^^
260
261.. function:: clear_traces()
262
263   Clear traces of memory blocks allocated by Python.
264
265   See also :func:`stop`.
266
267
268.. function:: get_object_traceback(obj)
269
270   Get the traceback where the Python object *obj* was allocated.
271   Return a :class:`Traceback` instance, or ``None`` if the :mod:`tracemalloc`
272   module is not tracing memory allocations or did not trace the allocation of
273   the object.
274
275   See also :func:`gc.get_referrers` and :func:`sys.getsizeof` functions.
276
277
278.. function:: get_traceback_limit()
279
280   Get the maximum number of frames stored in the traceback of a trace.
281
282   The :mod:`tracemalloc` module must be tracing memory allocations to
283   get the limit, otherwise an exception is raised.
284
285   The limit is set by the :func:`start` function.
286
287
288.. function:: get_traced_memory()
289
290   Get the current size and peak size of memory blocks traced by the
291   :mod:`tracemalloc` module as a tuple: ``(current: int, peak: int)``.
292
293
294.. function:: get_tracemalloc_memory()
295
296   Get the memory usage in bytes of the :mod:`tracemalloc` module used to store
297   traces of memory blocks.
298   Return an :class:`int`.
299
300
301.. function:: is_tracing()
302
303    ``True`` if the :mod:`tracemalloc` module is tracing Python memory
304    allocations, ``False`` otherwise.
305
306    See also :func:`start` and :func:`stop` functions.
307
308
309.. function:: start(nframe: int=1)
310
311   Start tracing Python memory allocations: install hooks on Python memory
312   allocators. Collected tracebacks of traces will be limited to *nframe*
313   frames. By default, a trace of a memory block only stores the most recent
314   frame: the limit is ``1``. *nframe* must be greater or equal to ``1``.
315
316   Storing more than ``1`` frame is only useful to compute statistics grouped
317   by ``'traceback'`` or to compute cumulative statistics: see the
318   :meth:`Snapshot.compare_to` and :meth:`Snapshot.statistics` methods.
319
320   Storing more frames increases the memory and CPU overhead of the
321   :mod:`tracemalloc` module. Use the :func:`get_tracemalloc_memory` function
322   to measure how much memory is used by the :mod:`tracemalloc` module.
323
324   The :envvar:`PYTHONTRACEMALLOC` environment variable
325   (``PYTHONTRACEMALLOC=NFRAME``) and the :option:`-X` ``tracemalloc=NFRAME``
326   command line option can be used to start tracing at startup.
327
328   See also :func:`stop`, :func:`is_tracing` and :func:`get_traceback_limit`
329   functions.
330
331
332.. function:: stop()
333
334   Stop tracing Python memory allocations: uninstall hooks on Python memory
335   allocators. Also clears all previously collected traces of memory blocks
336   allocated by Python.
337
338   Call :func:`take_snapshot` function to take a snapshot of traces before
339   clearing them.
340
341   See also :func:`start`, :func:`is_tracing` and :func:`clear_traces`
342   functions.
343
344
345.. function:: take_snapshot()
346
347   Take a snapshot of traces of memory blocks allocated by Python. Return a new
348   :class:`Snapshot` instance.
349
350   The snapshot does not include memory blocks allocated before the
351   :mod:`tracemalloc` module started to trace memory allocations.
352
353   Tracebacks of traces are limited to :func:`get_traceback_limit` frames. Use
354   the *nframe* parameter of the :func:`start` function to store more frames.
355
356   The :mod:`tracemalloc` module must be tracing memory allocations to take a
357   snapshot, see the :func:`start` function.
358
359   See also the :func:`get_object_traceback` function.
360
361
362DomainFilter
363^^^^^^^^^^^^
364
365.. class:: DomainFilter(inclusive: bool, domain: int)
366
367   Filter traces of memory blocks by their address space (domain).
368
369   .. versionadded:: 3.6
370
371   .. attribute:: inclusive
372
373      If *inclusive* is ``True`` (include), match memory blocks allocated
374      in the address space :attr:`domain`.
375
376      If *inclusive* is ``False`` (exclude), match memory blocks not allocated
377      in the address space :attr:`domain`.
378
379   .. attribute:: domain
380
381      Address space of a memory block (``int``). Read-only property.
382
383
384Filter
385^^^^^^
386
387.. class:: Filter(inclusive: bool, filename_pattern: str, lineno: int=None, all_frames: bool=False, domain: int=None)
388
389   Filter on traces of memory blocks.
390
391   See the :func:`fnmatch.fnmatch` function for the syntax of
392   *filename_pattern*. The ``'.pyc'`` file extension is
393   replaced with ``'.py'``.
394
395   Examples:
396
397   * ``Filter(True, subprocess.__file__)`` only includes traces of the
398     :mod:`subprocess` module
399   * ``Filter(False, tracemalloc.__file__)`` excludes traces of the
400     :mod:`tracemalloc` module
401   * ``Filter(False, "<unknown>")`` excludes empty tracebacks
402
403
404   .. versionchanged:: 3.5
405      The ``'.pyo'`` file extension is no longer replaced with ``'.py'``.
406
407   .. versionchanged:: 3.6
408      Added the :attr:`domain` attribute.
409
410
411   .. attribute:: domain
412
413      Address space of a memory block (``int`` or ``None``).
414
415   .. attribute:: inclusive
416
417      If *inclusive* is ``True`` (include), only match memory blocks allocated
418      in a file with a name matching :attr:`filename_pattern` at line number
419      :attr:`lineno`.
420
421      If *inclusive* is ``False`` (exclude), ignore memory blocks allocated in
422      a file with a name matching :attr:`filename_pattern` at line number
423      :attr:`lineno`.
424
425   .. attribute:: lineno
426
427      Line number (``int``) of the filter. If *lineno* is ``None``, the filter
428      matches any line number.
429
430   .. attribute:: filename_pattern
431
432      Filename pattern of the filter (``str``). Read-only property.
433
434   .. attribute:: all_frames
435
436      If *all_frames* is ``True``, all frames of the traceback are checked. If
437      *all_frames* is ``False``, only the most recent frame is checked.
438
439      This attribute has no effect if the traceback limit is ``1``.  See the
440      :func:`get_traceback_limit` function and :attr:`Snapshot.traceback_limit`
441      attribute.
442
443
444Frame
445^^^^^
446
447.. class:: Frame
448
449   Frame of a traceback.
450
451   The :class:`Traceback` class is a sequence of :class:`Frame` instances.
452
453   .. attribute:: filename
454
455      Filename (``str``).
456
457   .. attribute:: lineno
458
459      Line number (``int``).
460
461
462Snapshot
463^^^^^^^^
464
465.. class:: Snapshot
466
467   Snapshot of traces of memory blocks allocated by Python.
468
469   The :func:`take_snapshot` function creates a snapshot instance.
470
471   .. method:: compare_to(old_snapshot: Snapshot, key_type: str, cumulative: bool=False)
472
473      Compute the differences with an old snapshot. Get statistics as a sorted
474      list of :class:`StatisticDiff` instances grouped by *key_type*.
475
476      See the :meth:`Snapshot.statistics` method for *key_type* and *cumulative*
477      parameters.
478
479      The result is sorted from the biggest to the smallest by: absolute value
480      of :attr:`StatisticDiff.size_diff`, :attr:`StatisticDiff.size`, absolute
481      value of :attr:`StatisticDiff.count_diff`, :attr:`Statistic.count` and
482      then by :attr:`StatisticDiff.traceback`.
483
484
485   .. method:: dump(filename)
486
487      Write the snapshot into a file.
488
489      Use :meth:`load` to reload the snapshot.
490
491
492   .. method:: filter_traces(filters)
493
494      Create a new :class:`Snapshot` instance with a filtered :attr:`traces`
495      sequence, *filters* is a list of :class:`DomainFilter` and
496      :class:`Filter` instances.  If *filters* is an empty list, return a new
497      :class:`Snapshot` instance with a copy of the traces.
498
499      All inclusive filters are applied at once, a trace is ignored if no
500      inclusive filters match it. A trace is ignored if at least one exclusive
501      filter matches it.
502
503      .. versionchanged:: 3.6
504         :class:`DomainFilter` instances are now also accepted in *filters*.
505
506
507   .. classmethod:: load(filename)
508
509      Load a snapshot from a file.
510
511      See also :meth:`dump`.
512
513
514   .. method:: statistics(key_type: str, cumulative: bool=False)
515
516      Get statistics as a sorted list of :class:`Statistic` instances grouped
517      by *key_type*:
518
519      =====================  ========================
520      key_type               description
521      =====================  ========================
522      ``'filename'``         filename
523      ``'lineno'``           filename and line number
524      ``'traceback'``        traceback
525      =====================  ========================
526
527      If *cumulative* is ``True``, cumulate size and count of memory blocks of
528      all frames of the traceback of a trace, not only the most recent frame.
529      The cumulative mode can only be used with *key_type* equals to
530      ``'filename'`` and ``'lineno'``.
531
532      The result is sorted from the biggest to the smallest by:
533      :attr:`Statistic.size`, :attr:`Statistic.count` and then by
534      :attr:`Statistic.traceback`.
535
536
537   .. attribute:: traceback_limit
538
539      Maximum number of frames stored in the traceback of :attr:`traces`:
540      result of the :func:`get_traceback_limit` when the snapshot was taken.
541
542   .. attribute:: traces
543
544      Traces of all memory blocks allocated by Python: sequence of
545      :class:`Trace` instances.
546
547      The sequence has an undefined order. Use the :meth:`Snapshot.statistics`
548      method to get a sorted list of statistics.
549
550
551Statistic
552^^^^^^^^^
553
554.. class:: Statistic
555
556   Statistic on memory allocations.
557
558   :func:`Snapshot.statistics` returns a list of :class:`Statistic` instances.
559
560   See also the :class:`StatisticDiff` class.
561
562   .. attribute:: count
563
564      Number of memory blocks (``int``).
565
566   .. attribute:: size
567
568      Total size of memory blocks in bytes (``int``).
569
570   .. attribute:: traceback
571
572      Traceback where the memory block was allocated, :class:`Traceback`
573      instance.
574
575
576StatisticDiff
577^^^^^^^^^^^^^
578
579.. class:: StatisticDiff
580
581   Statistic difference on memory allocations between an old and a new
582   :class:`Snapshot` instance.
583
584   :func:`Snapshot.compare_to` returns a list of :class:`StatisticDiff`
585   instances. See also the :class:`Statistic` class.
586
587   .. attribute:: count
588
589      Number of memory blocks in the new snapshot (``int``): ``0`` if
590      the memory blocks have been released in the new snapshot.
591
592   .. attribute:: count_diff
593
594      Difference of number of memory blocks between the old and the new
595      snapshots (``int``): ``0`` if the memory blocks have been allocated in
596      the new snapshot.
597
598   .. attribute:: size
599
600      Total size of memory blocks in bytes in the new snapshot (``int``):
601      ``0`` if the memory blocks have been released in the new snapshot.
602
603   .. attribute:: size_diff
604
605      Difference of total size of memory blocks in bytes between the old and
606      the new snapshots (``int``): ``0`` if the memory blocks have been
607      allocated in the new snapshot.
608
609   .. attribute:: traceback
610
611      Traceback where the memory blocks were allocated, :class:`Traceback`
612      instance.
613
614
615Trace
616^^^^^
617
618.. class:: Trace
619
620   Trace of a memory block.
621
622   The :attr:`Snapshot.traces` attribute is a sequence of :class:`Trace`
623   instances.
624
625   .. attribute:: size
626
627      Size of the memory block in bytes (``int``).
628
629   .. attribute:: traceback
630
631      Traceback where the memory block was allocated, :class:`Traceback`
632      instance.
633
634
635Traceback
636^^^^^^^^^
637
638.. class:: Traceback
639
640   Sequence of :class:`Frame` instances sorted from the most recent frame to
641   the oldest frame.
642
643   A traceback contains at least ``1`` frame. If the ``tracemalloc`` module
644   failed to get a frame, the filename ``"<unknown>"`` at line number ``0`` is
645   used.
646
647   When a snapshot is taken, tracebacks of traces are limited to
648   :func:`get_traceback_limit` frames. See the :func:`take_snapshot` function.
649
650   The :attr:`Trace.traceback` attribute is an instance of :class:`Traceback`
651   instance.
652
653   .. method:: format(limit=None)
654
655      Format the traceback as a list of lines with newlines.  Use the
656      :mod:`linecache` module to retrieve lines from the source code.  If
657      *limit* is set, only format the *limit* most recent frames.
658
659      Similar to the :func:`traceback.format_tb` function, except that
660      :meth:`.format` does not include newlines.
661
662      Example::
663
664          print("Traceback (most recent call first):")
665          for line in traceback:
666              print(line)
667
668      Output::
669
670          Traceback (most recent call first):
671            File "test.py", line 9
672              obj = Object()
673            File "test.py", line 12
674              tb = tracemalloc.get_object_traceback(f())
675