Java LocalDate minusDays: Subtract Days from a Date

java localdate minusdays requires a clear understanding of the core syntax, runtime behavior, and practical implementation patterns demonstrated in the examples below.

The LocalDate.minusDays() method in Java subtracts a specified number of days from a date and returns a new LocalDate instance. It is part of the java.time package introduced in Java 8, which replaced the older java.util.Date and Calendar classes for most date manipulation tasks. This method is straightforward to use, but understanding its behavior at month and year boundaries, its relationship with plusDays(), and its immutable nature is essential for writing correct date logic.

Basic Usage of minusDays

To subtract days from a LocalDate, call minusDays() with a long argument. The method returns a new LocalDate object; the original instance remains unchanged.

import java.time.LocalDate;

LocalDate today = LocalDate.of(2025, 3, 15);
LocalDate tenDaysEarlier = today.minusDays(10);

System.out.println(today);          // 2025-03-15
System.out.println(tenDaysEarlier); // 2025-03-05

The argument is a long, so you can pass any integer value, including values larger than the number of days in a month or year. The method handles the arithmetic internally, adjusting the month and year as needed.

How minusDays Handles Month and Year Boundaries

When subtracting days crosses a month or year boundary, minusDays() automatically adjusts the date. For example, subtracting 20 days from March 5 yields February 13 in a non-leap year.

LocalDate march5 = LocalDate.of(2025, 3, 5);
LocalDate february13 = march5.minusDays(20);
System.out.println(february13); // 2025-02-13

Leap years are also respected. Subtracting days from March 1 in a leap year correctly produces February 29.

LocalDate march1Leap = LocalDate.of(2024, 3, 1);
LocalDate feb29 = march1Leap.minusDays(1);
System.out.println(feb29); // 2024-02-29

This behavior is consistent with the ISO-8601 calendar system that LocalDate uses, so you do not need to manually account for varying month lengths or leap-year rules.

Negative Arguments and the Relationship with plusDays

minusDays() accepts negative values. Subtracting a negative number of days is equivalent to adding the absolute value. In other words, date.minusDays(-5) behaves exactly like date.plusDays(5). This symmetry can simplify code when the number of days to shift is computed dynamically.

LocalDate base = LocalDate.of(2025, 6, 10);

LocalDate plusFive = base.minusDays(-5); // equivalent to plusDays(5)
LocalDate minusFive = base.plusDays(-5); // equivalent to minusDays(5)

System.out.println(plusFive);  // 2025-06-15
System.out.println(minusFive); // 2025-06-05

Because both methods accept negative arguments, you can choose the one that makes the intent clearer. If the variable represents a delta that may be positive or negative, using plusDays() with a signed delta is often more readable. If you are explicitly subtracting a non-negative amount, minusDays() communicates the operation directly.

Immutability and Return Value

LocalDate is immutable, and all arithmetic methods, including minusDays(), return a new instance rather than modifying the existing one. This has two important consequences.

First, you must assign the result to a variable or use it directly. Forgetting to capture the return value is a common mistake.

LocalDate date = LocalDate.of(2025, 7, 20);
date.minusDays(3); // result is discarded, date remains unchanged
System.out.println(date); // still 2025-07-20

Second, because the original object is never mutated, LocalDate instances are safe to share across threads. There is no need for defensive copies or synchronization when passing LocalDate objects between threads, as long as the references themselves are handled correctly.

Common Mistakes and Edge Cases

One frequent error is passing null to minusDays(). The method expects a primitive long, so a null cannot be passed directly. However, if you are using a Long object from a nullable source, unboxing may throw a NullPointerException. Always validate or convert before calling the method.

Another edge case is subtracting days from the minimum supported date. LocalDate.MIN is -999999999-01-01. Calling minusDays(1) on this date throws a DateTimeException because the result would be outside the valid range. The same applies to LocalDate.MAX when adding days. In practice, this is rarely an issue unless you are working with extreme dates, but it is worth knowing that the method does not silently wrap.

LocalDate minDate = LocalDate.MIN;
try {
    LocalDate invalid = minDate.minusDays(1);
} catch (DateTimeException e) {
    // Result would be out of range
}

Choosing Between minusDays and Other Date Arithmetic

LocalDate provides several arithmetic methods: minusDays(), minusWeeks(), minusMonths(), and minusYears(). The choice depends on the unit you want to subtract. For calendar-based operations like