Python Garbage Collection

What garbage collection means in CPython

Garbage collection answers one question: can the running program still reach this object? If yes, it stays alive; if no, the runtime can reclaim it.

CPython uses two mechanisms together. Reference counting is the fast path — most objects vanish the instant their last reference disappears. The cyclic collector is the backup — it finds groups of objects that point at each other but are no longer reachable from the program.

Follow the same objects from an extra reference to an unreachable cycle, then replace a strong back-reference with a weak one. The explorer replays a CPython 3.10.12 capture: reference counts subtract measurement overhead, collection results come from gc.collect(), and the object graphs and final zero/freed transitions illustrate the mechanism.

data = [10, 20, 30]

a = Node('A')
b = Node('B')

# A <-> B, no external refs

parent = Node('parent')
child = Node('child')

Reference counting

Every object carries a count of the references pointing at it. Bind a new name, pass it into a list, store it on an attribute — the count ticks up. Drop a name with del or rebinding, and it ticks down. When the count hits zero, CPython frees the object on the spot, no collector involved. This handles the overwhelming majority of objects, and it is why CPython memory use is so predictable.

The count lives in the object header (ob_refcnt), and the interpreter adjusts it with the Py_INCREF / Py_DECREF macros — among the most frequently executed operations in all of CPython:

#define Py_INCREF(op)  ((op)->ob_refcnt++)
#define Py_DECREF(op)  do { if (--(op)->ob_refcnt == 0) _Py_Dealloc(op); } while (0)

Because every assignment touches a counter, those updates must be atomic — which is one of the reasons the GIL exists: a single global lock is cheaper than making every refcount operation thread-safe on its own. The cost of all this bookkeeping is real overhead in tight loops, and it has one blind spot.

The cycle problem

Reference counting cannot reclaim a reference cycle. If a.link = b and b.link = a, each object still has a reference — from the other — even after every external name is gone. The counts never reach zero, so the objects leak. Self-referential data structures (doubly linked lists, parent/child trees, objects holding a callback that closes over them) all create this shape.

The generational cyclic collector

For exactly these cases, CPython runs a second collector over the container objects it tracks. The captured Python 3.10 runtime uses three generations; thresholds and collector details depend on the Python version and build, so inspect the runtime you deploy.

• New objects start in generation 0, which is scanned most often. Survivors are promoted to generation 1, then generation 2 — the older a cycle gets, the less often it is checked.
• This capture has thresholds gc.get_threshold() → (700, 10, 10). Net allocations trigger young-generation collections; older generations are visited less often.
• Detection uses trial deletion: subtract references that live inside the candidate set, then trace from objects with outside references to identify what remains reachable. The remaining unreachable group can be reclaimed.

The gc module

import gc

gc.collect()           # force a full collection; returns objects reclaimed
gc.get_threshold()     # (700, 10, 10) by default
gc.get_count()         # per-generation allocations since the last collection
gc.disable()           # turn the cyclic collector off (refcounting stays on)
gc.freeze()            # move surviving objects out of GC's view (e.g. post-import)

Disabling the cyclic collector is a legitimate latency tactic for short-lived, cycle-free workloads — refcounting still reclaims everything acyclic. gc.freeze() after startup keeps long-lived objects from being rescanned forever.

Inspecting the collector

gc.get_stats() returns per-generation totals — collections run, objects collected, and uncollectable objects. After a workload that churned through cyclic garbage, a real run looked like:

>>> gc.get_stats()
[{'collections': 41, 'collected': 17160, 'uncollectable': 0},   # gen 0
 {'collections': 2,  'collected': 800,   'uncollectable': 0},   # gen 1
 {'collections': 1,  'collected': 0,     'uncollectable': 0}]    # gen 2

Generation 0 ran 41 times and reclaimed the bulk; the older generations ran rarely and collected little — exactly the generational payoff. A climbing uncollectable count is your signal to hunt down finalizer cycles.

Weak references

A weakref lets you reference an object without raising its refcount, so it does not keep the object alive — the clean way to observe or cache without creating a cycle:

import weakref

cache = weakref.WeakValueDictionary()   # entries vanish when values die
cache['key'] = obj                      # no strong reference held

parent.child = child
child.parent = weakref.ref(parent)      # break the would-be cycle

Pitfalls

• Mutable default arguments persist. def f(items=[]) binds one list at definition time; it lives as long as the function does and accumulates across calls. Use None and create inside.

Related concepts