How Do Dictionaries Work in Python?

A dictionary maps keys to values. It is created with a literal, and the usual operations are assignment, lookup, deletion and membership.

user = {"name": "Ada", "role": "engineer", "active": True}

print(user["name"])            # Ada
print(user.get("role"))        # engineer
print(len(user))                # 3

user["team"] = "platform"     # add a new key
user["role"] = "lead"         # update an existing one
print(user["role"])            # lead

del user["active"]             # remove a key
print("active" in user)         # False
print(sorted(user.keys()))       # ['name', 'role', 'team']

Assignment with square brackets both adds and updates — if the key is new it is created, if it already exists the value is replaced. Deleting a key that does not exist raises a KeyError, whereas the in operator is always safe and is the right way to test for presence.

Two things about the dictionary itself are worth stating. The keys must be hashable, so strings, numbers and tuples of hashable values work, but a list cannot be a key. And the dictionary preserves insertion order, which is why sorted(user.keys()) is needed if you want alphabetical order rather than the order the keys were added.

The get method is the safe alternative to square-bracket access, and it returns a default instead of raising when the key is missing. That single difference is the subject of its own question, but it is worth mentioning here as the first thing to reach for when you are not certain a key exists.

Direct access to a missing key raises a KeyError, and there are three ways to handle that.

scores = {"ada": 99}

try:
    scores["grace"]
except KeyError as err:
    print("KeyError:", err)

print(scores.get("grace"))              # None
print(scores.get("grace", 0))           # 0 - your own default
print(scores.setdefault("grace", 87))   # 87 - and it is stored
print(scores)                           # {'ada': 99, 'grace': 87}

# setdefault does not overwrite an existing key
print(scores.setdefault("ada", 0))      # 99

get returns None when the key is missing unless you pass a default, and it never raises. That makes it the right tool for optional values.

setdefault does two things at once: it returns the current value if the key exists, and otherwise it inserts the default you supply and returns that. In the script it inserted grace with 87, so the dictionary now has two entries and a second call for ada returned 99 rather than replacing it.

Which to use depends on whether a missing key is a normal situation or a bug. If it is normal, get with a sensible default is clearest. If a missing key means something is wrong — a configuration value that must be present — then raising is correct, and the KeyError with the missing key name is a perfectly good error message.

One more option that is worth knowing: the membership test. Because the in operator never raises, the pattern if key in data: value = data[key] is safe, but it looks up the key twice. get avoids that and is usually the better shape.

A Python dictionary is a hash table. The key is passed to the hash function, which produces an integer, and that integer decides which bucket the entry lives in. To look up a key, the same hash is computed and the relevant bucket is examined directly, rather than scanning every entry.

That is why lookups are O(1) on average, while searching a list is O(n). With a million entries, a list lookup can mean a million comparisons in the worst case, while a dictionary lookup examines a handful of buckets. The same advantage applies to membership tests and to set operations, where the in operator on a set is constant time rather than linear.

Two consequences follow from the hashing. First, keys must be hashable, so the dictionary key type has to implement __hash__ and __eq__ consistently. Strings, numbers and tuples of hashables all work; lists and dicts do not, because their contents can change and the hash would become invalid.

Second, dictionaries preserve insertion order, since Python 3.7. That is a language guarantee now, not just an implementation detail, and it means you can rely on the order of keys, values and items when you iterate. It also means the ordering is a convenience rather than a contract you should design around — if you need a specific order, ask for it with sorted.

The performance caveat worth knowing is that the O(1) is an average, not a guarantee. Hash collisions are possible, and Python handles them by probing other buckets, so a pathological set of keys can degrade the lookup. That is why hash-randomised types such as str and bytes exist — they randomise the seed per process so an attacker cannot deliberately construct colliding keys.