1. Overview

In this tutorial, we're going to explore different ways to compare two HashMaps in Java.

We'll discuss multiple ways to check if two HashMaps are similar. We'll also use Java 8 Stream API and Guava to get the detailed differences between different HashMaps.

2. Using Map.equals()

First, we'll use Map.equals() to check if two HashMaps have the same entries:

public void whenCompareTwoHashMapsUsingEquals_thenSuccess() {
    Map<String, String> asiaCapital1 = new HashMap<String, String>();
    asiaCapital1.put("Japan", "Tokyo");
    asiaCapital1.put("South Korea", "Seoul");

    Map<String, String> asiaCapital2 = new HashMap<String, String>();
    asiaCapital2.put("South Korea", "Seoul");
    asiaCapital2.put("Japan", "Tokyo");

    Map<String, String> asiaCapital3 = new HashMap<String, String>();
    asiaCapital3.put("Japan", "Tokyo");
    asiaCapital3.put("China", "Beijing");


Here, we're creating three HashMap objects and adding entries. Then we're using Map.equals() to check if two HashMaps have the same entries.

The way that Map.equals() works is by comparing keys and values using the Object.equals() method. This means it only works when both key and value objects implement equals() properly.

For example, Map.equals() doesn't work when the value type is array, as an array's equals() method compares identity and not the contents of the array:

public void whenCompareTwoHashMapsWithArrayValuesUsingEquals_thenFail() {
    Map<String, String[]> asiaCity1 = new HashMap<String, String[]>();
    asiaCity1.put("Japan", new String[] { "Tokyo", "Osaka" });
    asiaCity1.put("South Korea", new String[] { "Seoul", "Busan" });

    Map<String, String[]> asiaCity2 = new HashMap<String, String[]>();
    asiaCity2.put("South Korea", new String[] { "Seoul", "Busan" });
    asiaCity2.put("Japan", new String[] { "Tokyo", "Osaka" });


3. Using the Java Stream API

We can also implement our own method to compare HashMaps using the Java 8 Stream API:

private boolean areEqual(Map<String, String> first, Map<String, String> second) {
    if (first.size() != second.size()) {
        return false;

    return first.entrySet().stream()
      .allMatch(e -> e.getValue().equals(second.get(e.getKey())));

For simplicity, we implemented the areEqual() method that we can now use to compare HashMap<String, String> objects:

public void whenCompareTwoHashMapsUsingStreamAPI_thenSuccess() {
    assertTrue(areEqual(asiaCapital1, asiaCapital2));
    assertFalse(areEqual(asiaCapital1, asiaCapital3));

But we can also customize our own method areEqualWithArrayValue() to handle array values by using Arrays.equals() to compare two arrays:

private boolean areEqualWithArrayValue(Map<String, String[]> first, Map<String, String[]> second) {
    if (first.size() != second.size()) {
        return false;

    return first.entrySet().stream()
      .allMatch(e -> Arrays.equals(e.getValue(), second.get(e.getKey())));

Unlike Map.equals(), our own method will successfully compare HashMaps with array values:

public void whenCompareTwoHashMapsWithArrayValuesUsingStreamAPI_thenSuccess() {
    assertTrue(areEqualWithArrayValue(asiaCity1, asiaCity2)); 
    assertFalse(areEqualWithArrayValue(asiaCity1, asiaCity3));

4. Comparing HashMap Keys and Values

Next, let's see how to compare two HashMap keys and their corresponding values.

4.1. Comparing HashMap Keys

First, we can check if two HashMaps have same keys by just comparing their KeySet():

public void whenCompareTwoHashMapKeys_thenSuccess() {

4.2. Comparing HashMap Values

Next, we'll see how to compare HashMap values one by one.

We'll implement a simple method to check which keys have the same value in both HashMaps using Stream API:

private Map<String, Boolean> areEqualKeyValues(Map<String, String> first, Map<String, String> second) {
    return first.entrySet().stream()
      .collect(Collectors.toMap(e -> e.getKey(), 
        e -> e.getValue().equals(second.get(e.getKey()))));

We can now use areEqualKeyValues() to compare two different HashMaps to see in detail which keys have the same value and which have different values:

public void whenCompareTwoHashMapKeyValuesUsingStreamAPI_thenSuccess() {
    Map<String, String> asiaCapital3 = new HashMap<String, String>();
    asiaCapital3.put("Japan", "Tokyo");
    asiaCapital3.put("South Korea", "Seoul");
    asiaCapital3.put("China", "Beijing");

    Map<String, String> asiaCapital4 = new HashMap<String, String>();
    asiaCapital4.put("South Korea", "Seoul");
    asiaCapital4.put("Japan", "Osaka");
    asiaCapital4.put("China", "Beijing");

    Map<String, Boolean> result = areEqualKeyValues(asiaCapital3, asiaCapital4);

    assertEquals(3, result.size());
    assertThat(result, hasEntry("Japan", false));
    assertThat(result, hasEntry("South Korea", true));
    assertThat(result, hasEntry("China", true));

5. Map Difference Using Guava

Finally, we'll see how to get a detailed difference between two HashMaps using Guava Maps.difference().

This method returns a MapDifference object that has a number of useful methods to analyze the difference between the Maps. Let's have a look at some of these.

5.1. MapDifference.entriesDiffering()

First, we'll obtain common keys that have different values in each HashMap using MapDifference.entriesDiffering():

public void givenDifferentMaps_whenGetDiffUsingGuava_thenSuccess() {
    Map<String, String> asia1 = new HashMap<String, String>();
    asia1.put("Japan", "Tokyo");
    asia1.put("South Korea", "Seoul");
    asia1.put("India", "New Delhi");

    Map<String, String> asia2 = new HashMap<String, String>();
    asia2.put("Japan", "Tokyo");
    asia2.put("China", "Beijing");
    asia2.put("India", "Delhi");

    MapDifference<String, String> diff = Maps.difference(asia1, asia2);
    Map<String, ValueDifference<String>> entriesDiffering = diff.entriesDiffering();

    assertEquals(1, entriesDiffering.size());
    assertThat(entriesDiffering, hasKey("India"));
    assertEquals("New Delhi", entriesDiffering.get("India").leftValue());
    assertEquals("Delhi", entriesDiffering.get("India").rightValue());

The entriesDiffering() method returns a new Map that contains the set of common keys and ValueDifference objects as the set of values.

Each ValueDifference object has a leftValue() and rightValue() methods that return the values in the two Maps respectively.

5.2. MapDifference.entriesOnlyOnRight() and MapDifference.entriesOnlyOnLeft()

Then, we can get entries that exist in only one HashMap using MapDifference.entriesOnlyOnRight() and MapDifference.entriesOnlyOnLeft():

public void givenDifferentMaps_whenGetEntriesOnOneSideUsingGuava_thenSuccess() {
    MapDifference<String, String> diff = Maps.difference(asia1, asia2);
    Map<String, String> entriesOnlyOnRight = diff.entriesOnlyOnRight();
    Map<String, String> entriesOnlyOnLeft = diff.entriesOnlyOnLeft();
    assertEquals(1, entriesOnlyOnRight.size());
    assertEquals(1, entriesOnlyOnLeft.size());
    assertThat(entriesOnlyOnRight, hasEntry("China", "Beijing"));
    assertThat(entriesOnlyOnLeft, hasEntry("South Korea", "Seoul"));

5.3. MapDifference.entriesInCommon()

Next, we'll get common entries using MapDifference.entriesInCommon():

public void givenDifferentMaps_whenGetCommonEntriesUsingGuava_thenSuccess() {
    MapDifference<String, String> diff = Maps.difference(asia1, asia2);
    Map<String, String> entriesInCommon = diff.entriesInCommon();

    assertEquals(1, entriesInCommon.size());
    assertThat(entriesInCommon, hasEntry("Japan", "Tokyo"));

5.4. Customizing Maps.difference() Behavior

Since Maps.difference() use equals() and hashCode() by default to compare entries, it won't work for Objects that don't implement them properly:

public void givenSimilarMapsWithArrayValue_whenCompareUsingGuava_thenFail() {
    MapDifference<String, String[]> diff = Maps.difference(asiaCity1, asiaCity2);

But, we can customize the method used in comparison using Equivalence.

For example, we'll define Equivalence for type String[] to compare String[] values in our HashMaps as we like:

public void givenSimilarMapsWithArrayValue_whenCompareUsingGuavaEquivalence_thenSuccess() {
    Equivalence<String[]> eq = new Equivalence<String[]>() {
        protected boolean doEquivalent(String[] a, String[] b) {
            return Arrays.equals(a, b);

        protected int doHash(String[] value) {
            return value.hashCode();

    MapDifference<String, String[]> diff = Maps.difference(asiaCity1, asiaCity2, eq);

    diff = Maps.difference(asiaCity1, asiaCity3, eq); 

6. Conclusion

In this article, we discussed different ways to compare HashMaps in Java. We learned multiple ways to check if two HashMaps are equal and how to get the detailed difference as well.

The full source code is available over on GitHub.