Introduction

In Python, "adding one dictionary into another" usually means merging key-value pairs. The correct method depends on intent: sometimes you want to mutate the original dictionary, sometimes you want a new merged result, and sometimes overlapping keys should be combined instead of overwritten.

Use update for In-Place Merging

If you want to modify the destination dictionary directly, dict.update is the standard tool.

1inventory = {"apples": 10, "bananas": 5}
2new_stock = {"bananas": 2, "oranges": 4}
3
4inventory.update(new_stock)
5print(inventory)

The result is:

{'apples': 10, 'bananas': 2, 'oranges': 4}

Notice the important rule: if the same key appears in both dictionaries, the incoming value replaces the old one.

That makes update good for overrides, but not for additive logic such as counting or stock accumulation.

Build a New Dictionary Instead of Mutating

If you want to keep both inputs unchanged, create a new merged dictionary.

In Python 3.9 and later, the merge operator is the cleanest form.

1base = {"host": "localhost", "port": 5432}
2overrides = {"port": 5433, "debug": True}
3merged = base | overrides
4print(merged)

For older versions, unpacking works the same way.

merged = {**base, **overrides}
print(merged)

In both cases, values from the right-hand side win for duplicate keys.

Combine Values Instead of Overwriting Them

If duplicate keys should be added together or otherwise merged by custom logic, write that policy explicitly.

1inventory = {"apples": 10, "bananas": 5}
2new_stock = {"bananas": 2, "oranges": 4}
3
4combined = inventory.copy()
5for key, value in new_stock.items():
6    combined[key] = combined.get(key, 0) + value
7
8print(combined)

Now the duplicate key bananas becomes 7 instead of being overwritten with 2.

This is clearer than forcing update to do something it was not designed to do.

Nested Dictionaries Are a Different Problem

Standard dictionary merges are shallow. If a value is itself a dictionary, the whole nested mapping is replaced unless you implement recursion deliberately.

1left = {
2    "db": {"host": "localhost", "port": 5432},
3    "debug": False,
4}
5right = {
6    "db": {"port": 5433},
7}
8
9shallow = left | right
10print(shallow)

The db dictionary from left is replaced completely. If that is not what you want, use a recursive merge.

1def deep_merge(a, b):
2    result = a.copy()
3    for key, value in b.items():
4        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
5            result[key] = deep_merge(result[key], value)
6        else:
7            result[key] = value
8    return result
9
10print(deep_merge(left, right))

This preserves host while updating only port.

Choose the Merge Policy Intentionally

A lot of confusion comes from assuming there is one universal "dictionary merge" operation. There is not.

A practical rule set is:

• use update when mutating the destination is fine
• use | or unpacking when you want a new dictionary
• use a custom loop when duplicate keys need special handling
• use recursion when nested dictionaries should be merged rather than replaced

The important design question is not syntax. It is what should happen when keys overlap.

Common Pitfalls

Using update and forgetting that it mutates the original dictionary is a common mistake.

Assuming duplicate keys are combined rather than overwritten is another.

Using a shallow merge on nested configuration data also causes subtle bugs because inner dictionaries get replaced entirely.

Finally, when working across Python versions, remember that the | merge operator requires Python 3.9 or later.

Summary

• 'update merges one dictionary into another by mutating the target'
• '| and unpacking create a new merged dictionary instead'
• duplicate keys are overwritten unless you define custom merge logic
• nested dictionaries need explicit deep-merge behavior if replacement is not acceptable
• choose the method based on the meaning of duplicate keys, not only on syntax convenience