Merge Dictionaries in Python

This article explains how to merge dictionaries (dict) in Python.

Refer to the following article to learn how to add or update individual items (key-value pairs) in a dictionary.

• Add and update an item in a dictionary in Python

Merge dictionaries to create a new dictionary

dict(), {}

You can specify multiple dictionaries using ** with either dict() or {}, both used for dictionary creation. The example below shows two dictionaries, but you can use three or more as well.

• Expand and pass a list and dictionary as arguments in Python

d1 = {'k1': 1, 'k2': 2}
d2 = {'k3': 3, 'k4': 4}

d = dict(**d1, **d2)
print(d)
# {'k1': 1, 'k2': 2, 'k3': 3, 'k4': 4}

d = {**d1, **d2}
print(d)
# {'k1': 1, 'k2': 2, 'k3': 3, 'k4': 4}

If the keys in the dictionaries specified as arguments overlap, this will result in an error when using dict(). On the other hand, with {}, the value of the dictionary on the right side will overwrite the corresponding value in the dictionary on the left side.

d1 = {'k1': 1, 'k2': 2}
d2 = {'k1': 100, 'k3': 3, 'k4': 4}

# d = dict(**d1, **d2)
# TypeError: dict() got multiple values for keyword argument 'k1'

d = {**d1, **d2}
print(d)
# {'k1': 100, 'k2': 2, 'k3': 3, 'k4': 4}

Refer to the following article for details on dictionary creation.

• Create a dictionary in Python ({}, dict(), dict comprehensions)

| Operator (Python 3.9 and later)

From Python 3.9, you can merge two dictionaries with the | operator. If there are duplicate keys, the value on the right side will overwrite the corresponding value on the left.

d1 = {'k1': 1, 'k2': 2}
d2 = {'k1': 100, 'k3': 3, 'k4': 4}

d = d1 | d2
print(d)
# {'k1': 100, 'k2': 2, 'k3': 3, 'k4': 4}

d = d2 | d1
print(d)
# {'k1': 1, 'k3': 3, 'k4': 4, 'k2': 2}

By using the | operator consecutively, you can combine multiple dictionaries.

d1 = {'k1': 1, 'k2': 2}
d2 = {'k1': 100, 'k3': 3, 'k4': 4}
d3 = {'k5': 5, 'k6': 6}

d = d1 | d2 | d3
print(d)
# {'k1': 100, 'k2': 2, 'k3': 3, 'k4': 4, 'k5': 5, 'k6': 6}

Merge other dictionaries into an existing dictionary

update()

If you specify another dictionary as an argument to the update() method, the dictionaries will be merged.

• Built-in Types - dict.update() — Python 3.11.3 documentation

If there are duplicate keys with the existing ones, they will be overwritten by the values of the dictionary specified in the argument.

d1 = {'k1': 1, 'k2': 2}
d2 = {'k1': 100, 'k3': 3, 'k4': 4}

d1.update(d2)
print(d1)
# {'k1': 100, 'k2': 2, 'k3': 3, 'k4': 4}

Passing multiple dictionaries directly to update() will result in an error.

d1 = {'k1': 1, 'k2': 2}
d2 = {'k1': 100, 'k3': 3, 'k4': 4}
d3 = {'k5': 5, 'k6': 6}

# d1.update(d2, d3)
# TypeError: update expected at most 1 arguments, got 2

In the update() method, you can add new items using keyword arguments (key=value). If you want to pass dictionaries as these keyword arguments, you can prefix them with **, which will pass each key-value pair as a separate keyword argument.

• Expand and pass a list and dictionary as arguments in Python

d1.update(**d2, **d3)
print(d1)
# {'k1': 100, 'k2': 2, 'k3': 3, 'k4': 4, 'k5': 5, 'k6': 6}

When using **, as shown in the above example, duplicate keys between the caller's dictionary and the dictionary specified in the argument are not a problem. However, if the same keys are found across multiple dictionaries specified in the argument, this will result in an error.

d1 = {'k1': 1, 'k2': 2}
d2 = {'k1': 100, 'k3': 3, 'k4': 4}
d3 = {'k5': 5, 'k6': 6}

# d3.update(**d1, **d2)
# TypeError: dict.update() got multiple values for keyword argument 'k1'

Refer to the following article for details on adding individual items using update().

• Add and update an item in a dictionary in Python

|= Operator (Python 3.9 and later)

As mentioned above, from Python 3.9, you can merge two dictionaries with the | operator.

Like the += operator in relation to the + operator, the |= operator allows cumulative assignment. Similar to the update() method, the object on the right side is merged into the object on the left side.

d1 = {'k1': 1, 'k2': 2}
d2 = {'k1': 100, 'k3': 3, 'k4': 4}

d1 |= d2
print(d1)
# {'k1': 100, 'k2': 2, 'k3': 3, 'k4': 4}

Note that with the |= operator, you can also specify an iterable of key-value pairs (two-element iterables), such as a list of (key, value).

d = {'k1': 1, 'k2': 2}

d |= [('k1', 100), ('k3', 3), ('k4', 4)]
print(d)
# {'k1': 100, 'k2': 2, 'k3': 3, 'k4': 4}

Be careful with the | operator, as specifying such an iterable will cause an error. Only operations between dictionaries are supported.

# d | [('k1', 100), ('k3', 3), ('k4', 4)]
# TypeError: unsupported operand type(s) for |: 'dict' and 'list'