Python Keyword-Only Parameters: Syntax and Use Cases
Python keyword-only parameters force callers to pass arguments by name after `*`. Learn the syntax and when to use them for clearer APIs.

Python keyword-only parameters let you force callers to pass certain arguments by name, which is useful when the meaning of an argument is not obvious from its position. This feature is part of the function signature syntax and has been available since Python 3.0, though it is often overlooked in favor of more common parameter patterns.
What Keyword-Only Parameters Are
A keyword-only parameter is one that must be supplied as a keyword argument in a function call. You mark parameters as keyword-only by placing a bare * in the parameter list. The named parameters declared after that * are keyword-only. The * itself is not a parameter; it is a separator that tells the parser to treat the following named parameters as keyword-only.
For example:
def configure_server(host, port, *, timeout=30, retries=3):
...Here host and port are positional-or-keyword parameters, while timeout and retries are keyword-only. A call like configure_server("localhost", 8080, 30) raises a TypeError because 30 is interpreted as a positional argument for timeout, which is not allowed. The correct call is configure_server("localhost", 8080, timeout=30, retries=3).
Declaring Keyword-Only Parameters
The syntax is straightforward: place a * in the parameter list before the parameters you want to make keyword-only. You can have positional-or-keyword parameters before the *, and you can also use *args to capture extra positional arguments. When *args is present, the named parameters after it are automatically keyword-only. For instance:
def log_message(level, message, *args, timestamp=None):
...In this signature, level and message are positional-or-keyword, args collects any additional positional arguments, and timestamp is keyword-only. You can call it as log_message("ERROR", "Disk full", timestamp=1234567890). If you try to pass timestamp positionally, Python raises an error.
Why Enforce Keyword Arguments
The primary motivation is readability. When a function has many parameters, especially ones with default values, it is easy to misplace arguments. Requiring keyword arguments for optional settings makes the call site self-documenting. Compare:
configure_server("localhost", 8080, 30, 3)with:
configure_server("localhost", 8080, timeout=30, retries=3)The second version is clearer because it names the values. This becomes even more important when parameters have subtle meanings, such as use_ssl or max_connections. Keyword-only parameters also protect against accidental positional misordering when the function signature changes over time.
Combining with Default and Positional Parameters
You can mix positional-or-keyword, keyword-only, and *args in the same signature. The * can be used alone to mark the boundary, or you can use *args to capture extra positional arguments. If you use *args, the named parameters after it are keyword-only by definition. For example:
def send_request(url, method='GET', *, headers=None, timeout=10):
...Here url is positional-or-keyword, method is positional-or-keyword with a default, and headers and timeout are keyword-only. A call like send_request("https://api.example.com", "POST", headers={"Content-Type": "application/json"}) is valid. You cannot pass headers positionally.
Common Mistakes and Pitfalls
A frequent mistake is forgetting the * and assuming that parameters after a default value are automatically keyword-only. They are not; they can still be passed positionally unless you explicitly add the *. Another pitfall is placing * after **kwargs, which is invalid because **kwargs must be the last parameter. Also, remember that a bare * is only a separator, not a parameter. It adds useful behavior only when you declare at least one keyword-only parameter after it; if you need to accept extra positional arguments, use *args instead.
A more subtle issue is that keyword-only parameters cannot be passed positionally even if they have default values. This is a deliberate design choice to enforce clarity, but it can break existing code if you add a * to a function that previously allowed positional arguments for those parameters.
Performance and Maintainability
Keyword-only parameters add negligible runtime overhead; the enforcement is a simple check during function call resolution. The real benefit is maintainability. Because keyword-only parameters are passed by name, changing their order does not break callers. You can also add new keyword-only parameters without affecting existing calls, as long as they have default values. This is especially valuable in public APIs and frameworks where backward compatibility matters.
For example, if you have a function:
def connect(host, port, *, timeout=30):
...You can later add retries=3 without breaking existing calls. Existing callers that use connect("localhost", 8080, timeout=5) continue to work. If timeout were positional, adding a new parameter before it would break every call.
Using Keyword-Only Parameters in Class Constructors
The same syntax applies when you define __init__ and other methods manually. This is common in configuration classes where you want to prevent accidental positional misordering. For example:
class ConnectionConfig:
def __init__(self, host, port, *, timeout=30, use_ssl=True):
self.host = host
self.port = port
self.timeout = timeout
self.use_ssl = use_sslInstantiating ConnectionConfig("localhost", 8080, timeout=10, use_ssl=False) is explicit and safe. If you later add another optional parameter, existing constructor calls remain valid as long as they use keyword arguments for the optional ones.
When Not to Use Keyword-Only
Keyword-only parameters are not always the right choice. If a function has only a few parameters and their order is obvious, forcing keyword arguments can add noise. For example, a simple function like def add(a, b): does not benefit from keyword-only parameters. Also, if you need to maintain compatibility with existing positional calls, adding a * is a breaking change. Use keyword-only parameters when the function signature is likely to grow, when parameters have subtle meanings, or when you are designing a public API that should be self-documenting.
In practice, the decision comes down to balancing clarity against flexibility. If the function is internal and used in a few places, positional arguments may be fine. For public APIs, keyword-only parameters are often a good investment because they make the interface more robust to change and easier to read.
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.