Introduction

In Python, you do not append one dictionary to another the way you append to a list. Dictionaries are mappings, so the usual operation is merge. The main design choice is whether you want to mutate the existing dictionary or create a new one.

That distinction matters because shared dictionaries can create side effects. A merge that looks harmless in one function may unexpectedly change state seen somewhere else.

Use update() for in-place merging

If you want to modify the original dictionary, use update():

1user = {"name": "Ada", "role": "admin"}
2extra = {"active": True, "team": "platform"}
3
4user.update(extra)
5print(user)

Output:

{'name': 'Ada', 'role': 'admin', 'active': True, 'team': 'platform'}

This is concise and efficient when mutating user is exactly what you want.

Create a new dictionary when you want to preserve inputs

If you want both originals to stay unchanged, build a new dictionary instead.

1base = {"name": "Ada", "role": "admin"}
2extra = {"active": True, "team": "platform"}
3
4merged = {**base, **extra}
5
6print(merged)
7print(base)

This style is common in configuration assembly and other code paths where immutable-style data flow is easier to reason about.

In Python 3.9 and later, the merge operator is even clearer:

1defaults = {"timeout": 10, "retries": 2}
2overrides = {"timeout": 30}
3
4combined = defaults | overrides
5print(combined)

For in-place merging, use |=:

defaults |= overrides
print(defaults)

Understand what happens with duplicate keys

When the same key exists in both dictionaries, the later value wins.

1left = {"theme": "light", "page_size": 20}
2right = {"theme": "dark"}
3
4print(left | right)

The result uses "dark" for theme.

This overwrite rule applies to update(), unpacking, and the merge operator. If key collisions are significant in your domain, check for them explicitly before merging.

Simple merges are shallow

A standard dictionary merge does not recursively combine nested dictionaries. It replaces the entire nested value.

1a = {"db": {"host": "localhost", "port": 5432}}
2b = {"db": {"port": 5433}}
3
4print(a | b)

Result:

{'db': {'port': 5433}}

If you need recursive behavior, write a dedicated helper:

1def deep_merge(left, right):
2    result = left.copy()
3    for key, value in right.items():
4        if (
5            key in result
6            and isinstance(result[key], dict)
7            and isinstance(value, dict)
8        ):
9            result[key] = deep_merge(result[key], value)
10        else:
11            result[key] = value
12    return result
13
14
15first = {"db": {"host": "localhost", "port": 5432}}
16second = {"db": {"port": 5433}}
17
18print(deep_merge(first, second))

This preserves the nested "host" key while overriding only the nested "port".

Choose the method based on ownership

A good practical rule is:

• use update() when mutation is intended
• use {**a, **b} or a | b when you want a fresh dictionary
• use a custom recursive helper when nested merge semantics matter

That keeps side effects explicit and makes it easier to reason about shared state.

Common Pitfalls

The biggest mistake is thinking dictionaries have list-like append behavior. They do not. Merging is key-based, not position-based.

Another issue is forgetting that duplicate keys are overwritten by the later dictionary. If both inputs define the same key, you do not get both values unless you design a custom merge rule.

Developers also assume nested dictionaries will merge recursively by default, but ordinary merge operations are shallow.

Finally, be careful with update() in code that passes dictionaries around widely. Mutating a shared object can create bugs that are hard to trace back to the merge point.

Summary

• Dictionaries are usually merged, not appended.
• Use update() when you want to modify the original dictionary.
• Use unpacking or the | operator when you want a new merged dictionary.
• Later values overwrite earlier ones for duplicate keys.
• Built-in dictionary merges are shallow, so nested dictionaries need a custom strategy.