Python Mutable Default Arguments Explained: Why Defaults Are Evaluated Once

By the end of this page, you will understand why Python evaluates default arguments once when a function is defined, why mutable defaults like lists and dictionaries can be unexpectedly shared across calls, and how to write safe functions using None or other sentinel values.

In Python, default argument values are evaluated exactly once, at the moment the def statement runs. They are then stored inside the function object and reused on later calls.

That means this function:

def foo(a=[]):
    a.append(5)
    return a

creates one list object when Python defines foo. Every call to foo() without an explicit argument uses that same list.

This is not specific to lists. It applies to all default values, but it becomes surprising when the default is mutable:

• list
• dict
• set
• most custom objects

If the default value is immutable, such as None, 0, False, or a string, the effect is usually harmless because immutable objects cannot be changed in place.

Why Python does this

Python treats the def statement as executable code. When Python reaches a function definition:

Think of a Python function definition like packing a toolbox once.

When Python reads this:

def foo(a=[]):
    ...

it puts one specific list into the toolbox for foo. Later, every time you call foo() without giving a, Python pulls out that same list from the toolbox.

It does not build a new list each time.

So this is not:

• "use [] as instructions to make a new list later"

It is:

• "store this already-created list as the default"

A good analogy:

• Definition time = writing and packing the function
• Call time = using the packed function
• Mutable default = reusing the same notebook every time instead of handing out a fresh blank page

If you write in that notebook during one call, the next call sees the previous notes.

The unsafe pattern looks like this:

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

Example:

print(add_item("a"))
print(add_item("b"))

Output:

['a']
['a', 'b']

The second call reuses the same list.

Safe pattern: use None

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

Now each call without items gets a fresh list:

print(add_item("a"))
print(add_item())

Trace this example:

def foo(a=[]):
    a.append(5)
    return a

print(foo())
print(foo())

Step 1: Python reads the def

def foo(a=[]):

At this moment:

• Python creates a new empty list []
• Python creates the function object foo
• Python stores that list as the default value for parameter a

Step 2: First call

foo()

Because no argument is passed:

• Python uses the stored default list
• a refers to that list
• a.append(5) changes the list from [] to [5]
• function returns

Mutable default arguments usually appear as a bug, but understanding them helps in real code.

1. Building request payloads

def add_tag(tag, tags=None):
    if tags is None:
        tags = []
    tags.append(tag)
    return tags

Used when assembling API request data without leaking tags between requests.

2. Collecting validation errors

def validate_user(user, errors=None):
    if errors is None:
        errors = []
    if not user.get("name"):
        errors.append("name is required")
    return errors

If errors=[] were used directly, one user's errors could carry into another validation run.

3. Recursive tree traversal

Beginners often write recursive functions with a list default.

def walk(node, results=):
     results  :
        results = []
    results.append(node[])
     child  node.get(, []):
        walk(child, results)
     results

In real projects, developers almost always avoid mutable defaults in public functions.

Common safe pattern

def process(items=None):
    if items is None:
        items = []
    # work with items

This is widely used in:

• web backends
• CLI tools
• data processing scripts
• libraries

Guard clause style

def save_records(records=None):
    if records is None:
        records = []
    if not records:
        return 0
    return len(records)

Developers often combine None defaults with early returns.

Validation pattern

def create_user(data=None):
     data  :
        data = {}
        data:
         ValueError()
     data

Mistake 1: Using a list or dict as a default

Broken code:

def add_name(name, names=[]):
    names.append(name)
    return names

Problem:

• values accumulate across calls

Fix:

def add_name(name, names=None):
    if names is None:
        names = []
    names.append(name)
    return names

Mistake 2: Checking with if not items instead of if items is None

Broken code:

def add_item(item, items=None):
    if not items:
        items = []
    items.append(item)
    return items

Problem:

• if the caller passes an empty list [], it is treated the same as None

Rule

Default argument expressions in Python are evaluated once, when the function is defined.

Risky pattern

def func(items=[]):
    items.append(1)
    return items

Safe pattern

def func(items=None):
    if items is None:
        items = []
    items.append(1)
    return items

Use is None, not if not items

if items is None:
    items = []

Affects all mutable objects

• list
• dict
• set
• custom mutable instances

Usually safe defaults

Why does Python evaluate default arguments only once?

Because the default value is part of the function object created when the def statement runs.

Are mutable default arguments always bad?

Not always, but they are usually confusing and error-prone. Most code should avoid them.

Why is None the recommended default?

None is immutable and commonly used as a sentinel meaning "no value was provided." That lets you safely create a new list or dict inside the function.

Does this behavior apply to dictionaries too?

Yes. Any mutable object used as a default can be shared across calls.

Is this behavior a bug in Python?

No. It is intentional and consistent with how function definitions are executed.

Can this behavior ever be useful?

Yes, for intentionally preserving state across calls, but clearer alternatives usually exist.

How can I inspect a function's defaults?

You can look at function.__defaults__.

def foo(a=[]):
    pass

print(foo.__defaults__)

Do lambda functions behave the same way?

Yes. Default arguments in lambdas follow the same rule because they are functions too.

• None as a sentinel value — commonly used to create safe defaults inside a function.
• Mutable vs immutable objects — explains why lists and dicts behave differently from strings and tuples.
• Function objects in Python — helps explain that defaults are stored on the function itself.
• Variable scope — useful for understanding where names are resolved and stored.
• Closures — another way functions can retain state between calls.
• Classes and instance attributes — a clearer way to store persistent state.
• Recursion in Python — recursive functions often need careful handling of accumulator lists.
• Argument passing in Python — helps explain what happens when mutable objects are passed explicitly.