Merge Dictionaries in Python: Methods & Examples

Merging dictionaries is a common task. You often need to combine data from multiple sources. Python offers several clean ways to do this. The best method depends on your Python version and needs.

This guide covers all major techniques. We will explore the update method, the union operator, and dictionary unpacking. You will learn to handle conflicts and choose the right tool.

Why Merge Dictionaries?

Dictionaries store key-value pairs. Merging combines two or more dictionaries into one. It is useful for consolidating configuration settings, combining API responses, or aggregating data.

Imagine you have user data from two systems. You need a single profile. Dictionary merging makes this simple and efficient.

Method 1: The update() Method

The update() method is a classic approach. It modifies the original dictionary in place. It adds items from another dictionary. If keys overlap, values from the new dictionary win.

# Example of the update() method
dict1 = {"a": 1, "b": 2}
dict2 = {"b": 99, "c": 3}

dict1.update(dict2)
print("Merged Dictionary:", dict1)
    

Merged Dictionary: {'a': 1, 'b': 99, 'c': 3}
    

Notice key "b" changed from 2 to 99. The value from dict2 overwrote the value from dict1. The original dict1 was changed. For more on this method, see our Python Dict Update Method Guide & Examples.

Method 2: Dictionary Unpacking (**)

Python 3.5+ introduced dictionary unpacking. Use the ** operator inside curly braces. This creates a new dictionary without altering the originals. Later dictionaries override earlier ones for duplicate keys.

# Example of dictionary unpacking
dict1 = {"name": "Alice", "score": 85}
dict2 = {"score": 90, "city": "Berlin"}

merged_dict = {**dict1, **dict2}
print("Merged Dictionary:", merged_dict)
print("Original dict1:", dict1) # Unchanged
    

Merged Dictionary: {'name': 'Alice', 'score': 90, 'city': 'Berlin'}
Original dict1: {'name': 'Alice', 'score': 85}
    

This is a clean, readable syntax. It is excellent for creating a new combined dictionary. You can unpack more than two dictionaries easily.

Method 3: The Union Operator (|)

Python 3.9 added the merge (|) and update (|=) operators. They provide an intuitive way to merge dictionaries. The | operator returns a new dictionary. The |= operator updates in place, similar to update().

# Example of the union | operator
config_default = {"theme": "light", "language": "en"}
config_user = {"language": "fr", "notifications": True}

final_config = config_default | config_user
print("Final Config:", final_config)

# Using the in-place |= operator
config_default |= config_user
print("Updated Default Config:", config_default)
    

Final Config: {'theme': 'light', 'language': 'fr', 'notifications': True}
Updated Default Config: {'theme': 'light', 'language': 'fr', 'notifications': True}
    

This is now the recommended method for Python 3.9+. It is very readable and explicit.

Merging Multiple Dictionaries

You often need to merge more than two dictionaries. All methods shown can be extended. Here is an example using the union operator.

# Merging three dictionaries
defaults = {"color": "red", "size": "M"}
inventory = {"size": "L", "stock": 50}
pricing = {"price": 29.99, "color": "blue"}

product_info = defaults | inventory | pricing
print("Product Info:", product_info)
    

Product Info: {'color': 'blue', 'size': 'L', 'stock': 50, 'price': 29.99}
    

The order matters. The rightmost dictionary's values take precedence. For complex merging logic, you might use a Python Dict Comprehension Guide & Examples.

Handling Nested Dictionaries

Simple merging only works on the top level. For nested dictionaries, you need a recursive merge. This combines dictionaries inside dictionaries.

# Simple merge fails for nested dicts
dict_a = {"user": {"name": "Alice", "id": 1}}
dict_b = {"user": {"id": 2, "city": "Paris"}}

simple_merge = dict_a | dict_b
print("Simple Merge:", simple_merge) # The entire 'user' dict is replaced
    

Simple Merge: {'user': {'id': 2, 'city': 'Paris'}}
    

To merge nested structures, you need a custom function. This function checks if a value is a dictionary and merges it recursively.

Choosing the Right Method

How do you pick a method? Consider your Python version and whether you need a new dictionary.

• Python 3.9+: Use the | operator for clarity.
• Modify in-place: Use update() or |=.
• Create a new dict: Use ** unpacking or |.
• Older Python (3.5-3.8): Use ** unpacking.
• Very old Python: Use update() or a loop.

Understanding these methods is part of mastering Python Dictionary Methods Guide & Examples.

Common Pitfalls and Tips

Be aware of key conflicts. The last value always wins. Plan your merge order accordingly.

Mutable values are not copied deeply. If you merge dictionaries containing lists, changes to the original list will affect the merged dictionary. Use the copy module for deep copies if needed.

Remember, dictionary keys must be hashable. You cannot use a list or another dictionary as a key.

Conclusion

Merging dictionaries in Python is straightforward. You have multiple tools: update(), ** unpacking, and the | operator.

For modern Python, the | operator is the cleanest choice. For in-place changes, use update() or |=. For nested dictionaries, you may need a custom recursive function.

Choose the method that fits your Python version and whether you need a new dictionary. This skill is essential for effective data handling in Python.