A Python keyword argument passes a value by parameter name. Instead of relying only on position, the call states which parameter receives each value.
The main references are Python’s keyword argument tutorial, the function call reference, and the arbitrary argument list guide. Related PythonPool guides cover filter and lambda, type conversion with int, and Python expressions.
Keyword arguments make call sites easier to read, especially when a function accepts several optional settings. They also reduce mistakes when two parameters have the same type or similar meaning.
The tradeoff is that callers must use the exact parameter names supported by the function. Renaming a public parameter can break code that calls it by keyword.
Keyword arguments are especially helpful in functions that accept booleans, limits, modes, or formatting options. A call like save(path, overwrite=True) explains itself better than a call where True appears without context.
They are also common in third-party libraries because keyword names make large APIs easier to discover and review. The clearer the call site, the fewer comments you need around it.
Call A Function By Name
Any normal parameter can usually be supplied by position or by keyword.
def describe_pet(name, animal):
return f"{name} is a {animal}"
print(describe_pet("Milo", "cat"))
print(describe_pet(name="Milo", animal="cat"))
print(describe_pet(animal="cat", name="Milo"))
The keyword calls are explicit, and the order can change because each value is matched by name.
Use keyword syntax when the names add useful meaning. Very short calls with obvious arguments may still be clearer in positional form.
Combine Positional And Keyword Arguments
Positional arguments must come before keyword arguments in a function call.
def make_profile(username, role, active=True):
return {
"username": username,
"role": role,
"active": active,
}
profile = make_profile("ada", role="admin", active=True)
print(profile)
This call passes username by position and the other two values by keyword.
After a keyword argument appears, later arguments in the same call also need keyword syntax unless they are unpacked with a supported form.
Python also prevents giving the same parameter twice. For example, passing a value by position and then using the same parameter name by keyword raises TypeError. That check protects the function from ambiguous input.
Use Defaults For Optional Settings
Default parameter values pair naturally with keyword arguments. Callers can override only the setting they care about.
def format_price(amount, currency="USD", decimals=2):
rounded = round(amount, decimals)
return f"{currency} {rounded:.{decimals}f}"
print(format_price(19.5))
print(format_price(19.5, currency="EUR"))
print(format_price(19.5, decimals=0))
This is clearer than forcing every caller to remember the position of each optional setting.
Be careful with mutable default objects such as lists or dictionaries. Use None as the default and create the object inside the function when needed.
Accept Extra Keywords With kwargs
**kwargs collects extra keyword arguments into a dictionary. It is useful for wrappers, logging helpers, and flexible configuration APIs.
def build_url(path, **kwargs):
query = "&".join(f"{key}={value}" for key, value in kwargs.items())
if query:
return f"{path}?{query}"
return path
print(build_url("/search", q="python", page=2))
print(build_url("/about"))
Inside the function, kwargs is a normal dictionary. Validate keys before using them when the input comes from callers you do not control.
A flexible signature is convenient, but too much flexibility can hide spelling mistakes. For stable public functions, named parameters are usually better than accepting any key.
Unpack A Dictionary Into Keywords
The ** operator can unpack a dictionary into keyword arguments during a call.
def connect(host, port, secure=False):
protocol = "https" if secure else "http"
return f"{protocol}://{host}:{port}"
options = {"host": "example.com", "port": 443, "secure": True}
print(connect(**options))
The dictionary keys must match parameter names. Extra or missing keys raise an error unless the function accepts them with **kwargs or provides defaults.
This pattern works well when configuration is already stored in a dictionary and the function signature is intentionally aligned with those keys.
Require Keyword-Only Parameters
A bare * in the function signature marks later parameters as keyword-only. Callers must name those parameters.
def resize(width, height, *, keep_ratio=True, quality=90):
return {
"width": width,
"height": height,
"keep_ratio": keep_ratio,
"quality": quality,
}
print(resize(800, 600, quality=80))
Keyword-only parameters are useful for flags and options that would be confusing as bare positional values.
The practical rule is to use positional arguments for the required core data and keyword arguments for optional behavior. That keeps calls compact while still making settings easy to review.
For public APIs, choose parameter names carefully and keep them stable. A good keyword name becomes part of the interface just like the function name itself.
Python also supports positional-only parameters with a / marker in the signature. You will see this in some built-in functions and advanced APIs. It means those parameters cannot be passed by keyword, even if their internal names appear in documentation.
When designing your own functions, start with the simplest readable signature. Add keyword-only parameters when flags or optional settings would be unclear by position. Add **kwargs only when you have a real reason to accept a flexible set of names.
For debugging, read the full TypeError message when a call fails. Python usually tells you whether a required parameter is missing, an unexpected keyword was supplied, or a parameter received more than one value.