When does CPython's cycle collector actually run, and what do the gc thresholds control?

**The trigger is allocation, not memory.** Nothing in CPython watches the process's memory footprint or runs the cycle collector on a timer. The interpreter keeps a counter for the youngest generation: every time a tracked container object is allocated it goes up, every time one is deallocated it goes down. When that surplus exceeds the first collection threshold, a collection of the young generation runs. That is the whole trigger. A process can hold gigabytes and never collect if it stops allocating containers, and a process that allocates and frees millions of small lists can collect constantly while its memory stays flat. **Generations.** Objects the collector has just started tracking sit in the youngest generation, which is scanned often. Anything that survives a pass is promoted to an older generation and examined much less frequently. The rationale is the standard weak-generational observation: most objects die young, so rescanning long-lived data on every pass is wasted work. On Python 3.14 the trigger values are visible directly: ```python import gc print(gc.get_threshold()) # (2000, 10, 0) on CPython 3.14 print(gc.get_count()) # live counters for the three generations ``` The first value is the allocation surplus that fires a young collection. The second counts young collections before the middle generation is included. On 3.14 the third value is `0` because the oldest objects are no longer collected in one stop-the-world sweep driven by a counter — CPython reworked the handling of long-lived objects to spread that work out and shorten pause times on large heaps. Read the tuple from the interpreter you actually run rather than memorising numbers, because these internals move between releases. **The controls.** - `gc.collect()` runs a full collection now and returns the number of unreachable objects found. `gc.collect(0)` restricts it to the youngest generation. - `gc.set_threshold(t0, t1, t2)` moves the trigger points. Raising `t0` means fewer, larger passes: less CPU spent collecting, more cyclic garbage resident between passes. - `gc.set_threshold(0)` disables automatic collection — the documented meaning of a zero first threshold — while leaving explicit `gc.collect()` calls working. - `gc.disable()` and `gc.enable()` toggle automatic collection outright, and `gc.isenabled()` reports the state. - `gc.get_stats()` returns one dictionary per generation with `collections`, `collected` and `uncollectable` counts. Sampling it over time is the honest way to see what the collector is costing you. - `gc.callbacks` is a list of callables invoked before and after each collection, which is how you export collection counts and durations to metrics without patching anything. **Reference counting is unaffected by all of this.** Every knob here concerns the tracing pass that finds cycles. Non-cyclic objects are still freed the moment their last reference goes away, whatever the thresholds say — which is why turning the collector off does not stop most memory from being reclaimed. **Where this shows up in real systems.** Two shapes recur. The first is an allocation-heavy loop that builds and discards many short-lived containers: the young counter crosses the threshold constantly, and profiling shows a visible slice of wall time inside collection even though almost nothing is ever cyclic. Raising the first threshold is the targeted fix, and `gc.callbacks` or `gc.get_stats()` is how you confirm the improvement rather than guessing. The second shape is the opposite: a service that allocates almost nothing after startup but holds a large object graph. It collects rarely, which is fine, but every pass it does run walks the whole promoted graph. Freezing the startup graph out of the collector's view is the standard answer there. **What tuning cannot do.** Thresholds change *when* cycles are collected; they never change *whether* something is garbage. If memory grows because a module-level cache keeps appending, the objects are reachable and no threshold, generation or forced collection will touch them. Reaching for `gc.set_threshold()` before establishing that the growth is actually cyclic is the most common wasted afternoon in this area.