Python: Dictionary Union Operators Explained

We all have those moments when we want to merge two Python dictionaries together based on their keys. The traditional way to do this was to use the dict.update() method. However starting Python 3.9, the much-awaited dict Union operator (| and |=) was introduced.

So what are these new Union operators and how to use them?

This is what I will discuss in this article.

Merging two Dictionaries using dict.update [Old Way]

Say you want to merge two dictionaries d1 and d2. Here is how you would do it using the dict.update method

>>> d1 = {"name": "Alice", "age": 25, "job": "Software Engineer"}
>>>
>>> d1 = {"name": "Alice", "age": 25, "job": "SWE"}
>>> d2 = {"job": "Senior SWE", "location": "US"}
>>> d1.update(d2)
>>> d1
{'name': 'Alice', 'age': 25, 'job': 'Senior SWE', 'location': 'US'}

A couple of things to notice:

• the update method didn’t create a new dictionary object, it just updated d1 in place
• the keys of the updated d1 is the union of the keys in d1 and d2
• for keys that exist in both d1 and d2, the values of those keys will be the ones in d2. In other words, d1 is actually “updated” with d2

Now let’s see how we can do the same thing with the Union operator (|)

Merging two Dictionaries using the Union Operator [Python 3.9+]

Easy and simple, this is how you do it.

>>> d1 = {"name": "Alice", "age": 25, "job": "SWE"}
>>> d2 = {"job": "Senior SWE", "location": "US"}
>>> d1 | d2
{'name': 'Alice', 'age': 25, 'job': 'Senior SWE', 'location': 'US'}

As you can see, we get the same result as before. d1 is merged with d2 and keys that exist in both dictionaries are updated with the values of the operand to the right of the union operator.

There is one difference between using the union operator and the update method though.

As you can see from the code above, the union operator actually returns a new dictionary. It doesn’t modify d1 or d2 in place.

>>> d3 = d1 | d2
>>> d1
{'name': 'Alice', 'age': 25, 'job': 'SWE'}
>>> d2
{'job': 'Senior SWE', 'location': 'US'}
>>> d3
{'name': 'Alice', 'age': 25, 'job': 'Senior SWE', 'location': 'US'}

Cool!

So what if you want to update d1 in place instead of creating a new dictionary?

In this case, you can still use the dict.update method, or even better, the augmented assignment union operator (|=)

Merging two Dictionaries using the Augmented Assignment Union Operator [Python 3.9+]

If you want to modify the dictionary d1 in place, here is how to do it using the union operator.

>>> d1
{'name': 'Alice', 'age': 25, 'job': 'SWE'}
>>> d2
{'job': 'Senior SWE', 'location': 'US'}
>>> d1 |= d2
>>> d1
{'name': 'Alice', 'age': 25, 'job': 'Senior SWE', 'location': 'US'}

Conclusion

Starting Python 3.9+, you can now use the Union operator to merge two dictionaries together.

To merge two dictionaries in place:

d1 |= d2

To merge two dictionaries and return the result in a new dictionary object:

d3 = d1 | d2

Happy Pythoning! 🙂

Learning Python?

Check out the Courses section!

Featured Posts

• The Python Learning Path (From Beginner to Mastery)
• Learn Computer Science (From Zero to Hero)
• Coding Interview Preparation Guide
• The Programmer’s Guide to Stock Market Investing
• How to Start Your Programming Blog?