Skip to content
Tutorials Center
My learning

Topics

Lesson 95 of 149 ยท Beyond the Basics

Memory Management

See how Python manages memory. Learn how names reference objects, how reference counting and the garbage collector free them, and use weakref and getsizeof.

In languages like C, you ask the computer for memory and you must give it back yourself. Forget, and your program leaks; give it back twice, and it crashes. Python does this bookkeeping for you. You create objects freely, and Python frees them when nothing needs them any more.

You don't have to understand the machinery to write Python, but knowing the basics explains a lot of puzzling behavior: why changing one list "also" changes another, why a cache can keep huge objects alive, and why a long-running program slowly eats memory. In this lesson you'll learn how names refer to objects, how reference counting and the garbage collector reclaim memory, how weak references avoid keeping things alive, and how to measure what your objects cost.

Names are references, not boxes

A variable in Python is not a box that holds a value. It's a name tag attached to an object. The object lives somewhere in memory (the heap), and any number of names, list slots or attributes can point at it.

That's why assignment never copies anything:

Python Two names, one list

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

  • is checks whether two names refer to the same object; == checks whether two objects have equal values (see Membership and Identity Operators).
  • id() returns a number that identifies an object while it's alive. In CPython it's the memory address.
  • Passing an argument to a function hands over a reference, so a function can change a mutable object the caller still uses. Make a copy (list(x), x.copy(), copy.deepcopy(x)) when you need independent data.

Immutable objects like numbers, strings and tuples can't be changed in place, so sharing them is always safe. That's also why Python feels free to reuse them: small integers and many short strings are created once and shared. Never rely on that with is; compare values with ==.

Reference counting

How does Python know when an object is no longer needed? Every object carries a reference count: the number of references pointing at it. Each new name, list slot or attribute that points at the object adds one. Each one that goes away subtracts one. When the count reaches zero, nothing can reach the object any more, and Python frees its memory immediately.

sys.getrefcount() shows the count. The number includes one temporary reference created by the call itself, and the exact values vary between Python versions, so watch how the number changes rather than its exact value:

Python Watching a reference count

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Two things to notice:

  • del deletes a name, not an object. It removes one reference. The object disappears only when the last reference is gone.
  • None shows an enormous number. Since Python 3.12, objects that live for the whole program, such as None, True and small integers, are immortal: their count is pinned to a huge value and never changes.

References also disappear automatically: when a function returns, its local variables go away; when you rebind a name (x = something_else), the old object loses a reference; when a list is freed, every item it held loses one.

Cycles and the garbage collector

Reference counting has one blind spot. If two objects refer to each other, each keeps the other's count above zero, even when your program can't reach either of them. This is a reference cycle:

Python
a = Node("a")
b = Node("b")
a.partner = b      # a -> b
b.partner = a      # b -> a
del a, b           # both counts are still 1: each is held by the other

Cycles are common: a tree node that knows its parent, a doubly linked list, an object that stores a method of itself. To clean them up, CPython has a second mechanism, the cyclic garbage collector in the gc module. It runs from time to time, looks for groups of objects that only reference each other, and frees them.

The next example uses weakref.finalize() to print a message when an object is freed. Automatic collection is switched off for the demo so you can see exactly when each object goes:

Python Reference counting vs the cycle collector

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The plain object is freed the instant its last reference disappears. The cycle survives del and is freed only when the collector runs. (The count from gc.collect() includes some internal objects that belong to the nodes, so it can be larger than 2.)

Useful facts about gc:

  • It's on by default and runs automatically, triggered by how many objects have been created since the last run. You almost never need to call gc.collect() yourself.
  • It tracks objects in generations: new objects are checked often, and objects that survive several collections are checked less often, since long-lived objects tend to stay alive.
  • gc.disable() is occasionally used in short programs that create many objects and no cycles, to save the collector's time. Turn it back on, or you'll leak every cycle.

Be careful with __del__. A __del__ method runs when an object is about to be freed, but you can't control exactly when that is (especially for objects in cycles), and exceptions inside it are only printed as warnings. To release files, connections or locks, use a context manager (with), which closes them at a known moment. For a cleanup callback, weakref.finalize() is safer than __del__.

Weak references

Sometimes you want to refer to an object without keeping it alive. A cache of loaded images, a registry of open windows, or an observer list shouldn't stop objects from being freed when the rest of the program is done with them.

A weak reference points at an object without adding to its reference count. When the object is freed, the weak reference simply returns None. The weakref module provides:

  • weakref.ref(obj): call it to get the object back, or None if it's gone.
  • weakref.WeakValueDictionary: a dict whose values disappear when they're freed elsewhere.
  • weakref.WeakKeyDictionary and weakref.WeakSet: the same idea for keys and set items.
Python A cache that doesn't keep objects alive

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

While someone uses logo.png, every caller gets the same object. Once the last strong reference is deleted, the entry vanishes from the cache by itself. Not every object can be weakly referenced: built-in types such as int, str, tuple and plain list can't, but instances of your own classes can.

How big is an object?

sys.getsizeof(obj) returns the size of one object in bytes. It's shallow: for a container it counts the container's own structure, including its array of references, but not the objects those references point to.

For a fuller picture of a running program, tracemalloc traces every memory allocation Python makes. Its get_traced_memory() returns the current and peak memory used since tracing started:

Python getsizeof, __slots__ and tracemalloc

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A class with __slots__ declares its attributes up front, so instances skip the per-object attribute dictionary and take less memory. That matters when you create millions of small objects. The trade-off: you can't add new attributes at runtime. You'll see how slots work in Metaclasses, Descriptors and Object Internals.

Other ways to save memory you've already met: generators instead of big lists (see Measuring and Improving Performance), the array module for long runs of numbers (see Arrays with the array Module), and reading files line by line.

Why memory still leaks

Python frees unreachable objects, but it can't free objects your program can still reach, even if you'll never use them again. Most "memory leaks" in Python are really forgotten references:

  • Ever-growing containers: a module-level list or dict that you keep appending to, such as a log of every request.
  • Unbounded caches: @functools.cache or a hand-written dict cache that never forgets anything. Use lru_cache(maxsize=...) or a WeakValueDictionary.
  • Lingering callbacks and listeners: registering a bound method keeps its whole object alive until you unregister it.
  • Large objects kept by long-lived names: a huge DataFrame stored in a global, or held by an exception traceback you saved for later.

To hunt a leak, compare two tracemalloc snapshots taken some time apart (snapshot2.compare_to(snapshot1, "lineno")); the lines whose allocations keep growing are your suspects.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. After a = [1, 2] and b = a, you run b.append(3). What is a?

    Assignment never copies. a and b are two names for the same list, so the change is visible through both.
  2. 2. What does del name do?

    del removes a name (one reference). Reference counting frees the object once its count reaches zero.
  3. 3. Why does CPython need a garbage collector in addition to reference counting?

    The cyclic garbage collector finds groups of objects that only reference each other and frees them. Immortal objects are never freed.
  4. 4. Which tool lets a cache hold objects without keeping them alive?

    A WeakValueDictionary stores weak references, so entries disappear automatically when the objects are freed elsewhere.
  5. 5. What does sys.getsizeof(my_list) measure?

    getsizeof is shallow. To see the full cost of nested data, add up the items or use tracemalloc.

Summary

  • Variables are references to objects; assignment and argument passing share objects instead of copying them.
  • Every object has a reference count; when it reaches zero, CPython frees the object immediately. del removes one reference.
  • The cyclic garbage collector (gc) frees groups of objects that refer only to each other; it runs automatically.
  • Weak references (weakref.ref, WeakValueDictionary, finalize) let you track objects without keeping them alive.
  • sys.getsizeof() measures one object shallowly; tracemalloc measures real allocations; __slots__ shrinks many small objects.
  • Most Python "leaks" are references you forgot about: growing containers, unbounded caches and lingering callbacks.

Next: Networking: URLs, HTTP and Sockets, where your programs start talking to other computers.