Java HashMap Iteration: Methods and Tradeoffs
Learn practical ways to iterate over a Java HashMap with entrySet, keySet, values, forEach, and streams, plus the performance and concurrency tradeoffs to consider.

When you need to process every entry in a Java HashMap, the iteration strategy you choose affects readability, performance, and even correctness in concurrent scenarios. Java HashMap iteration is a common task, but the API offers several ways to do it, and they are not always interchangeable.
The Core Iteration Options
A HashMap implements the Map interface, which defines three collection views: keySet(), values(), and entrySet(). Each view can be iterated with a for-each loop, an iterator, or a Java 8 stream. Additionally, the forEach method accepts a BiConsumer and is often the most concise option. The choice depends on whether you need keys, values, or both, and whether you need to modify the map during iteration.
Iterating with entrySet() for Key-Value Access
When your logic requires both the key and the value, entrySet() is the most direct approach. Each element is a Map.Entry that exposes getKey() and getValue(). This avoids a separate lookup for each key, which is especially important for large maps.
Map<String, Integer> scores = new HashMap<>();
scores.put("Alice", 92);
scores.put("Bob", 85);
scores.put("Carol", 78);
for (Map.Entry<String, Integer> entry : scores.entrySet()) {
System.out.println(entry.getKey() + " -> " + entry.getValue());
}The loop variable is a Map.Entry reference, and you can read both parts without calling get() on the map. This is the recommended pattern for most iteration tasks because it is both readable and efficient.
Using keySet() and values() When You Need Only One Side
keySet() returns a Set of keys, so it is the view to use when your logic needs only keys. A common but avoidable mistake is to iterate keySet() and call map.get(key) for each key when you also need the value; that performs an extra lookup on every iteration. If you need both keys and values, prefer entrySet(). If you only need values, values() returns a Collection of values directly.
// Keys only
for (String key : scores.keySet()) {
System.out.println("Key: " + key);
}
// Values only
for (Integer value : scores.values()) {
System.out.println("Value: " + value);
}These views are backed by the map. If you modify the map structurally while iterating over one of them, the iteration will generally throw a ConcurrentModificationException unless you remove the current entry through the iterator's own remove() method. For read-only processing, they are perfectly safe.
forEach and Stream Iteration
Java 8 introduced the forEach method and streams for working with maps. The forEach method accepts a BiConsumer and is the most compact syntax for iteration. It also works well with lambda expressions.
scores.forEach((key, value) -> {
System.out.println(key + " -> " + value);
});If you need to filter or transform entries, a stream over entrySet() is more flexible. For example, to collect keys of entries with a value above a threshold:
List<String> highScorers = scores.entrySet().stream()
.filter(entry -> entry.getValue() >= 90)
.map(Map.Entry::getKey)
.collect(Collectors.toList());If you are using Java 16 or later, you can replace .collect(Collectors.toList()) with .toList(). Streams introduce some overhead due to the pipeline machinery, but for typical collection sizes the difference is negligible. Use streams when you need declarative operations like filtering, mapping, or reduction; use forEach when you simply need to perform an action on each entry.
Performance and Ordering Considerations
HashMap does not guarantee any iteration order. You should not rely on insertion order or any other ordering, and the order can change when entries are added or removed. If you need predictable iteration order, use LinkedHashMap, which maintains a doubly-linked list of entries in insertion order (or access order if configured).
From a performance perspective, entrySet() is generally the most efficient when you need both keys and values because it avoids the extra get() lookup that a keySet()-plus-get() approach requires. The values() view is efficient for values alone, but it does not give you access to keys. The forEach method's default implementation iterates over entrySet() internally, so its performance is similar to an explicit entrySet() loop.
Stream-based iteration adds some overhead due to the stream pipeline, but for most applications the difference is not significant. The main cost is the creation of intermediate objects for operations like filter and map. If you are processing millions of entries in a tight loop, a traditional for-each loop over entrySet() is likely the fastest option.
Concurrent Modification and Thread Safety
The iterators returned by HashMap's collection views are fail-fast: if the map is structurally modified after the iterator is created, the iterator throws ConcurrentModificationException. This is a safety mechanism, not a guarantee of consistent behavior in concurrent programs. It is not a reliable way to detect concurrent modification because it is best-effort and can miss changes in some cases.
If you need to iterate over a map while other threads may modify it, use ConcurrentHashMap. Its iterators are weakly consistent: they reflect the state of the map at some point during iteration and do not throw ConcurrentModificationException. However, they also do not guarantee that every update made during iteration will be visible. For example:
Map<String, Integer> concurrentScores = new ConcurrentHashMap<>();
concurrentScores.put("Alice", 92);
for (Map.Entry<String, Integer> entry : concurrentScores.entrySet()) {
// Safe from ConcurrentModificationException
System.out.println(entry.getKey() + " -> " + entry.getValue());
}If you need to remove entries during iteration, use the iterator's remove() method, which is the only safe way to modify the map without throwing an exception. For ConcurrentHashMap, you can also use remove(key, value) or compute methods, but the iterator's remove() is still supported.
Choosing the Right Iteration Strategy
Select the iteration approach based on what you need and the context:
- Use
entrySet()when you need both keys and values. It is the most direct and avoids extra lookups. - Use
keySet()when you only need keys. - Use
values()when you only need values and have no need for keys. - Use
forEachwhen you have a simple action to perform on each entry and want concise syntax. - Use streams when you need to filter, map, or collect entries in a declarative way.
- Use
ConcurrentHashMapand its weakly consistent iterators when the map is shared across threads.
For most applications, a for-each loop over entrySet() is the safest and most readable default. It works in single-threaded code, uses the same iterator infrastructure that supports removal when you need it, and does not depend on Java 8 features. If you are using Java 8 or later, forEach is a clean alternative for simple actions. Streams are best reserved for more complex transformations where the declarative style pays off.
One edge case to keep in mind: if you modify the map's structure inside a stream pipeline (for example, by calling put or remove inside a forEach), you can still trigger a ConcurrentModificationException because the stream is backed by the map's collection view. The same fail-fast behavior applies. For concurrent modifications, always use ConcurrentHashMap or synchronize externally.
Finally, remember that iteration order is not guaranteed for HashMap. If your algorithm depends on a specific order, switch to LinkedHashMap or explicitly sort the entries before processing. The iteration method you choose does not affect order; it only affects how you access the data.
Try matching browser tools
All toolsSmall utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Java guides
All Java guidesJava Final Keyword: Usage and Behavior
How Java's final keyword works for variables, methods, and classes, with practical examples and decision guidance for using it.
Java Final Variable: Syntax, Behavior, and Use Cases
Understand what a final variable in Java means, how initialization works, and when to use it for constants, immutability, and clearer code.
Java Duration vs Period: When to Use Each
java duration vs period: Compare Java Duration and Period to handle time-based and date-based calculations correctly. Learn syntax, conversion, and pitfalls.
Instance vs Static Variables in Java: Key Differences
Understand the difference between instance and static variables in Java, including memory, lifecycle, and when to use each.
More in Java
All Java guidesThe guides filed next to this one in Java, in library order.