Python’s Garbage Collector: Refcounting, Cycle Detection, and the 3.14 Detour

Run this in any CPython session: x = [1, 2, 3]; del x. The list is gone — not eventually gone, the memory is reclaimed on the very line that executed del. Now run a = []; a.append(a); del a and the story changes: the list survives its deletion, possibly for thousands of allocations to come, until a completely different subsystem walks through memory and decides it is trash.

That asymmetry confuses a lot of people, and it matters in production. CPython does not have one garbage collector — it has two, layered on top of each other, with different triggers and different failure modes. The primary one is reference counting, and it does the vast majority of the work. The second exists only because refcounting cannot count its way out of a cycle. We’ll walk through both layers, look at how Python 3.14 briefly replaced the second layer and then rolled it back, and cover the knobs that matter when your service’s RSS graph starts climbing.

Layer One: Reference Counting Does the Real Work

Every Python object carries a reference count in its header. Assign the object somewhere, the count goes up; a reference goes away — a variable is deleted, a frame pops, a container element is overwritten — the count goes down. At zero, the object is destroyed immediately, synchronously, on the thread that dropped the last reference. There is no collector to wait for, which is why Python’s memory behavior feels “eager” compared to JVM or Go.

Refcounting has one famous consequence: destructors (__del__) run deterministically the moment the last reference disappears, so cleanup code that depends on them works in CPython and behaves differently on interpreters with other collection strategies — determinism is a property of refcounting, not of Python-the-language.

import sys

x = [1, 2, 3]
print(sys.getrefcount(x))  # 2: x itself plus the temporary argument reference

y = x                      # +1
x = None                   # -1, count back to 1 (y still holds it)
y = None                   # -1 -> 0: the list is freed right here

Refcounting has two structural costs. Every assignment, every function call, every loop iteration touches a reference count — a cache line that might be contended. And it cannot free anything whose count never reaches zero, which cyclic structures guarantee never happens.

Why Cycles Break Reference Counting

class Node:
    def __init__(self):
        self.parent = None

a = Node()
b = Node()
a.parent = b
b.parent = a        # cycle formed

del a, b            # both refcounts drop to 1, not 0.
                    # Neither object is ever reclaimed by refcounting.

Each node holds one reference to the other. Delete your own references and both objects still have an internal count of one — held by an object that only exists because the other one does. Their counts never reach zero on their own. This is not rare: every double-linked list, every tree with back-pointers, every exception object with a __traceback__ pointing back into stack frames produces cycles routinely. A long-running Python service allocates cyclic garbage constantly.

That’s what layer two is for.

Layer Two: The Generational Cycle Collector

The cyclic garbage collector is a tracing collector that runs alongside refcounting. It only tracks container objects — things that can hold references to other objects: lists, dicts, tuples, class instances, functions with closures. Plain ints and strings are exempt; they can’t form cycles, so the collector never sees them. “How many container objects exist” is the quantity that drives GC scheduling.

The algorithm is clever. Instead of computing reachability from roots — expensive, and it would need to know all the roots — the collector does a bounded local analysis: for every tracked object in a generation, it temporarily subtracts the references that come from within that same generation. Whatever remains with an effective count of zero is unreachable from outside the set and can be torn down. It’s a full reachability computation scoped to one generation, which is why it’s fast when that generation is small and slow when it’s big.

Objects are divided into three generations. New containers land in generation 0; when gen 0 is collected, survivors get promoted to generation 1, and gen 1 survivors to generation 2 — the usual bet that most objects die young, so collecting the young set frequently and the old set rarely keeps amortized cost low. The default thresholds are (700, 10, 10):

import gc
print(gc.get_threshold())   # (700, 10, 10)
print(gc.get_count())       # current allocation counters per generation

Read that as: run a gen 0 collection every 700 net new container objects (allocations minus deallocations); after 10 gen 0 runs, run gen 1; after 10 gen 1 runs, run gen 2 — the full pass that visits every tracked object in the process. A full collection pauses allocation work while it walks every container you have: milliseconds at best, much worse if you have millions of live containers.

The 3.14 Detour: Incremental GC, Shipped and Reverted

Python 3.14.0 replaced this collector with an incremental one — two generations instead of three, doing a fraction of a full pass each time it runs, so worst-case pauses shrink. The pause numbers were genuinely better. Then came the production reports.

Tim Peters traced a minimal workload — a bounded deque churning out self-referential objects — and found that under the incremental design, dead cycles piled up far faster than they were reclaimed: at steady state a backlog of roughly 90,000 unreachable objects sat uncollected, collections sometimes spaced tens of thousands of iterations apart, and RSS peaked several times higher than the generational collector produces on identical work. Real services reported the same shape: memory pressure that vanished the moment gc.collect() was called manually. In May 2026, Python 3.14.5 did something patch releases almost never do: it pulled the incremental collector and restored the 3.13 generational collector, citing production memory pressure. The incremental design is expected to return in 3.16 after a proper design review.

The practitioner takeaways are concrete. If you run 3.14.0 through 3.14.4, upgrade — the RSS growth under cyclic workloads is real. gc.get_threshold() returns (2000, 10, 0) on the incremental builds and (700, 10, 10) on the restored ones, which makes it a quick diagnostic for which collector you have. And code that tuned gc.set_threshold() for the incremental scheme should be revisited, because the third threshold is meaningful again.

The Free-Threaded Build Is a Different Machine

The free-threaded runtime (PEP 703, official as of 3.14) uses deferred reference counting — thread-local counts that only reconcile at safepoints — and immortalizes never-freed singletons like None and small ints (PEP 683) so their counts are never touched at all. The cyclic GC in this build is a separate, stop-the-world implementation that pauses all threads for its passes. Same observable gc module, very different machinery underneath.

Practical Knobs Worth Knowing

Most services never need to touch the GC. The situations where you will, briefly:

  • Memory grows and never comes back. The most common cause is not a leak in the collector — it’s objects that are technically reachable: module-level caches, loggers holding exception tracebacks, registries that grow. gc.get_objects() plus a histogram by type finds the hoarders.
  • Cyclic trash accumulates between full collections. The generational schedule means dead cycles can linger. If your workload allocates large cyclic structures at high rate, break the cycle explicitly (node.parent = None before dropping, or weakref for the back-pointer) or call gc.collect() on a schedule sized to your allocation rate.
  • You fork worker processes. Call gc.freeze() before fork(): it moves all current tracked objects out of the collection sets so the child’s first collections don’t walk (and copy-on-write-touch) pages inherited from the parent. Standard in preloaded web servers and Celery-style workers.
  • Latency spikes correlate with allocation bursts. gc.callbacks lets you timestamp collection starts and finishes and export pause durations as a metric — the honest way to confirm or refute “the GC did it.” And retire gc.disable() as a performance fix: it removes pause spikes, but on any service that allocates cyclic garbage it converts them into unbounded memory growth.
  • __del__ interacts badly with cycles. Objects with finalizers inside a cycle complicate reclamation; since 3.4 the collector calls finalizers in a safe order, but resurrection during finalization is still possible and gc.garbage is where truly uncollectable objects land.
import gc, time, collections

pauses = []
def on_gc(phase, info):
    if phase == "start":
        on_gc.t0 = time.perf_counter()
    else:
        pauses.append(time.perf_counter() - on_gc.t0)

gc.callbacks.append(on_gc)
# ... run your workload ...
print(max(pauses), "s longest GC pause")

Wrapping Up

CPython’s memory story is refcounting first, cycle collection second. The collector you’ll meet in current releases is generational with three generations and (700, 10, 10) defaults; the incremental redesign that briefly shipped in 3.14 was rolled back in 3.14.5 because trading pause time for resident memory was the wrong trade for most workloads. Understand which layer owns a given object’s lifetime, keep an eye on generation counts when RSS climbs, and use weakref, gc.freeze(), and measured gc.collect() calls where the workload demands them. The gc module documentation and the CPython internals guide to the garbage collector are the right next stops.

Leave a Reply

Your email address will not be published. Required fields are marked *