Skip to content

Python Positional-Only Parameters: The / Marker (3.8)

  • What the / marker does and how it combines with * in one signature.
  • The three problems it solves: frozen parameter names, **kwargs name collisions and mismatched overrides.
  • The rules for defaults, the error messages and how inspect and help() show it.
  • The traps: thinking / prevents the boolean trap, and wrappers that forward by keyword.
  • When to use / in application code and when it is a library-author tool.

A positional-only parameter can be filled only by position; passing it by name raises TypeError. You mark one by putting it before a / in the parameter list. The syntax was added in Python 3.8 by PEP 570 and is fully current in Python 3.14. Many builtins implemented in C, such as len(obj, /), have always behaved this way; / lets pure Python functions do the same. Its main benefit is that the parameter’s name is no longer part of the public API, so you can rename it, and the name stays free for use as a key in **kwargs.

With an ordinary parameter, the name is part of the contract: if any caller writes format_amount(value=10), renaming value to amount breaks that caller. PEP 570 calls this out as a burden on library authors, who must keep meaningless names like x or obj forever.

The second problem is a collision between a named parameter and **kwargs. A function that accepts arbitrary field changes cannot receive a field that happens to share the name of its first parameter. The samples on this page are plain scripts: save each as a .py file and run it with python3 file.py (Python 3.8 or later is required for /). They were run on CPython 3.14.6 and the output shown is from that run.

# Before: order_id is positional-or-keyword, so it collides with **changes.
def update_order_v1(order_id, **changes):
return order_id, changes
try:
# A client wants to change the order's external reference, stored as "order_id"
# in a partner system: the keyword cannot reach **changes.
update_order_v1("ORD-1001", **{"status": "shipped", "order_id": "PARTNER-77"})
except TypeError as exc:
print("TypeError:", exc)
# After: order_id is positional-only, so the name is free for **changes.
def update_order(order_id, /, **changes):
return order_id, changes
print(update_order("ORD-1001", status="shipped", order_id="PARTNER-77"))

Output:

TypeError: update_order_v1() got multiple values for argument 'order_id'
('ORD-1001', {'status': 'shipped', 'order_id': 'PARTNER-77'})

The standard library relies on the same trick: collections.Counter.__init__(self, iterable=None, /, **kwds) and collections.UserDict.__init__(self, dict=None, /, **kwargs) must accept any keyword, including one called iterable or dict. PEP 570 cites dict() and dict.update() as further beneficiaries.

The full signature shape, from the Python tutorial, is:

def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
----------- ---------- ----------
| | |
| Positional or keyword |
| - Keyword only
-- Positional only

Both markers are optional. Everything left of / is positional-only, everything between / and * is positional-or-keyword, and everything after * is keyword-only.

import inspect
def format_amount(value, currency="EUR", /, *, decimals=2):
return f"{value:,.{decimals}f} {currency}"
print(format_amount(1234.5))
print(format_amount(1234.56, "USD", decimals=0))
try:
format_amount(value=1234.5)
except TypeError as exc:
print("TypeError:", exc)
print(inspect.signature(format_amount))
for name, p in inspect.signature(format_amount).parameters.items():
print(f" {name}: {p.kind.name}")
# Builtins have used this calling convention for a long time.
print(inspect.signature(len), inspect.signature(sorted))

Output:

1,234.50 EUR
1,235 USD
TypeError: format_amount() got some positional-only arguments passed as keyword arguments: 'value'
(value, currency='EUR', /, *, decimals=2)
value: POSITIONAL_ONLY
currency: POSITIONAL_ONLY
decimals: KEYWORD_ONLY
(obj, /) (iterable, /, *, key=None, reverse=False)

Rules from PEP 570:

  • Defaults work as usual. Positional-only parameters may have defaults, but once one does, every following positional-only and positional-or-keyword parameter needs a default too. def f(a=1, b, /) fails with SyntaxError: parameter without a default follows parameter with a default.
  • No /, no positional-only parameters. A / must follow at least one parameter: def f(/) is a SyntaxError.
  • Lambdas accept /, just as they accept *.
  • help() and inspect.signature() show the /, which is why the notation already appeared in documentation for C builtins before 3.8.
  • Error messages name the parameter that was wrongly passed by keyword.

PEP 570 also notes that positional arguments are faster to parse and handle than keyword arguments, which is one reason builtins prefer them. In ordinary application code that difference is rarely measurable; choose / for API design reasons, not speed.

OrdersPortal applies a chain of discount rules to a subtotal and emits metrics with free-form tags. Positional-only parameters let each rule name its argument however it likes without breaking the abstract contract, and let a metric carry a tag called name.

from abc import ABC, abstractmethod
class DiscountRule(ABC):
"""OrdersPortal pricing rule. Callers pass the subtotal by position only."""
@abstractmethod
def apply(self, subtotal: float, /) -> float: ...
class PercentOff(DiscountRule):
def __init__(self, percent: float) -> None:
self.percent = percent
def apply(self, amount: float, /) -> float: # different name: fine
return round(amount * (1 - self.percent / 100), 2)
class FlatOff(DiscountRule):
def __init__(self, off: float) -> None:
self.off = off
def apply(self, total: float, /) -> float: # different name: fine
return max(total - self.off, 0.0)
def record_metric(name: str, value: float, /, **tags: str) -> str:
"""Tags are free-form, so a tag may itself be called "name" or "value"."""
tag_text = ",".join(f"{k}={v}" for k, v in sorted(tags.items()))
return f"{name} {value} [{tag_text}]"
rules: list[DiscountRule] = [PercentOff(10), FlatOff(15)]
subtotal = 120.0
for rule in rules:
subtotal = rule.apply(subtotal) # the only call form that exists
print(subtotal)
print(record_metric("orders.discounted_total", subtotal,
region="eu", name="black-friday"))
try:
PercentOff(10).apply(subtotal=50.0)
except TypeError as exc:
print("TypeError:", exc)

Output:

93.0
orders.discounted_total 93.0 [name=black-friday,region=eu]
TypeError: PercentOff.apply() got an unexpected keyword argument 'subtotal'

Without /, a caller could write rule.apply(subtotal=...), which works for the base class’s name and fails for every subclass that chose a different one. Marking the parameter positional-only makes the names irrelevant, so every override is safe to call the same way.

The following script shows the first two mistakes:

# Positional-only does not stop a caller from passing the value; it only hides the name.
def load_order(order_id, /, include_lines=False):
return order_id, include_lines
print(load_order("ORD-5", True)) # the boolean trap is still open here
def load_order_v2(order_id, /, *, include_lines=False):
return order_id, include_lines
print(load_order_v2("ORD-5", include_lines=True))
# A wrapper that forwards by keyword breaks on positional-only targets.
import functools
def call_with_kwargs(func, **kwargs):
return func(**kwargs)
try:
call_with_kwargs(load_order_v2, order_id="ORD-5")
except TypeError as exc:
print("TypeError:", exc)
print(functools.partial(load_order_v2, "ORD-5")(include_lines=True))

Output:

('ORD-5', True)
('ORD-5', True)
TypeError: load_order_v2() got some positional-only arguments passed as keyword arguments: 'order_id'
('ORD-5', True)
  • Expecting / to fix unreadable calls. It does the opposite for flags: it forbids naming them. Put flags after *, and keep / for the main subject.
  • Forwarding by keyword. Dispatchers, test helpers and functools.partial(func, order_id=...) that pass everything as keywords fail on positional-only targets. Forward positionally, or bind with partial(func, value).
  • Using / where names carry meaning. transfer(source, target, /) hides exactly the information a reader needs. Positional-only fits when order is obvious or the name is arbitrary.
  • Adding / to an existing public function without a deprecation period. Callers that used the keyword break. CPython deprecates first: Python 3.13 deprecated passing the name, argument count and callable of sqlite3.Connection.create_function() by keyword and scheduled them to become positional-only in Python 3.15.
  • Supporting Python 3.7 or older. The / marker is a SyntaxError there; the whole module fails to import.
Situation Use /? Reason
Single obvious subject: parse(text, /), add_to_queue(item, /) Yes The name adds nothing and may change
Function that also takes **kwargs with arbitrary keys Yes Frees the names for the caller
Method meant to be overridden with any parameter name Yes Overrides cannot break keyword callers
Pure Python version of a C function Yes Matches the builtin’s behavior (PEP 399)
Several parameters whose roles could be confused No Names are the documentation; consider *
Boolean or tuning options No Use keyword-only parameters

Positional-only parameters require Python 3.8 or later (PEP 570) and work unchanged in 3.14. Before 3.8, the same effect needed *args and manual unpacking, which hid the signature from tools. Keyword-only parameters (*), the counterpart, date from Python 3.0.

1. In def f(a, b, /, c, *, d), which calls are valid: f(1, 2, 3, d=4), f(1, 2, c=3, d=4), f(1, b=2, c=3, d=4)? The first two are valid. The third fails because b is positional-only and cannot be passed by keyword.

2. How can def foo(name, /, **kwds): return "name" in kwds return True, when it cannot without the /? Because name is positional-only, a keyword argument called name no longer binds to it and goes into kwds. Without /, foo(1, **{"name": 2}) raises “got multiple values for argument ‘name’”.

3. Why is renaming a positional-only parameter not a breaking change? No caller can refer to it by name, so the name is invisible to the call site. Only positional order matters.

4. Senior scenario: OrdersPortal publishes a plugin interface where third parties implement validate(self, order). Some plugins named the parameter o, others payload, and the core sometimes calls plugin.validate(order=...), which crashes for those plugins. How do you fix it? Make the interface validate(self, order, /) and change the core to call it positionally; positional-only removes the name from the contract, so every existing plugin works whatever it named the parameter. Add a static type check (for example a Protocol with the positional-only signature) in the plugin test kit, and mention in release notes that keyword calls to validate are no longer supported. If external code calls validate(order=...) itself, deprecate that with a warning for one release before the change.

  • Parameters before / can only be passed by position (PEP 570, Python 3.8).
  • Their names are not part of the API, so you can rename them and reuse them as **kwargs keys.
  • Use / for an obvious single subject, for overridable methods and to mirror builtins.
  • Do not use / for flags or confusable arguments; use * for those.
  • Adding / to a public function is a breaking change for keyword callers.