Python Dictionary: Practical Usage and Performance
Learn how to create, access, and manipulate Python dictionaries, understand their performance characteristics, and avoid common pitfalls in real-world code.

A Python dictionary is a built-in data structure that stores key-value pairs. It is one of the most frequently used tools in Python because it provides fast lookups, readable syntax, and support for any hashable key type. Understanding how dictionaries work internally and where their strengths and limitations lie helps you write code that is both efficient and maintainable.
Creating and Accessing Dictionaries
Dictionaries can be created with curly braces or the dict() constructor. The literal syntax is the most common and often the most readable:
person = {"name": "Ada", "role": "engineer"}
empty = {}
from_pairs = dict([("name", "Ada"), ("role", "engineer")])Accessing a value by key is straightforward with square brackets, but this raises a KeyError if the key is missing. For cases where a missing key should not be an error, the .get() method returns None or a provided default:
role = person["role"]
missing = person.get("department") # None
fallback = person.get("department", "unknown")The .setdefault() method is useful when you want to insert a default value only if the key is absent. This is common when building counts or grouping data:
counts = {}
for word in words:
counts[word] = counts.setdefault(word, 0) + 1Common Operations and Methods
Dictionaries support a rich set of methods for adding, updating, and removing items. The update() method merges another mapping or iterable of key-value pairs into the dictionary, overwriting existing keys:
person.update({"location": "London"})
person.update([("years", 5)])To remove a key, pop() returns the value and removes the key, while del simply removes it. The popitem() method removes and returns the last inserted key-value pair in Python 3.7+ where insertion order is guaranteed.
Membership testing with in is efficient and is the preferred way to check whether a key exists:
if "name" in person:
print(person["name"])Iteration and View Objects
Iterating over a dictionary yields its keys by default. To iterate over values or key-value pairs, use the .values() and .items() methods. These return view objects that reflect changes to the dictionary in real time:
for key in person:
print(key)
for value in person.values():
print(value)
for key, value in person.items():
print(key, value)View objects are not lists, so they cannot be indexed directly. If you need an index, convert them to a list first. This is a common source of confusion for developers coming from other languages.
Performance Characteristics and Memory Behavior
In CPython, which is the standard Python implementation, dictionaries are implemented as hash tables. This gives average-case O(1) time complexity for lookup, insertion, and deletion. The hash of each key determines its storage location, so keys must be hashable. Immutable built-in values such as strings and numbers are hashable; tuples are hashable only when their elements are hashable. Built-in mutable containers such as lists are not.
Because hash tables rely on a good hash function, collisions degrade performance to O(n) in the worst case. CPython's hash function for strings is randomized per process to mitigate denial-of-service attacks, but for most applications the average-case behavior is what matters.
Memory usage is higher than an equivalent list of tuples because the hash table allocates extra space to keep load factors low. When a dictionary grows, it may need to rehash all keys, which is an O(n) operation. This resizing cost is amortized over the insertions, so in ordinary code it is rarely a problem. dict.fromkeys() and dictionary comprehensions can make construction clearer, but they still insert each key; they do not avoid the ordinary cost of building the dictionary.
When to Use a Dictionary Instead of a List or Set
Choosing between a dictionary, list, and set depends on the operation you need to perform. A dictionary is the right choice when you need to associate a value with a unique key. A set is appropriate when you only need to track membership without an associated value. A list is better when order and duplicates matter.
The following table summarizes the decision criteria:
| Need | Recommended Structure |
|---|---|
| Map keys to values | Dictionary |
| Track unique items | Set |
| Preserve order and duplicates | List |
For example, if you need to count occurrences of words, a dictionary mapping each word to its count is natural. If you only need to know which words appear, a set is sufficient. If you need to process words in the order they appear, a list preserves that order.
Common Pitfalls and Edge Cases
One frequent mistake is using a mutable default value in a function signature. This is not specific to dictionaries but appears often when a dictionary is used as a default argument:
def add_item(item, storage={}):
storage[item] = True
return storageThe default dictionary is created once and shared across all calls. The correct pattern is to use None and create a new dictionary inside the function.
Another pitfall is assuming dictionaries preserve insertion order in older Python versions. While this is guaranteed from Python 3.7 onward, code that relies on order should not be run on older interpreters without checking the version.
When copying a dictionary, a shallow copy with dict.copy() or copy.copy() shares the same value objects. If the values are mutable, changes to those values will affect both dictionaries. Use copy.deepcopy() when you need independent nested structures.
Finally, be aware that dictionary keys must be hashable. If you need to use a list as a key, convert it to a tuple first. This is a common workaround that preserves the logical content while making the key immutable.
Advanced Usage: Dictionary Comprehensions and Merging
Dictionary comprehensions provide a concise way to build dictionaries from iterables. For example, creating a mapping from numbers to their squares:
squares = {x: x**2 for x in range(10)}Merging two dictionaries can be done with the {**a, **b} syntax or the | operator in Python 3.9+. The | operator is more readable and also supports in-place merging with |=:
merged = {**defaults, **user_settings}
merged = defaults | user_settingsThese features make dictionary manipulation more expressive and reduce the need for explicit loops. If you need a dictionary, a dictionary comprehension builds it directly. A generator expression produces values lazily and can be more memory-efficient when you consume items one at a time, but it does not create a dictionary.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.