skip to content

In Pydantic 2, why is `items: list[LineItem] = []` safe on a BaseModel, and when do you still need `default_factory`?

level: middleimportance: should knowfreq 55%

answer

  1. unhashable defaults copied
  2. one copy per instance
  3. computed per instance
  4. factory may receive validated data

basics

~20 s

Pydantic 2 deep-copies an unhashable default such as [] for each instance, so instances never share it. Use default_factory when the default must be computed per instance, like an id or a timestamp, or derived from earlier fields.

solid answer

~40 s

A plain `= []` is shared by every call in ordinary Python, and a standard dataclass refuses it outright. Pydantic 2 instead **deep-copies an unhashable default** each time it builds an instance, so `items: list[LineItem] = []` is safe. You still need `Field(default_factory=...)` when the value must be **computed at instantiation**: a fresh `uuid4().hex`, `datetime.now(timezone.utc)`, anything whose plain default would be evaluated once at class definition. Since 2.10 a factory may also take one argument, the **already validated data**, so a field can default from an earlier one, provided that earlier field is declared first. Remember that defaults are **not validated** unless `validate_default=True` is set on the field or in the config.

code

python · 28 lines
python
from datetime import datetime, timezone
from uuid import uuid4

from pydantic import BaseModel, Field


class LineItem(BaseModel):
    sku: str
    quantity: int = 1


class Order(BaseModel):
    order_id: str = Field(default_factory=lambda: uuid4().hex)
    received_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
    customer_email: str
    contact_email: str = Field(default_factory=lambda data: data['customer_email'])
    items: list[LineItem] = []


a = Order(customer_email='[email protected]')
b = Order(customer_email='[email protected]')
a.items.append(LineItem(sku='SKU-1'))
print(len(a.items), len(b.items))
#> 1 0
print(b.contact_email)
#> [email protected]
print(a.order_id != b.order_id)
#> True

go deeper

for a junior

Recall that a list default is safe on a Pydantic model because each instance gets its own copy, and that default_factory exists for computed values.

for a middle

Explain the deep copy of unhashable defaults, the cases that still need a factory, the data-taking factory and its ordering rule, and that defaults skip validation.

for a senior

Spot import-time timestamps and ids in review, and decide where validate_default should be on because defaults come from code or configuration that can drift.

for a principal

Weigh a team convention of always writing default_factory for clarity against relying on Pydantic's copying, and whether validate_default belongs in a shared base config.

## The Python problem Pydantic sidesteps In plain Python, a default value is evaluated **once**, when the function or class body runs. If that value is a mutable object such as a list or a dict, every caller that relies on the default receives the very same object, so one caller's `append` shows up for everyone. The standard library's dataclasses respond by raising an error for a list default and telling you to use a factory. Pydantic 2 takes a different route. When a field's default is **not hashable** (lists, dicts, sets and the like), Pydantic makes a **deep copy** of it for every new model instance. So on a `BaseModel` this is fine: ```python class Order(BaseModel): items: list[LineItem] = [] tags: dict[str, str] = {} ``` Each `Order` receives its own empty list and its own empty dict. A hashable default such as a tuple or a string is used as is, which is harmless because it cannot be mutated in place. ## When you still need `default_factory` `Field(default_factory=callable)` tells Pydantic to **call** the function each time a value is needed, instead of copying a stored value. Reach for it in these cases: 1. **The value must be different per instance.** An order id from `uuid4().hex`, or a `received_at` timestamp. Written as a plain default, `datetime.now(timezone.utc)` runs once at import time, and every order gets the import time. Pydantic only copies unhashable defaults, and a datetime is hashable, so the one import-time value is reused. 2. **The value depends on another field.** Since version 2.10, a factory may accept a single argument; Pydantic passes it a dictionary of the **already validated data**. A `contact_email` can default to `customer_email`. 3. **Clarity for readers and type checkers.** `default_factory=list` states intent explicitly, and static type checkers understand `default_factory` in the assignment form. ## The ordering rule for factories that read data The dictionary passed to a data-taking factory contains **only fields validated so far**, and Pydantic validates fields in declaration order. So: - `customer_email` must be declared **above** `contact_email`, or it is not in the dictionary yet and the lookup fails. - Reordering fields during a refactor can therefore break a factory that used to work, so keep dependent fields together. ## Defaults are trusted, not validated By default Pydantic does **not** run validation on default values, whether they are stored or produced by a factory. That has two consequences: | Situation | Result without `validate_default` | Result with `validate_default=True` | |---|---|---| | `quantity: int = Field(default='one')` | the instance holds the string `'one'` | `ValidationError`, type `int_parsing` | | `quantity: int = Field(default='3')` | the instance holds the string `'3'` | the instance holds the integer `3` | `validate_default` can be set per field in `Field()` or for the whole model in `ConfigDict`. It is worth turning on where defaults come from code that may drift, such as a factory reading configuration. ## A worked order model For the partner order scenario, a sensible declaration is: - `order_id: str = Field(default_factory=lambda: uuid4().hex)`: a fresh id each time. - `received_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))`: the moment of validation, not of import. - `customer_email: str`: required. - `contact_email: str = Field(default_factory=lambda data: data['customer_email'])`: copies the earlier field when the partner omits it. - `items: list[LineItem] = []`: safe, because Pydantic copies it. ## Private attributes follow the same pattern Models can also hold **private attributes**, names starting with an underscore that are not fields: they are not validated and are not part of the input. They take defaults the same way, through `PrivateAttr(default=...)` or `PrivateAttr(default_factory=...)`. A typical use is `_processed_at: datetime = PrivateAttr(default_factory=datetime.now)`, a timestamp the code sets for itself and never accepts from a partner. Since version 2.13, a private attribute's factory may also take the validated data as its argument, mirroring what field factories gained in 2.10. That lets a private cache key, for example, be derived from the validated order id without a custom `__init__` or a post-initialisation hook. ## Common misreadings - Believing Pydantic shares a list default between instances, and wrapping every list in a factory out of fear. It is not wrong, just unnecessary. - Believing Pydantic raises the dataclass error for a list default. It does not. - Expecting a default of the wrong type to be caught at class definition. It is not caught at all unless `validate_default` is on, and then only when an instance is created. - Expecting a data-taking factory to see fields declared below it.

  • In Pydantic 2, what does `validate_default=True` change, and where can you set it?
    It makes Pydantic run the field's validation on the default value when an instance is created without that field, so a default of the wrong type raises a ValidationError and a convertible one is converted. Set it per field with `Field(validate_default=True)` or for a whole model with `ConfigDict(validate_default=True)`. Without it, defaults are used exactly as written.
  • In Pydantic 2, why does `received_at: datetime = datetime.now(timezone.utc)` give every order the same timestamp?
    The expression runs once, when the class body executes at import time. The resulting datetime is hashable, so Pydantic uses it as is rather than copying it, and every instance that omits the field gets that import-time value. `Field(default_factory=lambda: datetime.now(timezone.utc))` calls the function at each instantiation instead.

A stored default is a form template that the clerk photocopies for every customer, so nobody scribbles on anyone else's copy. A default factory is the clerk filling in the date and a ticket number at the moment you walk up.

  • A list default on a Pydantic model is shared by every instance.
  • Pydantic raises the same ValueError as dataclasses for a list default.
  • Default values are validated and converted just like input values.
  • A default factory that takes data can read fields declared after it.
  • A plain default of datetime.now() is evaluated for every new instance.