Python Default Argument vs Keyword Argument: Understanding the Difference

Python developers often confuse default arguments with keyword arguments because both appear in function definitions and calls. A default argument is a parameter with a preset value, while a keyword argument is a value passed by name. They are not mutually exclusive; they serve different purposes and can be used together. The distinction between python default argument vs keyword argument is a frequent source of confusion, but once you understand how each works, you'll write clearer and safer functions.

Default Arguments: Defined in the Function Signature

A default argument is a parameter that assumes a value if the caller omits it. You define it in the function signature using an equals sign:

def greet(name, greeting="Hello"):
    print(f"{greeting}, {name}!")

Here, greeting has a default value of "Hello". If you call greet("Alice"), Python uses the default. If you call greet("Bob", "Hi"), it uses "Hi" instead. The default value is evaluated only once, at the time the function is defined, not each time the function is called. This behavior has a significant consequence when the default is a mutable object, as we'll see later.

Default arguments are positional by default. They can be overridden positionally or by keyword, but the order of parameters matters when using positional arguments.

Keyword Arguments: Passing Values by Name

A keyword argument is a way to pass a value to a function by explicitly naming the parameter it corresponds to. In the call, you write parameter=value:

greet(name="Alice", greeting="Hi")

Keyword arguments make calls more readable, especially when a function has many parameters. They also allow you to skip optional parameters without providing values for earlier ones. For example:

def create_user(name, age=None, active=True):
    ...

create_user("Alice", active=False)

Here, age is omitted, but active is set using a keyword argument. Without keyword arguments, you would have to pass None for age explicitly.

How Default Arguments and Keyword Arguments Interact

Default arguments and keyword arguments are not competing features. A default argument can be overridden by a keyword argument, and a keyword argument can be used to supply a value for a parameter that has a default. The two work together naturally:

def configure(host="localhost", port=8080, debug=False):
    print(f"{host}:{port} debug={debug}")

configure(port=9090)  # host and debug use defaults
configure(debug=True, host="example.com")  # order does not matter

Keyword arguments let you specify only the parameters you need, while defaults fill the rest. This is a common pattern for configuration functions and APIs with many optional settings.

The Mutable Default Argument Trap

Because default values are evaluated once at definition time, using a mutable object like a list or dictionary as a default can lead to unexpected behavior. Consider:

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

The list items is created once when the function is defined. Every call that omits items shares the same list object:

print(add_item("a"))  # ['a']
print(add_item("b"))  # ['a', 'b']  # not ['b']!

The function accumulates state across calls, which is usually not what you want. The standard fix is to use None as a sentinel and create a new list inside the function:

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

This ensures each call gets a fresh list unless the caller explicitly passes one. The same applies to dictionaries, sets, and any mutable object.

Common Mistakes and How to Avoid Them

Beyond mutable defaults, several related mistakes appear frequently. One is mixing positional and keyword arguments incorrectly. In Python, positional arguments must come before keyword arguments in a call. Another is using a mutable default without realizing it is shared. A third is overusing keyword arguments when a simple positional argument would be clearer, or vice versa.

To keep code maintainable, follow these guidelines:

• Use keyword arguments for optional parameters and for parameters that are not obvious from the context.
• Use positional arguments for required parameters that have a natural order.
• Avoid mutable defaults; use None and create a new object inside the function.
• When a function has many parameters, consider grouping related ones into a data class or using keyword-only arguments.

When to Use Default Arguments vs Keyword Arguments

Default arguments are a feature of the function definition; keyword arguments are a feature of the function call. You decide whether a parameter should have a default based on whether the caller should be able to omit it. You decide whether to use keyword arguments based on readability and the need to skip optional parameters.

Use default arguments when a parameter has a sensible default that most callers will accept. Use keyword arguments when a function has many parameters, when you need to skip optional ones, or when passing a value that is not obvious from position alone.

Advanced Parameter Types: Keyword-Only and Positional-Only

Python 3 introduced syntax to enforce how arguments are passed. You can define keyword-only arguments by placing them after a * in the signature. These arguments must be passed by name, even if they have defaults:

def save_file(path, *, overwrite=False):
    ...

save_file("data.txt", overwrite=True)  # valid
save_file("data.txt", True)  # TypeError: overwrite is keyword-only

Similarly, positional-only arguments can be defined before a /:

def divide(a, b, /):
    return a / b

divide(10, 2)  # valid
divide(a=10, b=2)  # TypeError: a and b are positional-only

These features give you precise control over the function's API. They are especially useful in libraries where you want to avoid breaking changes or where parameter names are not meaningful to callers. When combined with default arguments, they let you design functions that are both flexible and explicit.

Understanding the distinction between default arguments and keyword arguments is foundational to writing Python that is clear and predictable. The mutable default pitfall is a classic example of how a subtle detail in the language can cause bugs. By applying the patterns described here, you can avoid these issues and make your functions behave exactly as intended.