Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Fixing the Python Mutable Default Argument Trap

Python evaluates mutable default arguments once, so a shared list or dict can leak state across calls. Learn the None-sentinel pattern and dataclass default_factory fix.

~4 min readPython
#python#mutable-default-arguments#function-signatures#python-dataclasses
A Python function definition showing a mutable list default shared across multiple calls, illustrating the shared-state trap.

Python evaluates default argument expressions once, at function definition time. For a mutable default such as a list or dict, that means the same object is reused on every call that omits the argument. The examples below show why that happens, why it causes surprising state leaks, and how to fix it.

The Surprising Behavior of Mutable Defaults

python
def add_item(item, bucket=[]): bucket.append(item) return bucket print(add_item("first")) # ['first'] print(add_item("second")) # ['first', 'second']

The second call returns a list that already contains "first" even though no bucket argument was passed. The default list was created once, when the function was defined, and the same object is reused for every call that omits the argument. This is the classic Python mutable default argument problem: state silently leaks from one call to the next.

The same behavior appears with dicts, sets, bytearrays, and any custom mutable object used as a default.

Why Python Evaluates Defaults Once at Definition Time

When the def statement executes, Python evaluates each default expression exactly once and stores the resulting objects in the function's __defaults__ tuple. For a module-level function, that happens when the module is imported, not when the function is called.

python
def build(bucket=[]): return bucket print(build.__defaults__)

For a call that omits bucket, the list stored in __defaults__ is the same object used inside the function. Because lists are mutable, an in-place operation such as append persists across calls. The default is not re-evaluated per call, so each omitted argument reuses the same object.

This is not a language bug. It is a direct consequence of evaluating defaults once at definition time, and the behavior is fully predictable once the rule is understood.

The Standard Fix: None as a Sentinel

The conventional fix is to use None as the default and create a fresh mutable inside the function body.

python
def add_item(item, bucket=None): if bucket is None: bucket = [] bucket.append(item) return bucket

Each call that omits bucket gets a brand-new list. Calls that pass a list explicitly still use that list, so the function keeps its flexibility.

The None check is cheap and idiomatic. It composes cleanly with type hints:

python
def add_item(item: str, bucket: list[str] | None = None) -> list[str]: if bucket is None: bucket = [] bucket.append(item) return bucket

The same pattern applies to dicts, sets, and any other mutable default.

When the Shared Default Is Actually Useful

There are rare cases where sharing a mutable default is intentional. A registry or cache that should persist across all calls is one example:

python
def register(name, registry={}): registry[name] = True return registry

This works, but it hides shared state inside the function signature. A module-level variable communicates the intent more clearly:

python
_registry = {} def register(name): _registry[name] = True return _registry

If shared state is genuinely required, make it explicit. Relying on the mutable default as a hidden singleton confuses readers, complicates testing, and makes the state hard to reset between test cases.

Dataclasses and Default Factory

The same problem appears with dataclasses, but the dataclass machinery rejects a mutable default at class definition time.

python
from dataclasses import dataclass, field @dataclass class Bucket: items: list = [] # raises ValueError at class definition time

Use field(default_factory=list) instead:

python
@dataclass class Bucket: items: list = field(default_factory=list)

default_factory is invoked once per instance, so each Bucket gets its own list. This is the same principle as the None sentinel, but enforced by the dataclass API rather than by convention.

Runtime and Import-Time Implications

Because defaults are evaluated at definition time, the default expression for a module-level function runs during module import. That matters when the expression has side effects or depends on runtime state.

python
import time def now(timestamp=time.time()): return timestamp

Here time.time() runs once at import, not at each call. Every call returns the same timestamp. To get the current time per call, compute it inside the body.

The same rule applies to keyword-only defaults, which are stored in __kwdefaults__. The fix is identical regardless of how the parameter is declared.

Debugging and Maintainability Concerns

The mutable default argument is a common source of subtle bugs in production code. The symptom is often intermittent: a function returns data that includes entries from an earlier request, and the cause is not obvious from reading the call site.

When reviewing code, a mutable default is a strong signal that object lifetime may not have been considered. The fix is small, but the failure mode is confusing because the bug only appears when the argument is omitted.

Testing is also affected. If a function with a mutable default is called across multiple test cases without passing the argument, state leaks between tests. The None sentinel pattern keeps each test isolated, and the default_factory pattern does the same for dataclass instances.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.