Python Extend Dictionary

Lists have extend(), but dictionaries do not have dict.extend(). That trips many beginners: you are not “appending pairs to the end” of a sequence—you are merging keys into a mapping where each key is unique.

Python dictionaries do not have an extend() method. To extend a dictionary, use update() or the |= operator if you want to modify the existing dictionary. Use the | operator or ** unpacking if you want to create a new merged dictionary.

A dictionary stores key-value pairs in curly braces {} and preserves insertion order in modern Python (for example, list(d) follows insertion order, as the Python tutorial describes). Keys are unique: assigning again replaces the previous value—there are never two entries for the same key.

This page focuses on the question “How do I extend an existing dictionary?” For a wider tour of merge patterns, ChainMap, copies, and related topics, see merge dictionaries in Python. For adding keys in day-to-day code, Python add to dictionary fits closely as well. Background on dict basics lives in the Python dictionary guide.

Tested on: Python 3.13.3; kernel 6.14.0-37-generic.

Can you extend a dictionary in Python?

Yes. “Extending” a dictionary means bringing keys (and their values) from another mapping into an existing dict, or building a larger dict from two or more mappings. There is no extend() name on dict because the data model is not “items in a row” like a list—it is keys pointing to values, and dictionaries are defined as key-value mappings with unique keys.

Why dict has no extend() method

list.extend(iterable) grows the list by appending elements from the iterable in order (see append vs extend in Python lists). A dict has no ordered slot you append into: you insert or overwrite by key. The closest mental model to “extend” is “merge these keys into me” (update, |=) or “give me a new dict that contains both” (|, {**a, **b}). If you need list-like behavior under one key, store a list as the value and call extend on that list.

Extend a dictionary using update()

dict.update() merges another mapping or an iterable of (key, value) pairs into the dictionary in place and returns None. If a key already exists, the incoming value replaces the old one—there is no separate “remove duplicates” step because duplicate keys cannot exist in one dict.

left = {"name": "Ada", "score": 10}
right = {"score": 99, "team": "blue"}
left.update(right)
print(left)

You should see name unchanged, score updated to 99 from right, and team added.

Extend a dictionary using |= operator

The |= augmented assignment operator updates the left-hand dictionary in place. It was added in Python 3.9 together with | (PEP 584). For duplicate keys, the right-hand side wins, same as update().

a = {"x": 1}
b = {"x": 2, "y": 3}
a |= b
print(a)

You should see x equal to 2 and y equal to 3. On Python 3.8 or earlier, use a.update(b) instead—|= is not available.

Merge dictionaries using | operator

The binary | operator builds a new dictionary; neither operand is modified. PEP 584 calls this the merge operator and specifies right-hand wins on key overlap.

first = {"a": 1, "b": 2}
second = {"b": 9, "c": 3}
merged = first | second
print(merged)
print("first unchanged:", first)

You should see merged with b equal to 9, and first still {"a": 1, "b": 2}.

Extend a dictionary using unpacking

Unpacking builds a new dict literal. It works on older Python versions and does not require 3.9’s |. Later unpackings overwrite earlier keys for the same name, same “right wins” idea.

old_a = {"a": 1}
old_b = {"a": 2, "b": 3}
combined = {**old_a, **old_b}
print(combined)

You should see a equal to 2 and b equal to 3.

Add one key-value pair to a dictionary

Use subscript assignment. New keys add a pair; existing keys replace the value.

cfg = {"host": "localhost"}
cfg["port"] = 8080
cfg["host"] = "127.0.0.1"
print(cfg)

You should see host updated and port present.

Extend dictionary with another dictionary

The usual pattern is base.update(extra) when extra is another dict or any mapping. You can also pass keyword arguments to update for string keys that are valid identifiers.

base = {"id": 1}
extra = {"name": "Kim", "id": 2}
base.update(extra)
print(base)

id ends up as 2 because keys from extra overwrite on conflict.

Extend dictionary without changing the original

Use first | second or {**first, **second} so you get a new dict and leave first and second untouched.

original = {"a": 1}
incoming = {"b": 2}
snapshot = original | incoming
print(snapshot)
print("original keys:", list(original))

snapshot should contain both keys; original should still only have a.

What happens when keys already exist?

There is only one value per key. When both sides define the same key, the merge or update picks one value: for d.update(other), d |= other, d | other, and {**a, **b}, the value from the right-hand or later mapping wins (PEP 584 for | and |=). If you need to combine values (for example sum counts or concatenate lists) for the same key, you write explicit logic—plain dict operations never keep two values under one key.

left = {"k": [1]}
right = {"k": [2]}
# normal merge replaces the list, it does not append:
print(left | right)

You should see k mapped to [2], not [1, 2].

update() vs |= vs | vs

Common mistakes when extending dictionaries

• Calling dict.extend()—that API exists on list, not on dict.
• Forgetting that update() and |= change the original dict; assign or copy first if you need the old snapshot.
• Forgetting that d | m returns a new dict; assigning back (d = d | m) is fine, but d | m alone does not update d.
• Expecting duplicate keys to store two values at once—only one value per key survives.
• Using dict(base, **extra) when extra has non-string keys or keys that are not valid keyword names; prefer update, |=, |, or {**base, **extra}.
• Treating dictionary “extend” like list.extend—here you merge by key, not append positions.
• Assuming a shallow merge combines nested dicts field by field; inner dicts are replaced wholesale unless you add custom merging.

Python extend dictionary quick reference table

Summary

You extend a Python dictionary by merging keys: in place with update() or |= (3.9+), or without touching inputs using | (3.9+) or {**a, **b}. There is no dict.extend() because dicts are mappings, not growable sequences. Shared keys always resolve to a single value, with the right-hand side winning in the usual merge forms.

References

• PEP 584 – Union operators for dict
• Built-in types — mapping
• Tutorial — dictionaries