The three ways to add to a dictionary
You add items to a Python dictionary using square brackets with the key name, then assign a value. If the key already exists, this overwrites the old value. If the key is new, Python creates it.
The simplest method is direct assignment: dictionary_name[key] = value. For example, if you have a dictionary called person and you write person["age"] = 30, Python adds the key "age" with the value 30 to that dictionary.
The other two methods are the update() method, which adds multiple items at once, and the setdefault() method, which adds a key only if it does not already exist. Each serves a different situation.
Key Takeaways
- Direct assignment with square brackets is the most common way to add a single item: my_dict[key] = value.
- The update() method adds multiple items in one line: my_dict.update({"key1": value1, "key2": value2}).
- Use setdefault() when you want to add a key only if it does not already exist in the dictionary.
- Square bracket assignment overwrites any existing value for that key, while setdefault() leaves existing values unchanged.
Adding a single item with square brackets
Direct assignment is the method you will use most often. Write the dictionary name, then square brackets with the key inside, then an equals sign, then the value you want to store.
Here is a concrete example:
person = {"name": "Alice", "city": "Portland"} person["age"] = 30 print(person)
After running this code, person now contains {"name": "Alice", "city": "Portland", "age": 30}. The new key-value pair is added to the existing dictionary.
If you use this method on a key that already exists, the old value is replaced. If you write person["age"] = 31, the age changes from 30 to 31. This is useful when you need to update information, but it means you cannot accidentally preserve an old value this way.
Adding multiple items at once with update()
When you need to add several items to a dictionary in one operation, the update() method is faster and cleaner than writing multiple assignment lines.
Pass update() a dictionary containing the new key-value pairs:
person = {"name": "Alice"} person.update({"age": 30, "city": "Portland", "job": "Engineer"}) print(person)
The result is {"name": "Alice", "age": 30, "city": "Portland", "job": "Engineer"}. All three new items are added in a single line.
Like direct assignment, update() overwrites any keys that already exist. If person already had a "city" key, the new value would replace it. You can also pass update() a list of tuples or keyword arguments instead of a dictionary, though the dictionary syntax is most readable.
Adding a key only if it does not exist with setdefault()
The setdefault() method adds a key-value pair, but only if that key is not already in the dictionary. If the key exists, setdefault() does nothing and returns the existing value.
Here is how it works:
person = {"name": "Alice", "age": 30} person.setdefault("age", 25) print(person)
The output is still {"name": "Alice", "age": 30}. Because "age" already exists with the value 30, setdefault() does not change it, even though you passed 25 as the default value.
Now add a key that does not exist:
person.setdefault("city", "Portland") print(person)
Now person is {"name": "Alice", "age": 30, "city": "Portland"}. Since "city" was not in the dictionary, setdefault() added it with the value "Portland". This method is useful when you want to set a default value for a key without overwriting data that might already be there.
Choosing between assignment, update(), and setdefault()
Use direct assignment when you are adding or changing a single item and you want to overwrite any existing value. This is the most common case.
Use update() when you have multiple items to add at once, or when you are merging two dictionaries together. It is cleaner and faster than writing separate assignment statements.
Use setdefault() when you want to add a key only if it does not already exist — for example, when you are building a dictionary from user input and you want to preserve any values that were set earlier. This prevents accidental overwrites.
Common mistakes when adding to dictionaries
The most frequent error is forgetting the square brackets. Writing person.age = 30 looks like it should work, but Python treats that as trying to add an attribute to the dictionary object itself, not as a key-value pair inside the dictionary. Always use square brackets: person["age"] = 30.
Another mistake is using a list or dictionary as a key. Keys must be immutable — meaning they cannot be changed after creation. Strings, numbers, and tuples work as keys. Lists and dictionaries do not, and Python will raise a TypeError if you try.
When using update(), remember to pass a dictionary (with curly braces) or another iterable of key-value pairs. Writing person.update("age", 30) will fail because that is not the right syntax. The correct form is person.update({"age": 30}).
Frequently Asked Questions
Can I add a key with a space or special character in it?
Yes. Keys are just strings, so person["first name"] = "Alice" works fine. You cannot access it with dot notation like person.first name, but square bracket access works: person["first name"] returns "Alice".
What happens if I add the same key twice?
The second assignment overwrites the first. If you write person["age"] = 30 and then person["age"] = 31, the dictionary only stores 31. There is no error — Python simply replaces the old value.
Can I add a key with a number as the key instead of a string?
Yes. Numbers work as dictionary keys: scores = {1: "first", 2: "second"} is valid. You access them the same way: scores[1] returns "first". Just remember that scores[1] and scores["1"] are different keys.
Does update() create a new dictionary or change the existing one?
It changes the existing dictionary in place. After you call person.update({"age": 30}), the person dictionary itself is modified. You do not get a new dictionary back.