Java LocalDate minusDays: Subtract Days from a Date

This article explains how to subtract days from a LocalDate using minusDays(), including the method's behavior at month and year boundaries, negative arguments, and immutability.

The LocalDate.minusDays() method 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 is the modern replacement for the older java.util.Date and Calendar classes for most date manipulation tasks. The method is straightforward to use, but understanding how it handles boundaries, negative values, and immutable return values 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 parameter is a long, so you can pass values larger than the number of days in a month or year. The method adjusts the month and year as needed and throws a DateTimeException if the resulting date falls outside the supported LocalDate range.

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 one day 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 signed delta, using plusDays() with that 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 a nullable Long to minusDays(). The method parameter is a primitive long, so you cannot pass a null literal directly. If a Long value from a nullable source is unboxed during the call, null causes a NullPointerException. Validate or convert the value 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.

import java.time.LocalDate;

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

Choosing Between minusDays and Other Date Arithmetic

LocalDate also provides minusWeeks(), minusMonths(), and minusYears(). Use these methods when you want to subtract calendar units rather than an exact number of days. For example, date.minusMonths(1) from March 31 returns February 28 in a non-leap year, whereas minusDays(30) simply moves back 30 days. In general, choose minusDays() when the amount is measured in days, and the unit-specific methods when you want week, month, or year arithmetic.