Python *args and **kwargs Explained the Easy Way

Python args and kwargs look like syntax soup the first time you see them. A star, sometimes two stars, two unfamiliar names, and a function that suddenly accepts any number of arguments. The good news is that the underlying idea is small. The star tells Python to collect extra positional arguments into a tuple. The double star tells Python to collect extra keyword arguments into a dictionary. Once those two sentences click, every advanced shape that uses them becomes legible.

What the Single Star Actually Does

A single star in a function definition collects every extra positional argument into a tuple. The name after the star can be anything, but the Python community has long agreed on args, which is why the feature is universally called args even though the keyword is just the star. Inside the function body, args is a regular tuple that you can index, iterate, and pass on to other functions like any other sequence.

python

def total(*args):
    return sum(args)
 
print(total(1, 2, 3, 4))

The function above accepts any number of positional arguments. The call passes four numbers, which Python packs into a tuple named args, and the body returns their sum. The same function called with no arguments would return zero, because sum on an empty tuple is zero. The mental model is to picture the caller pouring arguments into a tube, with the star at the function definition collecting whatever pours through. To revisit how regular functions work without the variable arguments trick, our piece on Python functions explained with real use cases covers the simpler base case.

What the Double Star Actually Does

Two stars in a function definition collect every extra keyword argument into a dictionary. The name after the double star is conventionally kwargs, again by community agreement rather than language rule. Inside the function body, kwargs is a regular dictionary whose keys are the argument names and whose values are the argument values. The dictionary supports every normal dictionary method and can be iterated, looked up, or passed on like any other mapping.

A describe function written as def describe with two stars before kwargs accepts calls like describe with name equal to Mira and age equal to thirty one. Python packs those keyword pairs into a dictionary named kwargs, and the function body can iterate the dictionary's items, look up a particular key, or pass the whole dictionary on to another function. The same model that explained the single star applies here, just with the named arguments collected into a dictionary instead of the positional arguments collected into a tuple. For a deeper picture of how Python dictionaries themselves behave, our walkthrough on Python dictionaries explained with real-world examples sits next to this article cleanly.

Mixing Args, Kwargs, and Regular Parameters

A function can mix regular parameters, args, and kwargs in the same signature, but the order has to be exact. Regular positional parameters come first, then the args collector with a single star, then keyword-only parameters, then the kwargs collector with a double star. Python enforces this order at parse time, which means a misplaced star is a SyntaxError rather than a runtime bug. Once you internalise the order, designing flexible function signatures becomes mechanical.

A typical request helper might be written as def request taking a required url, then a star args collector, then a keyword-only method parameter with a default of GET, then a double star kwargs collector. The signature has a required positional parameter, an args collector, a keyword-only parameter with a default, and a kwargs collector. A caller can supply any combination of positional and keyword arguments and the function will accept them all. Functions in the standard library and in popular packages use this shape extensively, which is why understanding the order pays off across almost every Python codebase. The same shape is exactly what wrapper functions, decorators, and adapter layers reach for whenever they need to forward an unknown set of arguments through to an underlying function without changing them. For a closer look at how return values flow back out of functions like these, our guide on Python return statements explained beyond basics covers the matching return side.

Unpacking with the Same Stars

The two stars do not only appear in function definitions. They also appear at call sites, where they reverse the operation. A single star before a sequence in a function call unpacks the sequence into separate positional arguments. A double star before a dictionary in a function call unpacks the dictionary into separate keyword arguments. The same star, the same direction of thought, just running in reverse.

python

numbers = [1, 2, 3]
print(*numbers)
 
config = {"sep": ",", "end": "\n"}
print("a", "b", **config)

The first print unpacks the list into three separate arguments. The second print unpacks the dictionary into the sep and end keyword arguments. The same pattern is how you forward arguments from one function to another, by accepting args and kwargs in the outer function and immediately calling the inner function with the same args and kwargs after their own stars. This is the trick behind decorators and wrapper functions in everyday Python code.