Java Arrays deepEquals: Nested Array Comparison

When you compare two arrays in Java with == or the default equals(), you are comparing object references, not the data inside the arrays. That is why java.util.Arrays provides equals() and deepEquals(). The java arrays deepequals method exists to compare nested arrays by their contents, and it behaves differently from Arrays.equals() in a way that matters as soon as your arrays contain other arrays.

Why Arrays.equals() Fails on Nested Arrays

Arrays.equals() compares two arrays element by element. For each pair of elements, it calls equals() on the elements. When the elements are primitives, the comparison is straightforward. When the elements are objects, the comparison depends on whether those objects override equals().

The problem appears when the elements are themselves arrays. An inner array is an object, and unless it overrides equals(), the comparison falls back to reference equality. Two inner arrays that contain the same values are still different objects, so Arrays.equals() reports them as unequal.

int[][] first = {{1, 2}, {3, 4}};
int[][] second = {{1, 2}, {3, 4}};

System.out.println(Arrays.equals(first, second));      // false
System.out.println(Arrays.deepEquals(first, second));  // true

first and second are distinct objects, and so are their inner arrays. Arrays.equals() compares the inner arrays by reference and returns false. Arrays.deepEquals() recurses into the inner arrays and compares their contents, returning true.

What Arrays.deepEquals() Actually Compares

Arrays.deepEquals(Object[] a1, Object[] a2) compares two arrays deeply. Two arrays are deeply equal when they have the same number of elements and every corresponding pair of elements is deeply equal. An element that is itself an array is compared recursively with the same deep logic. Any other element is compared with equals().

The method accepts Object[], not primitive arrays. A primitive int[] cannot be passed to deepEquals() directly because int[] is not a subtype of Object[]. A two-dimensional int[][] can be passed, because its elements are int[] objects, and int[] is an Object. The same applies to String[][], Object[][], and any array whose elements are reference types.

Comparing Multi-Dimensional Arrays

Multi-dimensional arrays are the most common reason to reach for deepEquals(). Each level of nesting adds another layer of reference comparison that Arrays.equals() cannot handle.

String[][] expected = {{"user", "admin"}, {"guest"}};
String[][] actual = {{"user", "admin"}, {"guest"}};

if (Arrays.deepEquals(expected, actual)) {
    // contents match at every level
}

The recursion continues until it reaches elements that are not arrays. For String[][], the recursion stops at the String elements, which are compared with String.equals(). For int[][][], it stops at the int primitives.

How deepEquals Handles Null and Object Elements

Two null references are deeply equal. If one array contains null and the other contains a non-null value, the comparison returns false. This matches the behavior of Objects.equals() and avoids the NullPointerException that a naive element.equals() call would throw.

For arrays of objects, the element comparison uses the object's own equals() implementation. That means deepEquals() is only as correct as the equals() methods of the objects it contains. If a class does not override equals(), two distinct instances with identical fields are not deeply equal, because the default Object.equals() compares references.

class Coordinate {
    int x;
    int y;
    // no equals() override
}

Coordinate[] a = {new Coordinate(1, 2)};
Coordinate[] b = {new Coordinate(1, 2)};

System.out.println(Arrays.deepEquals(a, b)); // false

This is not a limitation of deepEquals(); it is the expected contract. Deep equality is defined in terms of the element types' own equality rules.

Runtime Cost and Performance Considerations

Deep comparison is recursive. The cost is proportional to the total number of elements across all levels, so it is O(n) in the total element count. Each level of nesting adds method-call and stack overhead, and each non-array element comparison calls equals(), which may itself be expensive for complex objects.

The standard implementation short-circuits when both arguments reference the same array object, returning true immediately. That avoids traversing the structure when the caller passes the same array twice. There is no caching and no memoization, so repeated comparisons of large structures recompute everything each time.

If you are comparing very large or deeply nested arrays in a hot path, consider whether the structure can be compared more cheaply, for example by comparing a cached hash or by normalizing the data into a flat representation. For typical test assertions and configuration checks, the cost of deepEquals() is rarely the bottleneck.

Choosing Between equals, deepEquals, and Manual Comparison

Use Arrays.equals() when the arrays are one-dimensional and contain primitives or objects with well-defined equals() methods. It is faster and does not carry the recursion overhead.

Use Arrays.deepEquals() when the arrays contain other arrays, which includes every multi-dimensional array. It is the only standard method that compares nested contents correctly.

Use a manual comparison when you need custom element equality that the element types do not provide, or when you need to compare only part of the structure. A manual loop gives you control over which fields are compared and lets you stop early.

boolean matches = a.length == b.length;
for (int i = 0; matches && i < a.length; i++) {
    matches = a[i].x == b[i].x && a[i].y == b[i].y;
}

This approach avoids recursion and defines equality exactly for the fields that matter, which is useful when the element class does not override equals() and you cannot modify it.

Compatibility and Behavioral Boundaries

deepEquals() is available on java.util.Arrays since Java 5, so it is present in every modern JDK. The main behavioral boundary is the Object[] signature: you cannot pass a primitive array directly, and the method cannot compare primitive arrays of different types. Two int[] arrays are compared with the Arrays.equals(int[], int[]) overload, not with deepEquals().

Another boundary is symmetry with equals(). deepEquals() and equals() can disagree for the same pair of arrays, and that is by design. Arrays.equals() is shallow for nested arrays, while deepEquals() is recursive. When you write tests or assertions, choose one and apply it consistently, because mixing the two produces results that are difficult to reason about.