Python dataclass replace vs Manual Copy: Which Is Faster?

Intro — what this post promises

Python's dataclasses.replace(obj, field=value) is the safe way to copy a dataclass with one field changed, but it is slower than building the new instance by hand: updating one field on 5,000 instances it ran about 900k ops/s, against about 6.5M for a manual positional constructor (about 7.2x) and 3.1M for keyword arguments. Use replace by default, because it survives field reorders and new defaults, and switch to a manual constructor only where profiling shows a hot loop paying for it.

It is not dataclass-vs-slots creation/memory (lab 44). Focus: the replace / update pattern.

Related links:

• 01shoppercove.comdataclass vs slots vs dict localhost lab
• 02shoppercove.comheapq merge vs sorted localhost lab
• 03shoppercove.comislice vs list slice localhost lab
• 04shoppercove.comconfigparser vs json localhost lab
• 05shoppercove.comhtml escape vs manual localhost lab
• 06shoppercove.comzlib vs gzip compress localhost lab
• 07shoppercove.comdifflib vs set ops localhost lab
• 08shoppercove.comstat vs path stat localhost lab

Lab honesty (1 Oct 2026 IST): Python 3.13.5. Affiliates: 0. No Docker. Order with 5 fields; also @dataclass(slots=True).

Verdict up front (5000 instances, flip status): manual positional ~6456211 ops/s; manual keyword ~3129734; replace ~900026; copy.copy+mutate ~526727. Prefer replace for clarity when fields evolve; manual wins raw speed if the shape is frozen.

Arms

Lab topology

n=5000 Order objects · 7 rounds · p50
metric: ops/s = n / p50_s (batch) · hot single also timed

Script: lab-evidence/110-dataclass-replace-vs-manual/results/run_lab.py.

Lead table — one-field status flip (p50)

Two-field & hot single

Why replace anyway

replace survives field reorders and defaults — you name only what changes. Manual constructors break silently when someone inserts a field. On this box replace is ~7.2× slower than positional manual for a one-field flip; that tax is often fine outside tight inner loops.

Reading it

• Domain models / event sourcing copies → replace.
• Ultra-hot numeric kernels with a stable schema → manual construct may win.
• copy.copy + mutate trailed here and is easy to get wrong with nested mutables.
• Slots change allocation; replace still pays helper overhead (lab 44 for create/memory).

Frozen note

With frozen=True, in-place mutation is impossible — replace (or a new construct) is mandatory. The speed story then becomes replace vs manual new, not copy-mutate. Measure that variant if your models are frozen.

Field-count sensitivity

replace inspects the dataclass fields and builds a new instance via the generated constructor. More fields ⇒ more work per call, while a positional manual build always passes every argument explicitly. If your record grows to dozens of columns, re-benchmark — the maintainability case for replace gets stronger even if the relative gap widens.

Event / reducer style

Pipelines that emit “old row → new row” copies map cleanly to replace(old, changes). That keeps call sites short when only 1–2 keys change across many event types. Micro-optimizing to manual constructors tends to fork a family of nearly identical Order(...) lines that drift.

Pitfalls

• Mutating shared nested objects after shallow copy.
• Hand-rolling constructors that drift from the dataclass definition.
• Using replace in a micro-hot loop without measuring.
• Confusing this with slots-vs-dict creation benches.

Reproduce

python3 lab-evidence/110-dataclass-replace-vs-manual/results/run_lab.py

Evidence: summary.json, summary.txt.

Limits

One Linux box. Flat string/int fields only. Not frozen=True hash maps. Not pydantic/attrs.

Takeaway

Updating status on 5000 orders: manual ~6456211 ops/s beat replace ~900026 ops/s. Default to dataclasses.replace for maintainability; drop to manual only when profiles prove the gap matters.

FAQ

What does dataclasses.replace do?

It builds a new instance of the dataclass with the fields you name changed and everything else copied, using the generated constructor. You only name what changes.

Is dataclasses.replace slow?

Compared with a manual constructor, yes: about 900k ops/s vs 6.5M positional for a one-field flip on Python 3.13.5. It still beat copy.copy plus mutate (about 527k ops/s).

Do I need replace with frozen dataclasses?

Yes, or a new manual construct. With frozen=True you cannot mutate in place, so replace is the standard way to get an updated copy.