What does tracemalloc measure and how do you use it to find memory leaks?

Short answer

tracemalloc tracks the memory allocations Python makes and where they happen in the code, and lets you take snapshots and compare them to see which lines' memory is growing.

Explanation

Take a snapshot before the operation and after it (or after repeating it several times), then compare them to see the fastest-growing lines. tracemalloc does not see memory that C libraries allocate directly outside Python's own allocator, so it may differ from the RSS shown by the operating system. Common causes of leaks: unbounded caches, global lists that accumulate, callbacks holding references, and reference cycles with __del__.

Code example

import tracemalloc

tracemalloc.start()
before = tracemalloc.take_snapshot()

for _ in range(1000):
    handle_request()

after = tracemalloc.take_snapshot()
for stat in after.compare_to(before, "lineno")[:5]:
    print(stat)

Common mistakes

• Comparing the numbers with total process memory and expecting them to match.
• Taking a single snapshot instead of comparing two.

Follow-up questions

• How do you deal with heavy object creation in a hot loop?

Sources

• Python documentation — tracemalloc