Python dict.update() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
dict method

Definition

update() copies key/value pairs into the dict it is called on. New keys are added at the end; keys that already exist get the new value and keep their position.

It accepts three kinds of input, which can be combined in one call: another dict (or mapping), an iterable of 2-item pairs such as a list of tuples or a zip() object, and keyword arguments. It changes the dict in place and returns None.

dict.update() is an instance method of the built-in dict type: call it on a dictionary with dot notation, such as settings.update(...). No import is needed.

Syntax

Pass one positional source, keyword arguments, or both.

python
d.update(other_dict)
d.update([("key", "value"), ("key2", "value2")])
d.update(key="value", key2="value2")
CallWhat it does
{"a": 1}.update({"a": 9, "b": 2})Returns None; the dict becomes {'a': 9, 'b': 2}.
d.update([("c", 3), ("d", 4)])Adds or overwrites keys "c" and "d" from a list of pairs.
d.update(x=1, y=2)Adds or overwrites the string keys "x" and "y".

When the same key appears more than once, the last value wins; keyword arguments are applied after the positional source.

Method signatures
python
dict.update([other], **kwargs)
# other: a mapping, or an iterable of (key, value) pairs
# returns: None (the dict is changed in place)

Parameters

ParameterDescription
otherOptional, positional only. A dict or other mapping, or an iterable whose items are 2-item pairs such as tuples.
**kwargsOptional keyword arguments. Each name becomes a string key; they are applied after other.

Return Value

Return ValueDescription
NoneAlways None. The dict itself holds the merged result.

Python Examples

Example 1 — Apply User Overrides to Default Settings

Merge an overrides dict into the defaults, then adjust two more values with keyword arguments.

python
settings = {"debug": False, "port": 8080, "host": "localhost"}
overrides = {"port": 9000, "workers": 4}

result = settings.update(overrides)
print(result)
print(settings)

settings.update(debug=True, host="0.0.0.0")
print(settings)
print(overrides)

How It Works

  1. No return value. update() works in place, so result is None.
  2. Override wins. port keeps its second position but now holds 9000, and the brand-new workers key is appended at the end.
  3. Keyword form. debug=True, host="0.0.0.0" become the string keys 'debug' and 'host', replacing their old values.
  4. Source untouched. The overrides dict is only read, so it prints exactly as it was created.

Example 2 — Restock a Bakery from Pairs, zip(), and Keywords

Feed update() a list of tuples, a zip() object, and a keyword, then pass a malformed item on purpose.

python
inventory = {"bagels": 10}

inventory.update([("muffins", 4), ("scones", 7)])
inventory.update(zip(["croissants", "bagels"], [12, 3]))
inventory.update(donuts=6)
print(inventory)

try:
    inventory.update(["cookies"])
except ValueError:
    print("each item must be a key/value pair")
print(len(inventory))

How It Works

  1. List of tuples. Each 2-tuple supplies one key and one value, adding muffins and scones.
  2. zip() pairs. zip() produces the pairs ("croissants", 12) and ("bagels", 3); the second one overwrites the bagel count in place.
  3. Bad item. The string "cookies" is unpacked character by character, giving 7 elements instead of 2, so Python raises ValueError.
  4. Nothing half-added. The failing item was the first one, so the dict still has exactly five keys.

Example 3 — Merge Theme Colors with | and |=

Build a new merged dict without touching the original, then update one in place with the operator form.

python
base_theme = {"bg": "white", "fg": "black", "accent": "blue"}
dark = {"bg": "black", "fg": "white"}

merged = base_theme | dark
print(merged)
print(base_theme["bg"])

base_theme |= {"accent": "orange"}
print(base_theme)
print({**dark, "accent": "teal"})

How It Works

  1. New dict. base_theme | dark returns a fresh dict: key order from the left side, values from the right side where both have a key.
  2. Original kept. base_theme["bg"] is still white, because | does not modify either operand.
  3. In-place form. |= behaves like update() and changes base_theme itself.
  4. Older Pythons. Unpacking with {**dark, "accent": "teal"} builds a merged copy on Python 3.5 and later.

Frequently Asked Questions

It always returns None. The dict you called it on is changed in place, so call it on its own line instead of assigning the result.
a.update(b) merges b into a in place. For a new dict use {**a, **b}, or a | b on Python 3.9 and later.
The value from the argument you pass to update(), since it is applied last. Keyword arguments are applied after the positional source.
Yes. Any iterable of 2-item pairs works, such as [("a", 1), ("b", 2)] or a zip() object. An item of the wrong length raises ValueError.
No. Existing keys keep their position and only get a new value. Keys that were not there before are added at the end.

Next: dict.values()

Return a live view of the values of a dict, for sums, counts, and checks.

values() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

10 people found this page helpful