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.

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
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.
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.
def add_item(item, bucket=None):
if bucket is None:
bucket = []
bucket.append(item)
return bucketEach 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:
def add_item(item: str, bucket: list[str] | None = None) -> list[str]:
if bucket is None:
bucket = []
bucket.append(item)
return bucketThe 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:
def register(name, registry={}):
registry[name] = True
return registryThis works, but it hides shared state inside the function signature. A module-level variable communicates the intent more clearly:
_registry = {}
def register(name):
_registry[name] = True
return _registryIf 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.
from dataclasses import dataclass, field
@dataclass
class Bucket:
items: list = [] # raises ValueError at class definition timeUse field(default_factory=list) instead:
@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.
import time
def now(timestamp=time.time()):
return timestampHere 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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.