Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Dictionary Key Iteration: Methods and Pitfalls

Learn how to iterate over dictionary keys in Python, including direct for loops, .keys(), .items(), insertion-order guarantees, and safe modification during iteration.

~4 min readPython
#dictionary iteration#python loops#dict keys#iteration methods
Diagram showing iteration over a dictionary's keys with a loop and a key-value pair view.

Python offers several ways to iterate over dictionary keys. The most common is a simple for loop, which iterates over keys by default. The main alternatives—.keys(), .items(), and snapshotting with list()—are useful in different situations. This article covers those methods, insertion-order guarantees, and how to modify a dictionary safely during iteration.

Direct Iteration Over a Dictionary

The simplest way to iterate over dictionary keys is to use a for loop directly on the dictionary object. In Python, iterating over a dict yields its keys in the order they were inserted (as of Python 3.7). This is the idiomatic approach and is used most often in real code.

python
user_scores = {"alice": 42, "bob": 17, "carol": 88} for name in user_scores: print(name)

This loop prints alice, bob, carol. The loop variable receives each key in turn. You do not need to call a method to get the keys; the dictionary itself is iterable.

This behavior is intentional and documented. It keeps the syntax concise and avoids the overhead of creating an intermediate list or view object when you only need the keys.

Using .keys() Explicitly

If you want to make it explicit that you are iterating over keys, or if you need a view object that reflects dictionary changes, you can use the .keys() method. This returns a dict_keys view, which is a dynamic view of the dictionary's keys.

python
for name in user_scores.keys(): print(name)

The output is identical to direct iteration. The difference is that .keys() makes the intent clearer to readers who may not know that iterating a dict yields keys. It also allows you to perform set-like operations on the view, such as intersection or union with other key views.

One subtle point: the view is live. If you modify the dictionary after creating the view, the view reflects those changes. However, modifying the dictionary while iterating over the view still raises a RuntimeError because the dictionary size changes during iteration.

Iterating Over Items with .items()

Often you need both the key and the value. In that case, .items() is the appropriate method. It returns a view of key-value tuples, which you can unpack in the loop.

python
for name, score in user_scores.items(): print(f"{name}: {score}")

This is the most efficient way to access both components because it avoids a separate lookup for each key. If you used direct key iteration and then accessed user_scores[name], you would perform an extra hash lookup for every key. Using .items() eliminates that overhead.

When you only need keys, direct iteration is fine. When you need values as well, .items() is the standard choice.

Order Preservation and Python Version

The order in which keys appear has changed across Python versions. Before Python 3.7, dictionaries did not guarantee insertion order, though CPython 3.6 preserved it as an implementation detail. Since Python 3.7, insertion order is a language specification. This means that iterating over keys now yields them in the order they were added, unless the dictionary is created from a mapping that has its own order.

If you are working with a legacy codebase that might run on Python 2 or early Python 3, you cannot rely on order. In those environments, use collections.OrderedDict if order matters. For modern Python, a standard dict is sufficient.

Modifying a Dictionary During Iteration

Attempting to add or remove keys while iterating over the dictionary raises a RuntimeError because the internal size changes. This applies to direct iteration, .keys(), and .items().

python
for name in user_scores: if name == "bob": del user_scores[name] # RuntimeError: dictionary changed size during iteration

To modify a dictionary while iterating, you must iterate over a snapshot. The most common approach is to create a list of keys first:

python
for name in list(user_scores.keys()): if name == "bob": del user_scores[name]

The list() call creates a static copy of the keys, so the iteration is safe. This is a frequent pattern when you need to filter a dictionary in place.

Performance Considerations for Key Iteration

Direct iteration over a dictionary is the simplest and usually the fastest way to access keys because it does not build a list of keys. Calling .keys() also avoids building a list and makes the intent explicit. In practice, any performance difference between these two options is negligible for most applications.

The main performance trap is creating a list of keys when you do not need one. list(user_scores) or list(user_scores.keys()) allocates a new list containing all keys. This is necessary when you need to modify the dictionary during iteration, but wasteful if you are only reading keys. For read-only iteration, prefer direct iteration or .keys().

Another consideration is memory. A list of keys consumes memory proportional to the number of keys. A view or direct iteration does not. In large dictionaries, this can matter, especially in memory-constrained environments.

Choosing the Right Iteration Method

The decision among direct iteration, .keys(), .items(), and list() depends on what you need:

  • Use direct iteration when you only need keys and want the simplest syntax.
  • Use .keys() when you want to make the intent explicit or need set-like operations on the key view.
  • Use .items() when you need both keys and values.
  • Use list(dict) or list(dict.keys()) only when you need to modify the dictionary during iteration or require a static snapshot.

These choices are not about correctness alone; they affect readability and performance. In most code, direct iteration is sufficient and preferred. The other methods exist for specific cases where their behavior is necessary.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.