Python memory management: refcounting and the GC
What you’ll learn
Section titled “What you’ll learn”- How reference counting frees most objects the moment they become unused.
- Why reference cycles need the separate garbage collector, and how its generations work.
- What immortal objects (3.12), the 3.14 garbage-collector change and revert, and the free-threaded build mean for you.
- Why
sys.getrefcountandsys.getsizeofmislead, and why freed memory does not always go back to the operating system. - How to find a real leak with
tracemallocand fix it.
Summary
Section titled “Summary”CPython manages memory automatically with two cooperating mechanisms. Reference counting tracks how many references point at each object and frees the object as soon as the count reaches zero. A cycle-detecting garbage collector (the gc module) periodically finds groups of objects that refer to each other but are unreachable from the rest of the program, which reference counting alone can never free. Underneath, small objects come from CPython’s own allocator (pymalloc on the default build, mimalloc on the free-threaded build). All of this is a CPython implementation detail: the language only promises that unreachable objects may be reclaimed, and PyPy, for example, uses a different collector.
The problem it solves
Section titled “The problem it solves”Manual memory management (C’s malloc and free) invites leaks and use-after-free bugs. Tracing collectors (Java, Go, .NET) avoid those but free garbage only when a collection runs. CPython’s reference counting frees most objects at the exact statement that drops the last reference.
Running the samples: each sample is a complete script. Save it as a .py file and run it with Python 3.14 (python3 sample.py). Outputs come from CPython 3.14.6 on 64-bit Linux. Reference counts, object sizes and memory figures are implementation- and machine-dependent.
import sys
class Invoice: def __init__(self, number: str) -> None: self.number = number
def __del__(self) -> None: print(f" freed {self.number}")
inv = Invoice("INV-1001")print("refcount:", sys.getrefcount(inv)) # includes getrefcount's own argumentbatch = [inv] # a list now refers to it tooprint("refcount:", sys.getrefcount(inv))
print("del inv")del inv # the list still holds itprint("batch.clear()")batch.clear() # last reference gone: freed right hereprint("after clear")
print("None is immortal:", sys._is_immortal(None))Output:
refcount: 2refcount: 3del invbatch.clear() freed INV-1001after clearNone is immortal: Truedel inv removes a name, not the object: the list still refers to the invoice. The object is freed during batch.clear(), before the next line runs.
How it works
Section titled “How it works”Reference counting
Section titled “Reference counting”Every object header holds a reference count. Binding a name, storing the object in a container or passing it as an argument increments it; unbinding or removing decrements it. At zero, CPython runs __del__ if defined, releases the object’s own references (which can cascade) and returns the memory to the allocator.
sys.getrefcount() is a debugging aid, not an API. Its result includes the temporary reference made by the call itself. Since Python 3.12 (PEP 683), objects such as None, True and small integers are immortal: their count is fixed at a very large value and never changes. Python 3.14 also lets the interpreter borrow references internally, so What’s New in 3.14 warns that getrefcount can return smaller values than older versions. The documentation says not to rely on the value other than 0 or 1. sys._is_immortal() (3.14) identifies immortal objects.
The cycle collector
Section titled “The cycle collector”Reference counting cannot free a cycle: each member is referenced by another member, so no count reaches zero.
import gc
class Order: def __init__(self, order_id: str) -> None: self.order_id = order_id self.lines: list["OrderLine"] = []
def __del__(self) -> None: print(f" freed {self.order_id}")
class OrderLine: def __init__(self, order: Order, sku: str) -> None: self.order = order # back-reference: order -> line -> order self.sku = sku
print("thresholds:", gc.get_threshold())gc.disable() # make the timing visible for this demoorder = Order("ORD-2001")order.lines.append(OrderLine(order, "MUG-01"))print("del order")del order # refcounts never reach zero: a cycleprint("still alive until the collector runs")print("gc.collect() found", gc.collect(), "unreachable objects")gc.enable()Output (default build):
thresholds: (2000, 10, 10)del orderstill alive until the collector runs freed ORD-2001gc.collect() found 3 unreachable objectsThe three objects are the Order, its OrderLine and the lines list. The count is an implementation detail; the free-threaded build reported 152 for the same script because its collector works differently.
The collector tracks only container objects (instances, lists, dicts, sets and so on), because only they can form cycles; gc.is_tracked() tells you whether an object is tracked. On the default build, tracked objects live in three generations. A collection of the youngest generation starts when allocations minus deallocations exceed the first threshold (2000 in 3.14), survivors move to an older generation, and older generations are examined less often. Since Python 3.4 (PEP 442), objects in cycles that define __del__ are collected normally instead of being parked in gc.garbage.
Python 3.14.0 to 3.14.4 shipped a new incremental collector with two generations. Because of reports of significant memory pressure in production, Python 3.14.5 reverted to the 3.13 generational collector. If you tuned gc.set_threshold or interpreted gc.get_count() on an early 3.14 patch release, recheck it on 3.14.5 or later.
The free-threaded build
Section titled “The free-threaded build”The free-threaded build (PEP 703; experimental in 3.13, supported in 3.14) keeps reference counting but makes it thread-safe with biased reference counting: the owning thread updates a count cheaply, other threads use atomic operations. Its collector pauses all threads (“stop the world”), always scans every container object, and skips a scheduled collection if process memory has not grown by 10% since the last one and net allocations stay under 40 times the first threshold. Destruction of objects shared between threads can be delayed until the next collection. On the default build, the GIL is what makes plain, non-atomic reference counting safe; see the GIL.
Allocators and returning memory
Section titled “Allocators and returning memory”Objects of 512 bytes or less come from pymalloc, which carves 1 MiB arenas (on 64-bit platforms) into pools of fixed-size blocks; larger requests go to the system allocator. The free-threaded build uses mimalloc instead (3.13). An arena is returned to the operating system only when every block in it is free, so a process that built a million small objects and freed most of them can keep a large resident size. That is fragmentation, not a leak.
sys.getsizeof() reports only the object itself, not what it refers to:
import sys
skus = ["MUG-01", "PEN-02", "CAP-03"] * 1000print("list object only:", sys.getsizeof(skus), "bytes")print("list + its strings:", sys.getsizeof(skus) + sum(sys.getsizeof(s) for s in set(skus)), "bytes")print("empty dict:", sys.getsizeof({}), " empty list:", sys.getsizeof([]))Output:
list object only: 24056 byteslist + its strings: 24197 bytesempty dict: 64 empty list: 56The list holds 3,000 pointers to only three distinct string objects, which is why adding them changes so little.
Realistic example
Section titled “Realistic example”OrdersPortal’s memory grows a little every hour. Most Python “leaks” are objects that are still referenced, so the tool to use is tracemalloc, which records where each block was allocated. Compare two snapshots taken around a period of traffic:
import gcimport tracemalloc
_rendered: dict[str, str] = {} # the leak: an unbounded module-level cache
def render_receipt(order_id: str) -> str: if order_id not in _rendered: _rendered[order_id] = f"<html><body>Receipt for {order_id}</body></html>" * 20 return _rendered[order_id]
def handle_requests(start: int, count: int) -> None: for n in range(start, start + count): render_receipt(f"ORD-{n}")
tracemalloc.start()handle_requests(0, 1_000) # warm-upgc.collect()before = tracemalloc.take_snapshot()
handle_requests(1_000, 5_000) # "an hour of traffic"gc.collect()after = tracemalloc.take_snapshot()
for stat in after.compare_to(before, "lineno")[:2]: frame = stat.traceback[0] print(f"line {frame.lineno}: +{stat.size_diff / 1024:.0f} KiB in {stat.count_diff:+} blocks")current, peak = tracemalloc.get_traced_memory()print(f"traced now: {current / 1e6:.1f} MB, peak: {peak / 1e6:.1f} MB")Output (sizes implementation-dependent):
line 8: +4870 KiB in +5000 blocksline 13: +239 KiB in +5000 blockstraced now: 6.2 MB, peak: 6.2 MBLine 8 stores rendered receipts and line 13 builds the keys: 5,000 new blocks each for 5,000 requests that never repeat. The fix is to bound the cache:
import gcimport tracemallocfrom functools import lru_cache
@lru_cache(maxsize=1_000) # the fix: a bounded cachedef render_receipt(order_id: str) -> str: return f"<html><body>Receipt for {order_id}</body></html>" * 20
def handle_requests(start: int, count: int) -> None: for n in range(start, start + count): render_receipt(f"ORD-{n}")
tracemalloc.start()handle_requests(0, 1_000)gc.collect()before = tracemalloc.take_snapshot()
handle_requests(1_000, 5_000)gc.collect()after = tracemalloc.take_snapshot()
growth = sum(stat.size_diff for stat in after.compare_to(before, "lineno"))print(f"net growth: {growth / 1024:.0f} KiB", render_receipt.cache_info())Output:
net growth: 49 KiB CacheInfo(hits=0, misses=6000, maxsize=1000, currsize=1000)The cache info also shows the original cache never helped: zero hits. Tracing adds overhead to every allocation, so enable tracemalloc in staging or for a short window.
Common mistakes
Section titled “Common mistakes”- Thinking
delfrees an object. It removes one reference. The object is freed only when no references remain. - Relying on
__del__for cleanup. It may run late (cycles, other implementations, free-threaded delays) or at interpreter shutdown when modules are half torn down. Usewithand context managers for files, locks and connections. - Calling
gc.collect()in a hot path. A full collection scans every tracked object. Call it in tests or after a large teardown, not per request. - Disabling the collector globally to “save time”. Cycles then accumulate forever. If pauses matter, use
gc.freeze()after start-up instead (below). - Measuring with
sys.getsizeofalone. It is shallow; usetracemallocor a deep-size tool. - Expecting resident memory to drop after freeing. Fragmented arenas stay mapped; recycle worker processes if peak usage is the problem.
When to use it and when not to
Section titled “When to use it and when not to”You do not opt in to memory management, but you choose which tools to reach for:
| Goal | Tool | Notes |
|---|---|---|
| Find what is growing | tracemalloc snapshots |
Allocation site per line; overhead while tracing |
| Find who holds an object | gc.get_referrers() |
Slow; debugging only |
| Avoid owning an object | weakref |
Caches, observers, back-references |
| Fewer bytes per instance | __slots__ |
No per-instance __dict__ |
| Bound a cache | lru_cache |
Evicts by recency |
Share memory after fork |
gc.disable() early, gc.freeze() before fork, gc.enable() in children |
Documented pattern to reduce copy-on-write |
| Free a cycle now | gc.collect() |
Tests and batch teardown |
Compatibility
Section titled “Compatibility”| Version | Change |
|---|---|
| 2.0 | Cycle-detecting collector added alongside reference counting. |
| 3.4 | PEP 442: cycles with __del__ are collected. |
| 3.6 | pymalloc is the default for PyMem_Malloc too. |
| 3.7 | gc.freeze(). |
| 3.12 | PEP 683 immortal objects. |
| 3.13 | Free-threaded build (experimental) with mimalloc and biased reference counting. |
| 3.14 | sys._is_immortal(); internal borrowed references can lower getrefcount values; 3.14.0 to 3.14.4 ship an incremental collector with two generations. |
| 3.14.5 | Reverted to the 3.13 generational collector. |
Interview questions
Section titled “Interview questions”1. Why can’t reference counting free a parent and child that point at each other, and how do you avoid relying on the collector?
Each holds a reference to the other, so neither count reaches zero. Make the back-reference weak (weakref.ref(parent)) or break the link explicitly on teardown; then reference counting frees both.
2. A process’s memory stays at its peak after a large batch finishes, although tracemalloc shows the objects are gone. Is that a leak?
Probably not. pymalloc returns an arena only when it is entirely empty, and the C allocator may keep freed pages too. Check that traced memory is flat across repeated batches; if so, the fix is to run large batches in short-lived worker processes.
3. Senior scenario: an OrdersPortal pre-fork server shows each worker’s memory growing by hundreds of MB soon after start, although the code loads read-only data once in the parent. What is happening and what do you do?
Copy-on-write is being defeated: reference count updates and collector bookkeeping write to object headers, so pages shared with the parent get copied in each child. Load the data, call gc.disable() early in the parent and gc.freeze() right before forking, then gc.enable() in the children, which the gc documentation recommends for this case. Store bulk data in structures with few Python objects (arrays, bytes, memory-mapped files) so there are fewer headers to touch, and measure resident and shared memory per worker before and after.
Key takeaways
Section titled “Key takeaways”- Reference counting frees most objects when the last reference disappears; the
gcmodule handles cycles. - Immortal objects (3.12) and borrowed references (3.14) make
sys.getrefcountunreliable. - Python 3.14.5 reverted the incremental collector of 3.14.0 to 3.14.4.
- “Leaks” in Python are usually objects still referenced; find them with
tracemallocsnapshots. - Use
withfor resources, weak references for non-owning links, and bounded caches.
Related pages
Section titled “Related pages”- Weak references: refer to objects without keeping them alive.
- The GIL: why reference counting needs a lock on the default build.
- threading vs multiprocessing: the free-threaded build and process memory.
__slots__: smaller instances.- copy vs deepcopy: references versus copies.
- lru_cache: bounded caching.
Official references
Section titled “Official references”- gc: Garbage Collector interface (Python 3.14 docs)
- tracemalloc (Python 3.14 docs)
- sys.getrefcount and sys.getsizeof (Python 3.14 docs)
- Memory management, pymalloc and mimalloc (Python 3.14 C API docs)
- What’s New in Python 3.14: garbage collection
- Garbage collector design (CPython 3.14 InternalDocs)
- PEP 442: Safe object finalization, PEP 683: Immortal Objects, PEP 703: Making the GIL Optional