Python Positional vs Keyword Arguments
Understand the difference between positional and keyword arguments in Python, including their syntax, ordering rules, and when to use each style.

In Python, function arguments can be passed in two distinct ways: positionally or by keyword. The choice affects readability, maintainability, and the flexibility of your function signatures. Understanding the difference between these two styles is essential for writing clear APIs and debugging common errors.
What Are Positional Arguments?
Positional arguments are matched to parameters based on their order in the function call. For example:
def greet(name, greeting):
print(f"{greeting}, {name}!")
greet("Alice", "Hello") # Both arguments are positionalHere, "Alice" maps to name and "Hello" maps to greeting solely because of their positions. If you swap them, the output changes accordingly. This is straightforward for functions with few parameters, but it becomes error-prone when the parameter list grows or when parameters have similar types.
What Are Keyword Arguments?
Keyword arguments are passed using the parameter name explicitly, like this:
greet(name="Bob", greeting="Hi")Now the order does not matter; the mapping is determined by the names. This improves readability at the call site, because the reader can see which value corresponds to which parameter without checking the function definition. It also reduces the chance of accidentally swapping values.
Ordering Rules and Syntax Constraints
Python enforces a specific order when mixing positional and keyword arguments in a single call. All positional arguments must come before any keyword arguments. The following is invalid:
greet(name="Carol", "Hey") # SyntaxError: positional argument follows keyword argumentThe correct order is:
greet("Carol", greeting="Hey")This rule exists to avoid ambiguity: once a keyword argument is used, the parser cannot reliably determine how to assign remaining positional values.
Default values also interact with this. A parameter with a default can be omitted, but if you want to pass a later parameter by keyword while skipping an earlier one, you must use keyword arguments. For example:
def configure(host, port=8080, debug=False):
print(host, port, debug)
configure("localhost", debug=True) # port uses defaultCommon Mistakes and How to Avoid Them
One frequent error is forgetting to pass a required argument. If a function expects two positional parameters and you supply only one, Python raises TypeError: missing 1 required positional argument. This is easy to miss when the function has many parameters. Using keyword arguments at the call site can make the missing argument more obvious, but it does not prevent the error.
Another mistake is relying on positional order for boolean or numeric flags. For instance, a function like send_email(to, subject, cc=None, bcc=None) becomes hard to read if you call it with four positional values. Using keywords for optional parameters clarifies the intent:
send_email("user@example.com", "Hello", bcc="admin@example.com")When to Use Each Style
Positional arguments are best for parameters that are required and have a natural, obvious order, such as coordinates or a pair of values. They reduce typing and keep the call concise. Keyword arguments shine when parameters are optional, have defaults, or when the meaning of a value is not immediately clear from the value alone.
For API design, a common practice is to use positional arguments for the first few required parameters and keyword arguments for optional ones. This matches Python's standard library conventions. For example, print(*objects, sep=' ', end='\n') accepts the values positionally, while options such as sep and end are named keyword arguments.
Runtime Behavior and Performance Considerations
From a runtime perspective, the important difference is how arguments are bound before the function body runs. Once binding is done, the function body executes the same way, so the choice of calling style is mainly a readability and API-design decision. The way arguments are passed can also affect debugging and introspection. For instance, inspect.signature can show the actual parameter names, which helps with tooling and documentation.
One subtle difference is that keyword arguments allow you to pass values in any order, which can be useful when calling functions with many parameters. But this flexibility also means that a typo in a parameter name will raise a TypeError: unexpected keyword argument. This is often preferable to silently binding a wrong value.
Advanced Usage: *args and **kwargs
Python's *args and **kwargs mechanisms let you handle variable numbers of arguments. *args collects extra positional arguments into a tuple, while **kwargs collects extra keyword arguments into a dictionary. These are useful for decorators, wrappers, and forwarding calls.
def log_call(func, *args, **kwargs):
print(f"Calling {func.__name__} with {args} and {kwargs}")
return func(*args, **kwargs)When forwarding, using *args and **kwargs together preserves the original distinction between positional and keyword arguments, so the wrapped function receives them correctly. This is a common pattern in frameworks and libraries.
Best Practices for Function Signatures
Design your function signatures to make the intended usage obvious. For functions with more than three or four parameters, prefer keyword-only arguments for optional or ambiguous ones. You can enforce this by placing a * in the parameter list:
def create_user(name, email, *, age=None, admin=False):
passHere, age and admin can only be passed as keyword arguments. This prevents callers from accidentally passing them positionally, which reduces confusion and errors.
When you have many parameters, consider using a data class or a configuration object instead of a long parameter list. This improves maintainability and makes the call site more readable.
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.