Why Is the Mutable Default Argument a Trap?

Default argument values are worked out once, when the def statement runs, and not on each call. That means a mutable default is created a single time and then reused by every call that leaves the argument out, so any change to it is visible to the next caller.

def add_item(item, bucket=[]):
    bucket.append(item)
    return bucket


print(add_item('a'))    # ['a']
print(add_item('b'))    # ['a', 'b']  <- the old state is carried over
print(add_item('c'))    # ['a', 'b', 'c']


def add_item_fixed(item, bucket=None):
    if bucket is None:
        bucket = []          # a fresh list on every call
    bucket.append(item)
    return bucket


print(add_item_fixed('a'))   # ['a']
print(add_item_fixed('b'))   # ['b']

The first three calls share one list, so the output grows every time. The fixed version creates a new list on each call, so every result contains only its own item.

The fix has one subtlety. The check must be written as if bucket is None and not as if not bucket. If the caller passes an empty list on purpose, a test for "not bucket" would throw that list away and replace it with a new one, which is a different bug in the opposite direction.

The reason the default is only worked out once is that the def statement itself runs only once, when the function is defined. The default expression is evaluated at that moment, and the resulting object is stored in the definition of the function and then handed to every call that does not supply the argument. That is exactly why immutable defaults such as 0, an empty string, or a tuple are safe, and why only mutable defaults are dangerous.

The class-attribute version of the bug is the mirror image of the default-argument version. An attribute that is set in the class body belongs to the class itself, so every instance that does not replace it shares the same object.

class Registry:
    items = []               # one list, shared by every instance

    def add(self, value):
        self.items.append(value)
        return self.items


first = Registry()
second = Registry()
first.add('x')
print(second.items)          # ['x']  <- shared with first


# The same idea with a default argument, showing it is evaluated only once.
def counter(size=[]):
    size.append(1)
    return len(size)


print(counter())   # 1
print(counter())   # 2  <- the same default list, growing

Creating a second Registry does not give it a fresh list, because items was assigned once in the class body. The fix has the same shape as before. Set the attribute in __init__ instead, so that every instance gets its own list with a line like self.items = [] inside the constructor, or use a classmethod that builds a fresh one for you.

The counter function makes the evaluation-once point in a very direct way. The default list is created when the def statement runs, and every call appends to that one list, so the returned length grows from 1 to 2 to 3. If the default were worked out again on each call, then every result would be 1.

One more trap in the same family is worth naming. A default argument does not have to be mutable to be a problem, because it can still be a shared object that was created at definition time, such as an open file handle or a database connection. The rule generalises neatly. Never use a mutable object, or an object that holds a resource, as a default argument value.

The danger comes from the fact that the default is evaluated exactly once, when the function is defined, and the resulting object is then reused by every call that leaves the argument out. If that object is mutable, then every call changes the same shared state, and the result of one call leaks into the next one.

The bug is nasty in practice because it is invisible in a unit test that calls the function once, and it only shows up when the same function is used more than once. It also behaves differently depending on how the function is called. Passing an explicit argument gives correct and isolated behaviour, while leaving the argument out gives shared behaviour. That inconsistency is what makes it hard to diagnose.

The standard fix is to default the parameter to None and create the container inside the body of the function. The None sentinel is safe because None is immutable and cannot be changed by accident, and the check inside the function guarantees a fresh object for every call that did not supply one.

Two refinements are worth knowing. First, use if bucket is None rather than if not bucket, because an explicitly passed empty list is a legitimate value that should not be replaced. Second, the same trap applies to keyword-only parameters, and the fix there is identical.

There is a related mistake to avoid, which is defaulting to a tuple and then converting it inside the function. That works, but a tuple default for something the caller expects to be able to append to is a sign that the parameter should really be None. And for the rare function that wants to share state on purpose, the honest approach is to make the shared object explicit in the body instead of hiding it inside a default.