Python args vs kwargs: Choosing the Right Function Parameters
Learn how Python's *args and **kwargs work, when to use each, and how they affect function design and maintainability.

When you define a Python function, you often know exactly how many arguments it will accept. But there are cases where the number of arguments is unknown at design time. Python handles this with *args and **kwargs, two syntax forms that collect extra positional and keyword arguments. Knowing how these forms differ helps you write flexible functions, decorators, and APIs that accept variable input.
What Are *args and **kwargs?
In Python, *args and **kwargs are not reserved keywords but conventional names for two special syntax forms. When you place an asterisk before a parameter name in a function definition, Python collects any extra positional arguments into a tuple. Two asterisks before a parameter name collect extra keyword arguments into a dictionary. The names args and kwargs are conventions; you can use any name after the asterisk, but these are widely recognized.
The key distinction is that *args collects positional arguments, while **kwargs collects keyword arguments.
Syntax and Basic Usage
Consider a function that accepts any number of positional arguments:
def collect(*args):
print(args)
collect(1, 2, 3) # (1, 2, 3)Similarly, a function that accepts any number of keyword arguments:
def collect_keywords(**kwargs):
print(kwargs)
collect_keywords(a=1, b=2) # {'a': 1, 'b': 2}You can combine both with normal parameters. A standard signature that combines them normally follows this order: normal parameters, *args, keyword-only parameters, **kwargs. For example:
def f(a, b, *args, c=10, **kwargs):
print(a, b, args, c, kwargs)Here, a and b are required, extra positional arguments go to args, c is a keyword-only argument with a default, and any additional keyword arguments go to kwargs.
| Aspect | *args | **kwargs |
|---|---|---|
| Collects | Positional arguments | Keyword arguments |
| Type | tuple | dict |
| Syntax in definition | def f(*args) | def f(**kwargs) |
| Unpacking syntax | f(*iterable) | f(**mapping) |
When to Use *args
Use *args when a function needs to accept a variable number of positional arguments without knowing the exact count at definition time. A common use case is a sum function:
def total(*numbers):
return sum(numbers)
print(total(1, 2, 3)) # 6Another frequent use is in decorators. A decorator wraps a function and may need to forward any arguments the wrapped function receives. Using *args and **kwargs in the wrapper ensures it works with any signature:
def log_call(func):
def wrapper(*args, **kwargs):
print(f"Calling {func.__name__}")
return func(*args, **kwargs)
return wrapperHere, *args and **kwargs are used both to collect and to unpack when calling the original function.
When to Use **kwargs
Use **kwargs when a function needs to accept arbitrary keyword arguments. This is common in configuration systems, where you might want to set many options without defining each one as a parameter. For example:
class Config:
pass
config = Config()
def configure(**options):
for key, value in options.items():
setattr(config, key, value)
configure(debug=True, log_level="INFO")
print(config.debug) # True**kwargs also appears in frameworks that pass options through to other functions, such as a wrapper that forwards extra keyword arguments to a library call.
Common Mistakes and Pitfalls
A frequent mistake is confusing the collecting syntax with the unpacking syntax. In a function definition, *args collects extra arguments. In a function call, *args unpacks an iterable into positional arguments. The same applies to **kwargs for dictionaries.
def f(a, b, c):
print(a, b, c)
args = (1, 2, 3)
f(*args) # Unpacks tuple into positional arguments
kwargs = {'a': 1, 'b': 2, 'c': 3}
f(**kwargs) # Unpacks dict into keyword argumentsAnother pitfall is overusing *args and **kwargs when explicit parameters would make the function clearer. If a function only ever receives two or three specific arguments, defining them explicitly improves readability and enables static analysis. Reserve *args and **kwargs for cases where the number of arguments is genuinely variable or when you need to forward arguments transparently.
Performance and Maintainability Considerations
*args and **kwargs introduce a small runtime overhead because Python must create a tuple and a dictionary to hold the collected arguments. For most functions this is negligible, but in tight loops or extremely hot paths it can matter. If performance is critical, prefer explicit parameters where the argument count is fixed.
Maintainability is a more significant concern. Functions with *args and **kwargs are harder to inspect because their signatures do not reveal what arguments they accept. This makes debugging and documentation more difficult. Use them deliberately, and consider adding type hints or docstrings to clarify expected inputs.
Advanced Patterns and Limitations
Python 3 supports keyword-only arguments by placing a bare * in the parameter list. For example:
def f(a, *, b):
return a + bHere, b must be passed as a keyword argument. This is useful when you want to enforce clarity in calls.
When overriding methods in subclasses, you can use *args and **kwargs to accept any arguments the parent method might pass, but this can hide signature mismatches. Prefer explicit signatures when the interface is fixed.
In general, *args and **kwargs are powerful tools for writing flexible and reusable code, but they should not replace well-defined parameters when the API is known.
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.