Skip to content

Python memory management: refcounting and the GC

  • 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.getrefcount and sys.getsizeof mislead, and why freed memory does not always go back to the operating system.
  • How to find a real leak with tracemalloc and fix it.

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.

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 argument
batch = [inv] # a list now refers to it too
print("refcount:", sys.getrefcount(inv))
print("del inv")
del inv # the list still holds it
print("batch.clear()")
batch.clear() # last reference gone: freed right here
print("after clear")
print("None is immortal:", sys._is_immortal(None))

Output:

refcount: 2
refcount: 3
del inv
batch.clear()
freed INV-1001
after clear
None is immortal: True

del 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.

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.

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 demo
order = Order("ORD-2001")
order.lines.append(OrderLine(order, "MUG-01"))
print("del order")
del order # refcounts never reach zero: a cycle
print("still alive until the collector runs")
print("gc.collect() found", gc.collect(), "unreachable objects")
gc.enable()

Output (default build):

thresholds: (2000, 10, 10)
del order
still alive until the collector runs
freed ORD-2001
gc.collect() found 3 unreachable objects

The 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 (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.

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"] * 1000
print("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 bytes
list + its strings: 24197 bytes
empty dict: 64 empty list: 56

The list holds 3,000 pointers to only three distinct string objects, which is why adding them changes so little.

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 gc
import 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-up
gc.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 blocks
line 13: +239 KiB in +5000 blocks
traced now: 6.2 MB, peak: 6.2 MB

Line 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 gc
import tracemalloc
from functools import lru_cache
@lru_cache(maxsize=1_000) # the fix: a bounded cache
def 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.

  • Thinking del frees 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. Use with and 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.getsizeof alone. It is shallow; use tracemalloc or a deep-size tool.
  • Expecting resident memory to drop after freeing. Fragmented arenas stay mapped; recycle worker processes if peak usage is the problem.

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
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.

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.

  • Reference counting frees most objects when the last reference disappears; the gc module handles cycles.
  • Immortal objects (3.12) and borrowed references (3.14) make sys.getrefcount unreliable.
  • 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 tracemalloc snapshots.
  • Use with for resources, weak references for non-owning links, and bounded caches.