How should Python developers avoid bugs caused by mutable default arguments in function parameters?

Why Mutable Default Arguments Persist Across Calls

Python evaluates default parameter values once, when the function is defined, not each time it is called. If that default is a list, dictionary, or another mutable object, later calls reuse the same object. That is why state appears to “leak” between calls, even though the function signature looks harmless.

The key failure mode is hidden shared state. A function that appends to a default list or writes into a default dictionary is mutating an object that survives beyond a single invocation. That makes behavior depend on call history, which is especially confusing during debugging, refactoring, and unit testing.

A fresh object should be created inside the function when no argument is provided. In practice, that means using a sentinel such as None in the signature, then assigning a new list or dict at runtime. This keeps the default value stable while ensuring each call gets its own working data.

Safer Patterns for Function Defaults

The safest pattern is to treat the parameter default as a signal, not as storage. If the caller passes a value, use it; if not, build a new container inside the function. That approach avoids accidental reuse and keeps the function’s behavior tied to the current call rather than earlier ones.

It also helps to choose immutable defaults whenever a real default value exists. Numbers, strings, tuples, and None are straightforward because they cannot be mutated in place. If you need a mutable result, construct it during execution instead of at definition time.

For more implementation guidance on designing predictable Python code and avoiding common security-adjacent mistakes in handling state, the OWASP Cheat Sheet Series is a useful reference point.

When the function is part of a public API, document whether the parameter is optional and whether the function copies or mutates caller-provided data. That distinction matters because a “safe” default can still become surprising if the function mutates the object the caller supplied.

How to Spot the Bug During Review and Testing

Look for any function definition that uses a list, dict, or set directly in the parameter list. Those are the classic cases, but the same issue can appear with custom mutable objects. The review question is simple: will this object be reused across calls if no argument is provided?

Tests should call the function more than once with no argument and confirm that the second call starts clean. A single-call test can miss the bug entirely, because the problem only shows up after prior state has accumulated. This is why the defect often survives basic smoke testing.

When a function is meant to accumulate values, make that behavior explicit with a caller-owned container or a clearly documented lifecycle. Ambiguous defaults make the code harder to reason about than an explicit object passed in by the caller.

Practitioner Guidance

What to verify: Check every function signature for mutable defaults and confirm that repeated calls do not reuse the same internal object. Pay particular attention to helper functions that look innocuous but are called many times in loops, request handlers, or test fixtures.

Common mistake: Replacing a mutable default with another mutable object just because it feels cleaner. The correct fix is not “different mutable default”, it is “no shared mutable default state”.

Decision rule: If the default value exists only to mean “nothing was passed”, use None or another immutable sentinel and create the container inside the function. If the function truly needs persistent state, make that state explicit in the design rather than hiding it in a parameter default.

Practitioner takeaway: The real goal is predictable call-by-call behavior, so the safest code makes state creation explicit and shared mutation impossible by default.

Related resources from NHI Mgmt Group

• Parameters
• What breaks when developers rely on route guards instead of server-function checks for tenant data?
• Why do developers still need defense in depth when a framework already escapes HTML by default?
• How do organisations reduce Python application risk without slowing developers down?