How does the `|` merge operator combine two Python dicts, and how does it differ from `dict.update`?

Python has three spellings for combining two dicts, and they differ in what they return, what they mutate, and what they accept. **`a.update(b)`** has existed forever. It copies `b`'s entries into `a`, overwriting on collision, and returns `None` — the standard convention for in-place mutators, alongside `list.sort` and `list.append`. Writing `merged = a.update(b)` therefore binds `None`, which is one of the most common beginner bugs on this leaf. `update` is also the most permissive of the three about its right-hand side: it accepts any mapping, any iterable of key/value pairs, and keyword arguments, so `d.update([("k", 1)], region="eu")` is valid. **`{**a, **b}`** has worked since Python 3.5 (PEP 448). It builds a brand-new dict by unpacking both operands, right-hand wins, and generalizes to any number of operands and to inline extra keys — `{**defaults, **overrides, "trace_id": tid}`. **`a | b`** arrived in Python 3.9 (PEP 584) and is the most readable of the three for the two-dict case. It returns a **new** dict and leaves both operands untouched; on 3.8 and earlier the same expression raises `TypeError`. Its in-place sibling `a |= b` mutates `a` and, like `update` and unlike `|`, accepts an iterable of pairs on the right — `a |= [("k", 1)]` works while `a | [("k", 1)]` raises `TypeError`. One further asymmetry: for a `dict` subclass on the left, `|` returns a plain `dict`, dropping the subclass, while `|=` mutates in place and so preserves it. **Which value wins.** In all three forms, the *right-hand* operand wins on a duplicate key. `{"retries": 2} | {"retries": 5}` is `{"retries": 5}`. This is the "defaults on the left, overrides on the right" convention, and reading it backwards is the classic mistake. **Which position wins — the subtler half.** A merged key takes its **value** from the right operand but keeps its **position** from the left, because the merge is implemented as "copy the left, then update with the right", and updating an existing key never moves it. So: ```python base = {"currency": "EUR", "retries": 2} override = {"retries": 5, "timeout": 30} base | override # {'currency': 'EUR', 'retries': 5, 'timeout': 30} override | base # {'retries': 2, 'timeout': 30, 'currency': 'EUR'} ``` Note the second line: the merged dict is ordered like `override`, but `retries` carries `base`'s value of 2. Value precedence and key order come from opposite operands, and any code that treats a merged dict as ordered — writing a payroll CSV whose column order is taken from `merged.keys()`, for instance — is depending on the *left* operand's order, not on the one the reader probably assumed. That is a bug that produces a perfectly valid file with silently shuffled columns. If output order is part of your contract, state it explicitly with a key list rather than inferring it from a merge. **All three are shallow.** A merge copies references, one level deep. If a value is itself a dict or a list, the merged dict and the source share that object: ```python defaults = {"limits": {"rpm": 1200}} merged = defaults | {"region": "eu"} merged["limits"]["rpm"] = 60 # defaults is now {'limits': {'rpm': 60}} ``` Nothing in the merge protects you here, and neither does `dict.copy()`, which is also shallow. When independence matters, `copy.deepcopy` the nested structure, or write a small recursive merge — Python has no built-in deep merge, and interviewers like asking you to write one, because it forces you to say what should happen when the two sides disagree about a key's *type*. **Choosing.** For two dicts and a new result, `|` reads best and states the intent. For accumulating into an existing dict inside a loop, `update` or `|=` avoids allocating a dict per iteration. For merging more than two, or for adding literal keys at the same time, `{**a, **b, "k": v}` is the most compact. And when the values themselves are containers you intend to combine rather than replace, none of the three is what you want — you need an explicit merge function, because every built-in form replaces the whole value. **The legacy spelling.** Before PEP 448 you saw `dict(a, **b)`, which builds a new dict from `a` and then applies `b` as keyword arguments. It still works, but only when every key in `b` is a string - `dict(a, **{1: 2})` raises `TypeError: keywords must be strings` - so it is strictly weaker than the alternatives and worth recognising in old code rather than writing. `dict(a)` on its own is simply a shallow copy, the same as `a.copy()`. **Accumulating.** Inside a loop, prefer mutation over rebuilding. `merged |= chunk` (or `merged.update(chunk)`) writes into one dict, while `merged = merged | chunk` allocates and copies a fresh dict on every pass, turning a linear accumulation into a quadratic one. The functional-looking spelling is the expensive one, and this is the shape of the mistake that shows up as a job getting slower as its input grows.