Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Namedtuple Defaults: Syntax and Behavior

Learn how to set default values on Python namedtuple fields with the defaults parameter, inspect them through _field_defaults, and avoid common pitfalls with mutable defaults and dataclass alternatives.

~5 min readPython
#namedtuple#collections#python#dataclasses
Illustration of a Python namedtuple with labeled field slots showing default values

When you create a namedtuple in Python, every field is required unless you provide defaults. The collections.namedtuple factory accepts a defaults parameter that assigns default values to the rightmost fields, so callers can omit those arguments. Once you understand which fields receive defaults, how to inspect them at runtime, and how namedtuple defaults compare with dataclasses, the behavior is straightforward.

The defaults Parameter

The defaults parameter was added to collections.namedtuple in Python 3.7. It accepts an iterable of default values. The values are applied to the rightmost fields: the last value becomes the default for the last field, the previous value becomes the default for the field before it, and so on.

python
from collections import namedtuple Point = namedtuple("Point", ["x", "y"], defaults=[0, 0]) p = Point(5) print(p) # Point(x=5, y=0)

Here x and y are the rightmost fields, so both are optional and default to 0. Calling Point(5) supplies a value for x only, and y falls back to its default.

The key rule is that defaults are assigned to the rightmost fields. If you provide fewer defaults than fields, the leftmost fields remain required.

python
Person = namedtuple("Person", ["name", "age", "city"], defaults=["Unknown"]) p = Person("Alice", 30) print(p) # Person(name='Alice', age=30, city='Unknown')

In this example, only city has a default. The name and age fields must still be supplied by the caller. Attempting to construct Person("Alice") raises a TypeError because age is missing.

Inspecting Defaults with _field_defaults

Every namedtuple class exposes a _fields attribute listing its field names. The defaults are stored separately in _field_defaults, a dictionary that maps field names to their default values.

python
print(Person._field_defaults) # {'city': 'Unknown'}

The _field_defaults dictionary contains only the fields that actually have defaults. Fields without defaults are absent from the dictionary. This is useful when you need to serialize a namedtuple instance or generate documentation dynamically.

Note that _field_defaults is a plain dictionary. Mutating it does not change the behavior of the class, because the defaults are captured at class creation time. If you need to change defaults after the class is defined, you must use a different mechanism.

Setting Defaults After Class Creation

If you are working with a namedtuple class that was defined without defaults, you can attach defaults by assigning to __new__.__defaults__. This works because namedtuple generates a __new__ method whose signature reflects the field order.

python
Vector = namedtuple("Vector", ["x", "y", "z"]) Vector.__new__.__defaults__ = (0, 0) v = Vector(1) print(v) # Vector(x=1, y=0, z=0)

The tuple assigned to __defaults__ is aligned with the rightmost parameters of __new__, which correspond to the rightmost fields. Assigning (0, 0) gives defaults to y and z, while x remains required.

This technique is rarely necessary in modern code because the defaults parameter covers the same need at definition time. It is still worth knowing when you encounter older codebases that predate Python 3.7 or when you are constructing a namedtuple dynamically from metadata.

Common Mistakes with Defaults

The most frequent mistake is assuming that the defaults list fills fields from the beginning of the field list. Consider this definition:

python
Config = namedtuple("Config", ["host", "port", "debug"], defaults=["localhost", 8080])

Because defaults are applied to the rightmost fields, port defaults to "localhost" and debug defaults to 8080. The host field remains required. If you expected host and port to get the defaults, this alignment is surprising. Also, you cannot use defaults to give a default to a middle field while leaving a later field required; the defaulted fields are always the trailing ones.

The second common mistake is mixing mutable default values. Like regular function defaults, namedtuple defaults are evaluated once at class creation time. If you use a mutable object such as a list or dictionary as a default, every instance shares the same object.

python
Item = namedtuple("Item", ["name", "tags"], defaults=[[]]) a = Item("apple") b = Item("banana") a.tags.append("fruit") print(b.tags) # ['fruit']

Both instances reference the same list, so mutating one affects the other. If you need a fresh container per instance, namedtuple is the wrong tool; a regular class or a dataclass with a field(default_factory=...) is more appropriate.

Namedtuple Defaults vs Dataclass Defaults

The dataclasses module, introduced in Python 3.7, offers a more flexible default mechanism. A dataclass supports both fixed default values and default_factory callables that produce a fresh object for each instance.

python
from dataclasses import dataclass, field @dataclass class Item: name: str tags: list = field(default_factory=list)

The default_factory solves the shared-mutable-default problem that namedtuple cannot address. Dataclasses also support per-field defaults without a trailing defaults iterable, because each field declares its own default directly.

Namedtuple remains a reasonable choice when you need a lightweight, immutable, tuple-compatible record with positional access and hashing. Dataclasses provide more control over defaults, type annotations, and mutation behavior. The decision depends on whether tuple semantics matter to your code. If you rely on unpacking, indexing, or tuple equality, namedtuple preserves those behaviors. If you need per-field defaults with factory functions, dataclasses are the better fit.

Performance and Memory Considerations

Namedtuple instances are implemented as tuples, so they carry the same memory footprint as a tuple of the same length. Defaults do not change this: a default value is not stored per instance. When you omit a field, the default is filled in during construction, and the resulting tuple contains the resolved value.

This means defaults have no meaningful runtime cost beyond the normal construction path. The _field_defaults dictionary is a class-level attribute, not a per-instance attribute, so it does not add memory overhead to individual instances.

The tradeoff appears when you need mutable defaults or complex default logic. In those cases, the workaround code you would write around namedtuple defaults—such as a factory function that builds a fresh list—adds more maintenance burden than simply using a dataclass. For immutable records with simple scalar defaults, namedtuple is both concise and efficient.

When to Choose a Different Approach

If your fields are mostly required and only one or two trailing fields have simple defaults, the defaults parameter keeps the definition compact and readable. The alignment rule is easy to manage when the defaulted fields are at the end of the field list.

If you have many defaulted fields or need mutable defaults, the alignment rule in namedtuple becomes a source of bugs. A dataclass expresses each field's default next to the field itself, which is easier to review and maintain. The same applies when you need to subclass the record and extend its fields with additional defaults; dataclass inheritance rules are more explicit than namedtuple's positional defaults.

For code that must remain compatible with Python 3.6 and earlier, the defaults parameter is unavailable. In that environment, the __new__.__defaults__ assignment is the standard workaround, or you can wrap the namedtuple in a factory function that fills in missing values before construction.

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.