How to Update a Dictionary in Python

How-to basics · Updated November 22, 2026

Updating a dictionary in Python means changing the value of an existing key, adding a new key-value pair, or merging another dictionary into it. This is a core operation in Python programming, and there are several clean, readable ways to do it. The most direct method is to assign to a key: my_dict['key'] = new_value. This guide covers the standard update methods, including dict.update(), the ** merge operator, and the newer | operator, with clear examples and common pitfalls.

What You’ll Need

  • Python 3.5 or later (for most examples; the | operator requires Python 3.9+, and the ** merge works in 3.5+).
  • A Python interpreter or a script file where you can run code.
  • Basic familiarity with Python syntax (variables, print statements).

Step-by-Step

  1. Start with a dictionary. For example: user = {'name': 'Alice', 'age': 30}.
  2. Update a single key’s value. Use square bracket assignment: user['age'] = 31. This changes the value if the key exists, or adds a new key if it doesn’t. For instance, user['city'] = 'New York' adds a new key.
  3. Update multiple keys at once. Use the update() method with a dictionary, keyword arguments, or an iterable of key-value pairs. Example: user.update({'age': 32, 'city': 'Boston'}). This modifies the dictionary in place.
  4. Merge two dictionaries. In Python 3.9+, you can use the union operator |: merged = user | other_dict. This creates a new dictionary; it does not modify the originals. For in-place merging, use user |= other_dict.
  5. Merge using dictionary unpacking (Python 3.5+). Create a new dictionary: merged = {**user, **other_dict}. This is a common idiom and works in older versions too.
  6. Update from a list of key-value pairs. Use update() with a list of tuples: user.update([('age', 33), ('city', 'Chicago')]).
  7. Update conditionally. If you only want to update when a key doesn’t exist, use setdefault(): user.setdefault('country', 'USA') sets the value only if the key is missing.
  8. Remove a key. To delete a key, use del user['key'] or user.pop('key'). This is often part of an update workflow.

Common Mistakes

  • Forgetting that update() modifies in place. It returns None, so assigning its result to a variable gives you None.
  • Using | on Python versions before 3.9. This raises a TypeError.
  • Assuming | modifies the original. It returns a new dictionary; if you want in-place, use |=.
  • Overwriting keys unintentionally. When merging, later dictionaries override earlier ones. If you want to keep original values, swap the order.
  • Using update() with a single argument that is not a dictionary or iterable. For example, passing an integer causes a TypeError.

Tips

  • For a single key, direct assignment is the fastest and most readable.
  • For merging, prefer the | operator in Python 3.9+ for clarity; it’s the most explicit.
  • Use dict.update() when you want to modify the original dictionary in place, especially in loops.
  • If you need to update a dictionary without changing the original, always create a copy first: new_dict = original.copy() then update.
  • Remember that dictionary keys must be immutable (strings, numbers, tuples).

Troubleshooting

  • Getting a TypeError on |. Check your Python version; upgrade to 3.9 or later, or use {**dict1, **dict2}.
  • update() doesn’t seem to change the dictionary. Verify you’re not assigning the result of update() to a variable; it modifies in place, so just call dict.update(...).
  • Accidentally creating a new dictionary when you wanted to modify the original. If you use | or {**}, the original remains unchanged. Use |= or update() for in-place.
  • KeyError when trying to update a key that doesn’t exist? Direct assignment (dict[key] = value) adds the key, so no error. If you get a KeyError, you’re probably trying to read it, not update it.
  • Merging two dictionaries but losing data. Check the order: the right-side dictionary overrides the left. If you want the left to override, swap them.

Frequently Asked Questions

Q: What is the difference between update() and |?
A: update() modifies the dictionary in place and returns None. The | operator (Python 3.9+) returns a new dictionary with the merged contents, leaving the originals unchanged. Use |= for in-place merging with the operator.

Q: Can I update a dictionary with another dictionary that has nested dictionaries?
A: Yes, but the merge is shallow. The inner dictionaries are not merged recursively; the value of the right-side key replaces the left’s value entirely. For deep merging, you need to write a recursive function or use a library like copy.deepcopy and manual logic.

Q: How do I update a dictionary in a loop?
A: You can use update() inside the loop to accumulate changes, or assign directly to keys. For example: for k, v in new_data.items(): my_dict[k] = v.

Q: Is there a way to update only if the key is not already present?
A: Yes, use setdefault(key, default). It sets the value only if the key is missing, and returns the existing value if present.

Q: What happens if I update a dictionary while iterating over it?
A: Modifying the size of a dictionary during iteration can raise a RuntimeError. To avoid this, iterate over a copy: for key in list(my_dict): or collect changes and apply after the loop.

Q: Can I update a dictionary with keyword arguments?
A: Yes, update() accepts keyword arguments: user.update(age=34, city='Denver'). This is a clean way to update several keys that are valid Python identifiers.

Related

Try it: the Date Difference Calculator: days, months, years and weekdays between two dates, with the DATEDIF formulas.

More in How-to basics

Sources: Function behaviour and menu paths: Microsoft Support documentation for Excel. Method & sources

Spotted an error in this guide? Let us know.