How Does Memory Management Work in Python?

CPython manages memory mainly with reference counting. Every object carries a counter that records how many references point at it. When you bind a name to an object, that counter goes up by one. When the name goes away, the counter goes down by one. The moment the counter reaches zero, the memory of the object is released right away and in a predictable way, with no waiting for a collection pass.

A weak reference lets you watch that happen without keeping the object alive yourself.

import weakref


class Node:
    def __init__(self, name):
        self.name = name


node = Node('payload')
ref = weakref.ref(node)
print('alive:', ref() is not None)
print('name:', ref().name)

del node          # the last strong reference is gone
print('collected:', ref() is None)

The output is alive: True, then name: payload, and then collected: True. The object was freed the moment its reference count reached zero, so ref() now gives back nothing at all.

Weak references are used in real code for caches, for lists of observers, and for links between a parent and a child, where a strong reference would keep an object alive for ever. The standard library uses them as well. weakref.WeakValueDictionary is a dictionary that lets its values disappear, and weakref.finalize runs a cleanup action when an object is collected.

The important limitation is that a weak reference only works for types that support it. You cannot make a weak reference to an int or to a str, because those do not have an identity that you could meaningfully watch. You cannot weak-reference a tuple or a list either.

The gc module lets you look inside CPython's collector for cycles and lets you control when it runs. The objects it watches are the container types, which are lists, dictionaries, sets, tuples, classes, and class instances. Those are the ones that can form a cycle of references.

import gc

print('tracked objects:', len(gc.get_objects()))
print('collector enabled:', gc.isenabled())
print('generation thresholds:', gc.get_threshold())

gc.disable()
print('after disable:', gc.isenabled())

gc.enable()
print('after enable:', gc.isenabled())

# Run a collection pass whenever you want one.
gc.collect()
print('collected:', gc.collect())

The exact number of tracked objects depends on what you have imported, so treat it as a relative figure and not as a fixed number. The rest of the output is stable. The collector starts enabled. get_threshold() returns the default thresholds of 700, 10, and 10 for the three generations. Disabling and enabling it flips the flag. And gc.collect() returns the number of unreachable objects that it reclaimed, which is normally zero in a small script.

Three ideas are worth taking away. The collector works in generations, and there are three of them. Objects that survive a collection are moved up a generation, so long-lived objects are examined much less often. gc.freeze() moves everything that is currently tracked into a permanent generation, which is a useful trick for cutting the startup cost of a service that forks worker processes. And gc.disable() is a legitimate speed-up for a short batch job, where you leave the process yourself and you do not care about cycles being cleaned up.

A reference cycle exists when two or more objects point at each other, either directly or through a chain of other objects. A list that contains itself is the simplest example. Another very common one is a parent object that holds a child, and the child that holds a reference back to the parent, which happens all the time in object graphs built from links that go in both directions.

Reference counting on its own cannot clean these up. Each object still has at least one incoming reference from the other object in the cycle, so the counter never reaches zero, even though nothing outside the cycle can reach the group any more. The memory would stay used for the whole life of the process.

That is what the collector for cycles is for. It walks through the objects it watches and looks for groups that cannot be reached from any root, and the roots are the module globals, the current stack frames, and the state of each thread. Anything that cannot be reached is treated as rubbish and is freed, along with the reference counts that it holds.

The design with generations exists because checking every object on every single allocation would be far too slow. Objects that survive a collection are moved into an older generation, and they are looked at much less often, so the common case stays cheap.

Two practical notes finish the answer. An object that holds a reference to something outside the program can define __del__, and in some cases Python will not collect a cycle that contains such an object. The classic problem is a class whose __del__ closes a file that the cycle also refers to. And since Python 3.4 the collector was rewritten to cut down its overhead, which is why the advice today is not to switch it off without a reason.