Python Dictionary `update()` Method

The update() method changes a dictionary by adding new key-value pairs or replacing existing values.

Use it when you want to modify an existing dictionary instead of creating a new one.

Quick example

person = {"name": "Ana", "age": 20}
person.update({"age": 21, "city": "Lima"})
print(person)
# {'name': 'Ana', 'age': 21, 'city': 'Lima'}

Use update() to add new keys or overwrite existing keys from another dictionary or iterable of key-value pairs.

What `update()` does

update() modifies the original dictionary in place.

It can do two main things:

Add new key-value pairs
Replace values for keys that already exist

Important things to know:

It changes the dictionary directly
It does not sort the dictionary
It returns None
You should not assign its result to a new variable

Example:

student = {"name": "Mira", "grade": "B"}
student.update({"grade": "A", "city": "Quito"})
print(student)

Output:

{'name': 'Mira', 'grade': 'A', 'city': 'Quito'}

If you are new to dictionaries, see how to create a dictionary in Python.

Basic syntax

The basic form is:

dictionary.update(other)

other can be:

Another dictionary
An iterable of key-value pairs
Keyword arguments

You can also use:

dictionary.update(name="Sam")

If the same key appears more than once, the last value wins.

Example:

data = {"a": 1}
data.update({"a": 10})
print(data)

Output:

{'a': 10}

Using `update()` with another dictionary

This is the most common use of update().

It is useful when:

Merging small dictionaries
Adding extra settings
Updating stored data

Example:

settings = {"theme": "light", "font_size": 12}
new_settings = {"font_size": 14, "language": "en"}

settings.update(new_settings)
print(settings)

Output:

{'theme': 'light', 'font_size': 14, 'language': 'en'}

What happened here:

font_size already existed, so its value was replaced
language did not exist, so it was added

If you want a task-focused guide, see how to merge dictionaries in Python.

Using `update()` with key-value pairs

update() also works with iterables that contain pairs.

For example, you can pass a list of tuples:

scores = {"math": 90}
pairs = [("science", 85), ("english", 88)]

scores.update(pairs)
print(scores)

Output:

{'math': 90, 'science': 85, 'english': 88}

Each item must contain exactly two values:

The key
The value

Bad structure will raise an error.

Example of incorrect data:

data = {"a": 1}
bad_pairs = [("b", 2, 3)]

data.update(bad_pairs)

This causes an error because each item must be a pair.

This form is useful when you have simple data that needs to become dictionary entries.

Using keyword arguments

You can also pass key-value pairs as keyword arguments:

user = {"name": "Leo"}
user.update(age=25, city="Madrid")
print(user)

Output:

{'name': 'Leo', 'age': 25, 'city': 'Madrid'}

This is convenient for simple string keys.

But there is one limit: keys must be valid Python identifiers.

These work:

age
city
first_name

These do not work as keyword arguments:

"first name"
"user-id"

For keys like that, use a dictionary instead:

user = {}
user.update({"first name": "Leo", "user-id": 1001})
print(user)

Return value

update() returns None.

This is one of the most common beginner mistakes.

Incorrect:

person = {"name": "Ana"}
result = person.update({"age": 20})

print(result)
print(person)

Output:

None
{'name': 'Ana', 'age': 20}

Correct:

person = {"name": "Ana"}
person.update({"age": 20})

print(person)

Output:

{'name': 'Ana', 'age': 20}

If you only want to add or change one key, see how to add a key to a dictionary in Python.

When to use `update()`

Use update() when:

You want to modify an existing dictionary
You want to add several keys at once
You want to merge settings or user data
Overwriting old values is acceptable

If you want to keep the original dictionary unchanged, make a copy first:

original = {"name": "Ana", "age": 20}
updated = original.copy()

updated.update({"age": 21, "city": "Lima"})

print(original)
print(updated)

Output:

{'name': 'Ana', 'age': 20}
{'name': 'Ana', 'age': 21, 'city': 'Lima'}

After updating a dictionary, you may also want to learn how to access values in a dictionary in Python.

Common mistakes

Here are the most common problems beginners run into with update():

Assigning the result of update() to a variable and getting None
Expecting update() to return a new dictionary
Passing items that are not key-value pairs
Using keyword arguments for keys that are not valid identifiers
Overwriting existing values by mistake

Useful debugging checks:

print(my_dict)
print(type(data))
print(list(data))
print(my_dict.get('key'))
help(dict.update)

These can help you check:

What your dictionary currently contains
What type of data you are passing to update()
Whether your input really contains pairs
Whether a key exists
The built-in method help text

If you are trying to read a missing key after updating, you may also run into KeyError in Python: causes and fixes.

FAQ

Does `update()` return a new dictionary?

No. It changes the original dictionary and returns None.

Does `update()` overwrite existing keys?

Yes. If a key already exists, its value is replaced.

Can `update()` add new keys?

Yes. Missing keys are added to the dictionary.

Can I use `update()` with a list?

Yes, if the list contains key-value pairs like [('a', 1), ('b', 2)].

What is the difference between `update()` and assigning one key?

Single assignment changes one key. update() can change many keys at once.

Python Dictionary update() Method

Python Dictionary `update()` Method