Learn

Short lessons with real code you can edit and run on the page.

Dictionaries in Python

Lesson 20 Python 3.14 Runs in your browser
In short

A dictionary stores key-value pairs, so you look values up by a name instead of a position. You write the pairs in curly braces, as in ages = {"Ada": 36}, read a value with ages["Ada"] or ages.get("Ada"), and add a pair by assigning to a new key.

Key facts

  • ages = {"Ada": 36} maps the key "Ada" to the value 36. Keys are unique.
  • ages["Ada"] returns the value, and a missing key raises KeyError. ages.get("Bob") returns None instead.
  • ages["Bob"] = 28 adds a new pair or replaces the value of an existing key.
  • A for loop over a dictionary gives its keys. ages.items() gives each key with its value.
  • Dictionaries keep the order the keys were added in. A list, a dictionary or a set can't be a key, because its contents can change.

What is a dictionary in Python?

A dictionary holds keys paired with values, and you find each value by its key, not by a position. You write the pairs inside curly braces, with a colon between each key and its value, and the dict type keeps them in the order you added them.

A dictionary is the natural type for a record with named fields, a lookup table, or a count of how often things occur.

Python
ages = {"Ada": 36, "Bob": 28}
print(ages)
print(type(ages))
print(len(ages))
print(ages["Ada"])
Output
{'Ada': 36, 'Bob': 28}
<class 'dict'>
2
36

ages["Ada"] asks for the value stored under the key "Ada", the way fruits[0] asks a list for the item at position 0. Keys are unique, so a dictionary holds one value per key, and len() counts the pairs. Python programmers often call a dictionary a dict, after the name of its type.

How do I create a dictionary in Python?

Write key: value pairs inside curly braces, separated by commas. Empty braces make an empty dictionary, and dict(name="Ada", age=36) builds one from name=value arguments.

Keys are usually strings, numbers or tuples, and can't be lists, dictionaries or sets. Values can be anything, including lists and other dictionaries.

Python
empty = {}
print(empty)
person = dict(name="Ada", age=36)
print(person)
mixed = {1: "one", "two": 2, (3, 4): "point"}
print(mixed)
student = {"name": "Ada", "grades": [90, 85]}
print(student["grades"][0])
Output
{}
{'name': 'Ada', 'age': 36}
{1: 'one', 'two': 2, (3, 4): 'point'}
90

The keys in mixed are a number, a string and a tuple, and each one works because none of them can change. A tuple works as a key only if it holds no lists, dictionaries or sets. The last line reads a value that is a list and then indexes into it, one pair of brackets per step.

A list can't be a key, because its contents could change after the dictionary has filed it. Python calls a value hashable when it can turn the value into a fixed number, which works for any value that can't change. The error for a list key calls the list unhashable.

How do I get a value from a dictionary?

Put the key in square brackets, or call get(). Square brackets raise KeyError when the key is missing, and get() returns None instead, or a default value you pass as its second argument. The in operator tests whether a key exists.

Python
ages = {"Ada": 36, "Bob": 28}
print(ages["Bob"])
print(ages.get("Bob"))
print(ages.get("Cy"))
print(ages.get("Cy", 0))
print("Ada" in ages)
print("Cy" in ages)
Output
28
28
None
0
True
False

Use the brackets when the key must exist and a missing one is a bug worth stopping for. Use get() when a missing key is normal, such as counting words you haven't seen before. in looks at keys only, so 36 in ages is False even though 36 is a value.

Reading a Python dictionary with brackets and get()
FormWhat you getUse it when
d[key]The value, or KeyError when the key is missingThe key must exist
d.get(key)The value, or None when the key is missingA missing key is normal
d.get(key, default)The value, or the default when the key is missingYou need a stand-in value, such as 0 for a count

A lookup with a default can also replace an if and elif chain that maps each case to one value. This is the dictionary lookup the match statement lesson mentioned.

Python
messages = {200: "OK", 404: "Not found"}
print(messages.get(404, "Unknown status"))
print(messages.get(418, "Unknown status"))
Output
Not found
Unknown status

How do I add a key or change its value in a dictionary?

Assign a value to the key in square brackets. When the key is new, the assignment adds the pair at the end. When the key exists, the assignment replaces its value, and the pair keeps its place. update() does the same for several pairs at once.

Python
ages = {"Ada": 36, "Bob": 28}
ages["Cy"] = 41
print(ages)
ages["Bob"] = 29
print(ages)
ages.update({"Dee": 25, "Ada": 37})
print(ages)
print(len(ages))
Output
{'Ada': 36, 'Bob': 28, 'Cy': 41}
{'Ada': 36, 'Bob': 29, 'Cy': 41}
{'Ada': 37, 'Bob': 29, 'Cy': 41, 'Dee': 25}
4

There is no append() on a dictionary, because you add a pair by assigning to its key. The update() call added "Dee" and changed "Ada" in one step, and the length rose by one, since "Ada" was already there.

How do I remove a key from a dictionary?

Use del with the key in brackets, or call pop() with the key. pop() returns the value it removed, and a second argument makes it return that default instead of raising KeyError for a missing key.

Python
ages = {"Ada": 36, "Bob": 28, "Cy": 41}
del ages["Bob"]
print(ages)
removed = ages.pop("Cy")
print(removed)
print(ages)
print(ages.pop("Zed", "nobody"))
Output
{'Ada': 36, 'Cy': 41}
41
{'Ada': 36}
nobody

clear() empties the whole dictionary, and popitem() removes and returns the pair that was added last.

How do I loop through a dictionary in Python?

A for loop over a dictionary gives you its keys, one per pass. Call values() to loop over the values instead, and items() to get each key and value together as a pair you can unpack into two names.

Python
ages = {"Ada": 36, "Bob": 28}
for name in ages:
    print(name)
for age in ages.values():
    print(age)
for name, age in ages.items():
    print(name, "is", age)
print(ages.keys())
Output
Ada
Bob
36
28
Ada is 36
Bob is 28
dict_keys(['Ada', 'Bob'])

The items() loop is the one you will use most, because you usually need each key's value too. The last line shows what keys() returns, a view printed as dict_keys([...]). A view is a live window onto the dictionary's keys rather than a copy, and list(ages.keys()) turns it into a list.

Every loop over a dictionary runs in the order the keys were added, which Python has guaranteed since version 3.7.

Counting is the classic dictionary loop, and get() with a default of 0 handles the first time a word shows up.

Python
words = ["red", "blue", "red", "green", "red"]
counts = {}
for word in words:
    counts[word] = counts.get(word, 0) + 1
print(counts)
Output
{'red': 3, 'blue': 1, 'green': 1}

Which dictionary methods does Python have?

Python dictionaries have eleven methods, and the table lists all of them. len() counts the pairs. sorted(ages) returns the keys in sorted order, because sorted() loops over the dictionary, and looping over a dictionary gives its keys.

Python dictionary methods
MethodWhat it does
clear()Removes every pair
copy()Returns a new dictionary with the same pairs
fromkeys(keys, value)Builds a dictionary with each key set to the same value, None by default
get(key, default)Returns the value for key, or the default when the key is missing, and the default is None unless you pass one
items()Returns the pairs as (key, value) tuples for looping
keys()Returns the keys for looping
pop(key, default)Removes key and returns its value. For a missing key it returns the default, or raises KeyError when no default was passed
popitem()Removes and returns the pair added last
setdefault(key, default)Returns the value for key, first adding the key with the default when it is missing
update(other)Adds or replaces pairs from another dictionary, a list of (key, value) pairs, or name=value arguments
values()Returns the values for looping

A dictionary comprehension, {n: n * n for n in range(4)}, builds a dictionary the way a list comprehension builds a list, with a key and a value in the expression.

What is the difference between a list and a dictionary?

A list stores items by position, and a dictionary stores values by key. Use a list when the order is the point or the items have no natural name, and a dictionary when each value has a name you will look it up by.

Python list compared with dictionary
TypeWritten asRead byUse it when
ListSquare brackets, ["Ada", "Bob"]Position, names[0]The values are an ordered sequence of similar items
DictionaryCurly braces, {"Ada": 36}Key, ages["Ada"]Each value has a name, as in records, lookup tables and counts

Finding a key in a dictionary stays fast however many pairs it holds, while finding a value in a list means checking the items one by one. That is why a dictionary is the tool for lookups, and a set, which the sets lesson covers next, gives the same fast test without the values.

What is a nested dictionary in Python?

A nested dictionary is a dictionary whose values are dictionaries. One pair of brackets picks the inner dictionary and a second pair picks a value inside it, so people["ada"]["city"] reads the city of the record filed under "ada".

Python
people = {
    "ada": {"age": 36, "city": "London"},
    "bob": {"age": 28, "city": "Paris"},
}
print(people["ada"]["city"])
people["bob"]["age"] = 29
print(people["bob"])
for key, info in people.items():
    print(key, info["age"])
Output
London
{'age': 29, 'city': 'Paris'}
ada 36
bob 29

Data from web APIs, the services that programs ask for data over the internet, often arrives in this shape. Most of them send JSON, a text format whose objects and arrays Python's json module turns into dictionaries and lists.

The JSON to Python converter shows the Python code for any JSON you paste in, and the JSON lesson covers reading JSON in code.

Common mistakes with dictionaries in Python

Each of these four mistakes with dictionaries usually stops the program with a message that names the problem.

  • KeyError: 'Bob'. The key isn't in the dictionary. Check with in, or read with get() and a default.
  • TypeError: cannot use 'list' as a dict key (unhashable type: 'list'). A list was used as a key, and a list can change, so it isn't hashable. Use a tuple or a string.
  • ValueError: too many values to unpack (expected 2). The loop was written as for name, age in ages: without items(), so each pass received only a key and tried to split it in two. A key that happens to be two characters long even splits silently into its letters. Add .items().
  • AttributeError: 'dict' object has no attribute 'append'. A dictionary has no append(). Assign to a new key instead.

Run the three broken programs to see the messages, then fix them in the editor.

Python
ages = {"Ada": 36}
print(ages["Bob"])
Output
Traceback (most recent call last):
  File "main.py", line 2, in <module>
    print(ages["Bob"])
          ~~~~^^^^^^^
KeyError: 'Bob'
Python
prices = {[1, 2]: "pair"}
print(prices)
Output
Traceback (most recent call last):
  File "main.py", line 1, in <module>
    prices = {[1, 2]: "pair"}
             ^^^^^^^^^^^^^^^^
TypeError: cannot use 'list' as a dict key (unhashable type: 'list')
Python
ages = {"Ada": 36, "Bob": 28}
for name, age in ages:
    print(name, age)
Output
Traceback (most recent call last):
  File "main.py", line 2, in <module>
    for name, age in ages:
        ^^^^^^^^^
ValueError: too many values to unpack (expected 2)

Exercise

Add "Grace" with the age 45, change the age of "Linus" to 29, and keep the loop, so the program prints Ada is 36, Linus is 29 and Grace is 45 on three lines. The starter prints the two people already in the dictionary.

Python
ages = {"Ada": 36, "Linus": 28}
for name, age in ages.items():
    print(name, "is", age)
Output
Show the solution
ages = {"Ada": 36, "Linus": 28}
ages["Grace"] = 45
ages["Linus"] = 29
for name, age in ages.items():
    print(name, "is", age)

Quiz

This quiz has 5 questions. Pick an answer to see why it is right or wrong.

  1. 1What does this program print?

    d = {"a": 1}
    print(d.get("b"))
  2. 2What happens when a program runs print(d["b"]) and "b" is not a key in d?

  3. 3What does this program print?

    d = {"x": 1, "y": 2}
    for k in d:
        print(k)
  4. 4Which expression creates an empty dictionary?

  5. 5What does this program print?

    d = {"a": 1}
    d["a"] = 5
    print(d, len(d))

Frequently asked questions

What is a dictionary in Python?
A dictionary is a collection of key-value pairs written in curly braces, such as {'Ada': 36}. You look a value up by its key instead of a position, which makes it the type for named data such as a record or a lookup table.
How do I merge two dictionaries in Python?
Call update() to copy the pairs of one dictionary into another, or write a | b to build a new merged dictionary, which works in Python 3.9 and later. When both have the same key, the value from the dictionary passed to update(), or from b in a | b, wins.
How do I check if a key exists in a dictionary?
Use the in operator, as in 'Ada' in ages, which gives True or False. It checks keys only, so to test for a value use value in ages.values().
What is the difference between d[key] and d.get(key)?
d[key] returns the value or raises KeyError when the key is missing. d.get(key) returns None instead, and d.get(key, default) returns the default you choose, so use get() when a key might be absent.
Can a list be a dictionary key?
No. A list's contents can change, so Python can't use it as a key and raises a TypeError. Strings, numbers and tuples work as keys, as long as a tuple holds no lists, dictionaries or sets.
Are Python dictionaries ordered?
Yes. Since Python 3.7 a dictionary keeps its keys in the order they were added, and looping or printing shows that order. Pages that call dictionaries unordered usually describe Python 3.6 or earlier, before the order was guaranteed.
How do I loop through keys and values at the same time?
Loop over ages.items() with two names, as in for name, age in ages.items(). Looping over the dictionary itself gives only the keys, and values() gives only the values.