I spent an afternoon hunting a memory leak in a long-running ETL worker that processed images in batches. Memory grew steadily by a few hundred megabytes per hour, yet heap profilers showed no single large allocation. The culprit turned out to be a tiny reference cycle buried inside a callback registry — a parent object holding a list of bound methods, each bound method holding a reference back to the parent. Nothing was technically "leaked" in the C sense, but Python's reference counting alone could never free it. That incident forced me to finally internalize how CPython really manages memory, and why understanding the interplay between reference counting, the cyclic garbage collector, and weak references matters long before you hit production issues.
When Every Object Is a PyObject With a Refcount Field
At the C level, CPython represents every Python object as a PyObject struct. The two fields that matter most for memory are ob_refcnt and ob_type. ob_refcnt is a simple integer counter tracking how many references point to the object. When you write a = [] and then b = a, you are not copying the list. You are incrementing that counter from 1 to 2. When a name goes out of scope, or you del b, the counter decrements. The moment it hits zero, CPython calls the type's deallocation function immediately, on the same thread, without waiting for any background collector.
This is deceptively simple but has profound implications. In languages with tracing collectors, object finalization is non-deterministic. In CPython, for acyclic object graphs — which is the vast majority of objects — destruction is deterministic and prompt. I've found that predictability invaluable when working with file handles, sockets, and database cursors. If you open a file and lose the last reference, the file descriptor is closed right away via the type's tp_dealloc, not "sometime later."
The Cost of Counting Every Reference
That determinism is not free. Every assignment, argument pass, and container insertion must atomically adjust a counter. In single-threaded code this is cheap, but in free-threaded builds of Python 3.13+ and in extensions that release the GIL, refcount manipulation becomes a genuine synchronization cost. This is one reason the core team has explored alternative strategies like immortal objects for None, True, False and small integers — their refcount is marked as immortal and never changes, avoiding contention on globally shared singletons.
In my experience, the most common misunderstanding is assuming sys.getrefcount() returns the "real" count you expect. It always returns at least one more than you anticipate because the act of passing the object to the function creates a temporary reference. I use it as a diagnostic, not as ground truth. The more useful tools are gc.get_referrers() and object traversal when debugging leaks, not raw refcount inspection.
Borrowed vs. Owned References in C Extensions
If you ever write a C extension or debug one, you will encounter the concept of borrowed references. Functions like PyList_GetItem() return a borrowed reference — they do not increment the counter, and you must not decref it. Functions like PyLong_FromLong() return a new owned reference. Mixing these up causes either leaks or use-after-free crashes that manifest as intermittent segfaults. The Python Documentation on object structures is essential reading here, because the rules are explicit and unforgiving at the C boundary.
How Reference Counting Reclaims Memory Instantly (and Where It Fails)
For straight-line code without cycles, reference counting is beautifully efficient. Consider a function that builds a large dictionary, processes it, and returns. When the function exits, all local names are cleared, the dictionary's refcount drops to zero, and it releases its keys and values. Those values in turn drop their refcounts, cascading deallocation without ever involving the garbage collector. This cascade is why CPython rarely needs a full heap scan under normal workloads — most objects die young and are reclaimed immediately.
The failure mode is equally predictable: reference cycles. If object A references B and B references A, even when no external name points to either, both retain a refcount of at least 1. No amount of scope exit will free them. Pure reference counting cannot detect that an isolated cycle is unreachable from the program roots.
This is not a theoretical edge case. In my experience, cycles appear in four common Python patterns: parent/child bidirectional links in ORMs and tree structures, observer or pub/sub registries where subjects hold listeners and listeners hold subjects, closures that capture the instance they belong to, and exception tracebacks where __traceback__ holds frames that hold locals that hold the exception. The last one has bitten many teams writing retry loops that store the last exception.
# Reference counting can't free this isolated cycle
import sys
class Node:
def __init__(self, name):
self.name = name
self.parent = None
self.children = []
def __del__(self):
print(f"deleting {self.name}")
a = Node("a")
b = Node("b")
a.children.append(b)
b.parent = a # cycle: a -> b -> a
print(sys.getrefcount(a)) # 3: a, b.parent, getrefcount arg
print(sys.getrefcount(b)) # 3: b, a.children[0], getrefcount arg
del a
del b
# At this point the Node objects are unreachable but not freed
# if __del__ is defined in older Python versions without gc handling.
# With modern GC they will be collected, but not by refcounting alone.
Why __del__ Makes Cycles Dangerous
Objects with a __del__ finalizer compound the problem. If such objects participate in a cycle, CPython cannot safely determine the order in which to run finalizers. Before Python 3.4, those objects were placed in gc.garbage and never freed at all. Since PEP 442, Python can break many of these cycles safely, but only if your __del__ does not resurrect the object. I've found that the safest advice for production code is still to avoid __del__ entirely and use context managers or weakref.finalize instead. If you must define cleanup logic, keep it simple and never create new references to the dying object.
The Generational Garbage Collector: Tracking Cyclic Garbage Behind the Scenes
To handle cycles, CPython runs a supplemental tracing collector built on top of reference counting. It does not track every object — only containers that could potentially form cycles: lists, dicts, sets, tuples containing mutable objects, instances with __dict__, and similar types. Strings, integers, and tuples of immutable primitives are left alone because they cannot create a cycle. You can verify this with gc.is_tracked(obj).
The collector is generational, based on the observation that most objects die young. Newly tracked objects start in generation 0. If they survive a collection, they are promoted to generation 1, and then to generation 2. Each generation has a threshold. From Python Documentation the defaults in CPython 3.12 are roughly (700, 10, 10) — meaning generation 0 is collected after 700 more allocations than deallocations, generation 1 after 10 collections of generation 0, and generation 2 after 10 collections of generation 1. This design means short-lived cycles are caught quickly, while long-lived tenured objects are scanned rarely.
What Happens During a Collection
When a generation is collected, the GC does a reachability trace from known roots — stack frames, modules, and other GC-tracked containers. It copies the reference count into a temporary field, subtracts internal container references, and identifies groups with non-zero counts that are only referenced internally. Those groups are unreachable cycles. They are then collected, and if they have finalizers, those are invoked in a safe order.
One practical detail that surprises many teams: the GC must temporarily pause your application. It is not concurrent. For most web requests this pause is microseconds, but I have measured pauses of 50-100ms in services that built enormous graphs of dataclass instances and held them in generation 2. When building latency-sensitive pipelines — for example, the kind of concurrent workloads described in Python Async/Await: Writing Concurrent Code That Actually Works — those pauses can show up as tail-latency spikes.
| Mechanism | What It Reclaims | When It Runs | Overhead |
|---|---|---|---|
| Reference Counting | All objects whose refcount drops to zero; acyclic graphs | Immediately on DECREF to zero | Per-reference increment/decrement |
| Generational GC | Unreachable cycles among container objects | Periodically when allocation thresholds are exceeded | Pause to trace tracked containers; scales with number of tracked objects |
| Weak References | Does not reclaim; prevents references from keeping objects alive | Callback/expunge on referent collection | Small indirection and callback dispatch |
Tracing Reference Cycles With gc.get_referrers() and gc.get_referents()
When you suspect a leak, the gc module is your first toolkit. In my experience, the fastest way to confirm a cycle leak is to force a collection and inspect what remains. I usually start a reproduction script with gc.set_debug(gc.DEBUG_SAVEALL) or simply gc.collect() and len(gc.garbage) in older code, then narrow down with referrer walking.
The two functions to internalize are gc.get_referents(obj) — what does this object point to — and gc.get_referrers(obj) — what points to this object. Together they let you traverse the object graph. For large services, I also rely on tracemalloc to attribute memory growth to source lines, and objgraph in development to render graphs of the worst offenders. When you structure projects with disciplined isolation — Python Virtual Environments: Why They Matter and How to Use Them covers that foundation well — installing diagnostic tools like objgraph or pympler in a dedicated debug venv keeps production dependencies clean while giving you the introspection you need.
import gc
import weakref
gc.enable()
gc.set_debug(0) # disable verbose debug in production
class CacheEntry:
def __init__(self, key, value, parent):
self.key = key
self.value = value
self.parent = parent # creates potential cycle if parent holds entry
# Simulate leak: parent dict holds entry, entry holds parent
parent = {}
entry = CacheEntry("user:123", {"name": "Ada"}, parent)
parent["entry"] = entry
# Break external names and force collection
import sys
del entry
del parent
collected = gc.collect()
print(f"collected {collected} objects")
# Find lingering CacheEntry instances
for obj in gc.get_objects():
if isinstance(obj, CacheEntry):
print("leaked:", obj.key)
print(" referrers:", gc.get_referrers(obj)[:3])
print(" referents:", gc.get_referents(obj))
Patterns That Create Silent Cycles
In production I watch for three specific patterns. First, bound methods as callbacks: self.bus.subscribe(self.on_event) often stores a bound method, which holds self. If the bus lives as long as the application, the instance never dies. Second, closures in long-lived containers: a list of lambdas capturing self has the same effect. Third, exception handling that retains tracebacks: except Exception as e: self.last_error = e keeps the entire frame chain alive, including all locals in that call stack. The fix for the last one is trivial and often overlooked: assign self.last_error = None or use e.__traceback__ = None after logging.
Weak References: Caching Without Preventing Collection
Weak references solve a specific problem: you want to associate data with an object without keeping that object alive. A normal dictionary cache[obj] = computed_value increments the referent's refcount, so as long as the cache holds the key, the object cannot be freed. A weak-key dictionary does not.
The weakref module provides the primitives: weakref.ref(obj, callback) returns a callable that yields the object if it still exists or None if collected, and optionally invokes a callback at collection time. weakref.WeakKeyDictionary and weakref.WeakValueDictionary are dictionary variants where keys or values are weak. weakref.WeakSet keeps a set of objects without owning them. Not all types support weak references — instances of user-defined classes do by default, but list, dict, and str do not unless subclassed. You can add __weakref__ to __slots__ if you use slots.
I've found weak references most valuable in three places: caches and memoization layers, observer registries, and per-instance metadata. For data-heavy applications where you are comparing Dataclasses vs Pydantic: When to Use Which in Python Projects, caching validated models with a WeakValueDictionary lets you avoid revalidation while allowing memory pressure to naturally evict unused models.
import weakref
import gc
class Session:
def __init__(self, sid):
self.sid = sid
def __repr__(self):
return f"Session({self.sid})"
# 1) WeakValueDictionary cache that does not prevent collection
cache = weakref.WeakValueDictionary()
def get_session(sid):
if sid in cache:
print("cache hit")
return cache[sid]
print("cache miss")
s = Session(sid)
cache[sid] = s
return s
s1 = get_session("abc")
s2 = get_session("abc") # hit, same object
print(s1 is s2) # True
# Drop strong refs, force collection, cache entry disappears
del s1, s2
gc.collect()
print("abc in cache?", "abc" in cache) # False
# 2) weakref.ref with callback for cleanup
def on_collected(wr):
print("Session was collected, cleaning up external resource")
s3 = Session("xyz")
r = weakref.ref(s3, on_collected)
print(r()) # Session(xyz)
del s3
gc.collect() # prints callback message
print(r()) # None
Limitations and Pitfalls of Weak References
Weak references are not a panacea. First, the callback is not a destructor — it fires after the object is already being finalized, so you must not resurrect the object inside it. Second, WeakKeyDictionary uses hashes of its keys; if your object's __hash__ depends on mutable state that changes after insertion, you will lose the entry. Third, weak references add a level of indirection that makes debugging slightly harder — cache[key] may suddenly raise KeyError after a collection where you expected it to persist. I treat weak caches as best-effort accelerators, not as authoritative stores, and always code a recomputation path.
Tuning gc Thresholds and Disabling Collection for Latency-Sensitive Workloads
The default thresholds are conservative and correct for general-purpose Python, but they are tunable for specific workloads. You can inspect them with gc.get_threshold() and change them with gc.set_threshold(new0, new1, new2). Increasing generation 0's threshold reduces collection frequency at the cost of allowing more cyclic garbage to accumulate before cleanup. Decreasing it makes collections more frequent but shorter.
In one data ingestion service, we processed millions of small dataclass instances per minute, most of which were acyclic and died by refcounting. The generational collector was scanning tens of thousands of tracked objects every few seconds for almost no benefit. Raising the thresholds to (5000, 20, 20) cut GC CPU time by 30% without measurable memory growth. Conversely, in a GUI application that created many short-lived widget cycles, lowering the threshold reduced peak memory.
When to Temporarily Disable GC
For latency-critical sections you can call gc.disable(), run a tight loop that allocates heavily but creates no cycles, then gc.enable() and gc.collect() explicitly during an idle window. Numerical code using NumPy or frameworks that allocate large arrays often does this — those arrays are not GC-tracked, so pausing the collector avoids scanning overhead entirely. If you adopt this pattern, be disciplined: re-enable collection in a finally block, and monitor memory in staging. I have seen services where GC was disabled during startup and never re-enabled due to an exception path, leading to unbounded growth over days.
A more modern alternative on Python 3.11+ is gc.freeze() after warm-up. It moves all currently tracked objects into a permanent generation that is never scanned again, which is ideal for copy-on-write forking servers like Gunicorn or Uvicorn workers. You warm up the app, freeze the long-lived graph, and future collections only examine objects created after forking. Combined with careful use of type hints and static analysis as described in Python Type Hints: A Practical Guide for Production Code, this gives you both safety and predictable latency without hand-rolling memory management.
Frequently Asked Questions
Do I need to worry about reference cycles if I never use __del__?
Yes, but less. Modern CPython (3.4+) can collect most cycles containing objects with __del__ via PEP 442, and cycles without finalizers have always been collectible. The risk is not permanent leaks but delayed reclamation and unpredictable finalization order. For most application code, prefer try/finally, context managers, and weakref.finalize over __del__, and treat cycles as a performance and determinism issue rather than a correctness catastrophe.
Why does my memory grow even though gc.collect() returns 0?
A return value of 0 means no cyclic garbage was found. Growth then comes from reachable objects you still hold, or from non-GC causes like fragmentation in the pymalloc arena, unreleased C-allocated memory in extensions, or increasing refcounts from caches and global registries. Use tracemalloc to find allocation hotspots, audit caches for unbounded growth, and check for global lists or dicts that accumulate entries without eviction.
Can I create a weak reference to any Python object?
No. Only objects that support the weak reference protocol can be weakly referenced. User-defined class instances support it by default. Built-in types like list, dict, tuple, str, and int do not, unless you subclass them. If you use __slots__, include '__weakref__' in the slots tuple to enable weak references. Attempting weakref.ref([]) raises TypeError.
Is disabling the garbage collector safe for performance optimization?
It can be, but only in narrow, measured cases. If your hot path allocates no cyclic garbage — for example, tight NumPy loops or parsing that uses only strings and tuples — disabling GC during that path removes pause time. Always re-enable it promptly in a finally block and do a manual gc.collect() at a safe point. Never disable GC globally in a long-running service without exhaustive testing, because any overlooked cycle will leak for the lifetime of the process.