Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~4 min readPython
#Python#function arguments#keyword arguments#positional arguments
Illustration comparing positional and keyword arguments in Python function calls

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:

python
def greet(name, greeting): print(f"{greeting}, {name}!") greet("Alice", "Hello") # Both arguments are positional

Here, "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:

python
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:

python
greet(name="Carol", "Hey") # SyntaxError: positional argument follows keyword argument

The correct order is:

python
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:

python
def configure(host, port=8080, debug=False): print(host, port, debug) configure("localhost", debug=True) # port uses default

Common 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:

python
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.

python
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:

python
def create_user(name, email, *, age=None, admin=False): pass

Here, 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 tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.