Understanding HashMap Initial Capacity and Proper Usage in Java

Preface

Although I have been writing blogs for a long time, I rarely discuss HashMap. This is because HashMap is a staple topic for Java interviews and many readers feel they have seen it enough, so I have not written much about it.

Previously I prepared a flowchart for HashMap's put process, which already covers most core points.

I decided to write this article after noticing many legacy projects in my company where developers misuse HashMap capacity settings.

The article will cover:

Incorrect ways of specifying initial capacity with examples;

Source‑code walkthrough of how the initial capacity is calculated;

Points where resizing occurs;

Correct usage guidelines that require understanding before applying;

Some miscellaneous discussion.

Main Content

Many people know they can specify a capacity, but some get it right while others do not.

Why Specify Capacity?

As Alibaba's Java development manual states, the core reason is to avoid repeated resizing as the map grows, which hurts performance.

Common wrong usages (the performance impact is small but still undesirable) include:

Wrong Example ①

When paginating data (fixed at 15 items per page) and converting the result to a Map, developers write:

Map
map = new HashMap<>(15);

or

Map
map = new HashMap<>(userPageList.size());

Wrong Example ②

When there are four different types that need to be stored in a map, developers write:

Map
map = new HashMap<>(4);

Wrong Example ③

When a method receives a map that should hold two parameters, developers write:

Map
map = new HashMap<>(2);

All these examples misuse the capacity value.

By default, HashMap is created with an internal capacity of 16, and the load factor is 0.75, so the resize threshold is 12 (16 × 0.75).

If we intend to store four elements and set the initial capacity to 4, the actual resize threshold becomes 4 × 0.75 = 3. When the fourth element is inserted, the map resizes, defeating the purpose of specifying capacity.

Demonstration with Reflection

Using reflection we can access the internal capacity field and print its value after each insertion:

public static void main(String[] args) throws NoSuchMethodException, InvocationTargetException, IllegalAccessException {
    Map
map = new HashMap<>(4);
    Class
mapType = map.getClass();
    Method capacity = mapType.getDeclaredMethod("capacity");
    capacity.setAccessible(true);

    map.put("1", "first element");
    System.out.println("capacity : " + capacity.invoke(map) + "    size : " + map.size());
    map.put("2", "second element");
    System.out.println("capacity : " + capacity.invoke(map) + "    size : " + map.size());
    map.put("3", "third element");
    System.out.println("capacity : " + capacity.invoke(map) + "    size : " + map.size());
    map.put("4", "fourth element");
    System.out.println("capacity : " + capacity.invoke(map) + "    size : " + map.size());
}

The output shows that after inserting the third element the capacity is still 4, but inserting the fourth element triggers a resize and the capacity becomes 8.

So what initial capacity should we pass?

4 / 0.75 + 1 ≈ 6.33

Choosing 6 or 7 both result in an internal capacity of 8, and no further resizing occurs for four elements.

HashMap always rounds the requested capacity up to the next power of two:

Values 5‑8 become internal capacity 8;

Values 9‑16 become internal capacity 16.

In summary, specifying the initial capacity is a trade‑off between memory usage and performance. When writing time‑critical tasks or running on memory‑constrained services, you should carefully calculate the needed capacity to avoid unnecessary rehashing.

Source: blog.csdn.net