How to Add Items to a Dictionary in Python

Assign a value to a key with square brackets: items["apple"] = 3. Python adds the key if it is new and replaces its value if it already exists. For multiple pairs, use update(); to insert only when a key is missing, use setdefault().

Add or replace one key-value pair

A Python dictionary stores key-value pairs, with each key unique within that dictionary. Start with an empty dictionary using {}, then assign a value by key:

#	Preview	Product	Price
1		The Python Language Reference Manual (Python Manual)	$49.95	Buy on Amazon

settings = {}
settings["theme"] = "dark"
print(settings)  # {'theme': 'dark'}

If you assign to a key that is already present, Python replaces its old value. The official Python 3.14.8 tutorial explains that the old value associated with that key is forgotten.

settings["theme"] = "light"
print(settings["theme"])  # light

Add multiple items with update()

Use update() to add several key-value pairs to an existing dictionary. It changes the dictionary in place, overwrites existing values for keys in the input, and returns None.

#1 Best Overall

The Python Language Reference Manual (Python Manual)

$49.95

Buy on Amazon

settings.update({"theme": "dark", "font_size": 16})

Its input can be a mapping, an iterable of pairs, or keyword arguments when the keys are valid Python identifiers:

settings.update([("theme", "dark"), ("font_size", 16)])
settings.update(theme="dark")

Do not assign the result back to the dictionary: settings = settings.update(...) would set settings to None. The Python built-in types reference documents the accepted inputs and overwrite behavior.

Add a key only if it is missing

Use setdefault(key, default) when an existing value should be preserved. If the key is present, the method returns its current value without changing it. If it is absent, it inserts the default and returns that value.

settings.setdefault("language", "en")

Choose setdefault() when retaining an existing value matters; use square-bracket assignment when replacement is intended.

Merge dictionaries or update one in place

Python 3.9 and later support dictionary merge operators. The | operator creates a new dictionary; the |= operator updates the dictionary on its left. If both dictionaries contain a key, the value from the right-hand dictionary wins.

defaults = {"theme": "light", "font_size": 14}
user_settings = {"theme": "dark"}

combined = defaults | user_settings
# defaults is unchanged; combined has theme "dark"

defaults |= user_settings
# defaults is updated in place

For code that must also run on Python versions before 3.9, use update() to modify a dictionary or copy it first if you need a merged result without changing the original.

Collect several values under one key

A dictionary key can hold a list when you need to group multiple values under it. defaultdict(list) creates an empty list the first time a missing key is accessed, so you can append without checking whether the key exists.

from collections import defaultdict

groups = defaultdict(list)
for category, item in records:
    groups[category].append(item)

See the official collections documentation for defaultdict behavior and grouping examples.

Dictionary keys and missing-key lookups

• Keys must be hashable. Strings and numbers are common choices; tuples work if all their contents are hashable. Lists cannot be keys because they are mutable.
• Reading a missing key with d[key] raises KeyError.
• d.get(key) or d.get(key, fallback) can read a key without raising for a missing key, but get() does not insert anything. Use setdefault() when a missing key should be added.

For more detail on dictionary assignment, key constraints, and lookup behavior, see the Python tutorial’s dictionary section.

Quick Recap

Bestseller No. 1

The Python Language Reference Manual (Python Manual)

$49.95

Choose the operation that matches the result you want

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.