HOWTO · Java
Java Date vs. LocalDate
This tutorial demonstrates the difference between date and localdate in Java.
On this page
Java’s Date and LocalDate represent different things. A Date represents an instant on the timeline, with millisecond precision. A LocalDate represents a calendar date, such as a birthday, without a time or a time zone. Choose based on whether your value is a moment or a date on a calendar.
Java Date vs. LocalDate
java.util.Date is a legacy type. Its stored value identifies an instant; it does not store a calendar time zone. When formatted or converted to calendar fields, that instant is interpreted using a chosen time zone, often the system default. The displayed day can therefore differ across zones.
java.time.LocalDate is in the java.time package. It is immutable and contains year, month, and day fields, but no time, offset, or zone. It cannot identify a unique moment by itself. Adding or subtracting days returns a new LocalDate rather than changing the original value.
| Aspect | java.util.Date |
java.time.LocalDate |
|---|---|---|
| Meaning | An instant on the timeline | A calendar date |
| Time zone | Not stored; choose a zone when converting or displaying | None; it does not identify an instant |
| Precision | Milliseconds | Whole days |
| Mutability | Mutable | Immutable |
| Typical use | Interoperating with APIs that require Date |
Birthdays, due dates, and other date-only values |
Despite its name, Date is not a date-only type. For a scheduled event at a particular moment, use an instant-bearing type and apply a zone when displaying it. For a business date that should remain the same regardless of the viewer’s location, use LocalDate.
Working with Date and Legacy APIs
Existing libraries and interfaces may still accept or return java.util.Date. Keep that type at the compatibility boundary, and use Instant to make its timeline meaning explicit. Date.toInstant() and Date.from(Instant) provide conversions between the legacy type and the modern time API.
Run this example:
import java.time.Instant;
import java.time.LocalDate;
import java.time.ZoneId;
import java.util.Date;
public class Main {
public static void main(String[] args) {
Date legacyDate = Date.from(Instant.parse("2024-03-10T00:30:00Z"));
Instant instant = legacyDate.toInstant();
LocalDate dateInNewYork = instant.atZone(ZoneId.of("America/New_York")).toLocalDate();
System.out.println("Instant: " + instant);
System.out.println("New York date: " + dateInNewYork);
}
}
Instant: 2024-03-10T00:30:00Z
New York date: 2024-03-09
This program starts with a fixed instant, converts it to Date for a legacy API, then converts back to Instant. Applying the New York zone determines the calendar date for that location. These are the results from the supplied run.
Do not treat Date as if it retained the zone used to display it: the same instant can correspond to different local dates in different zones. When adapting an existing API, make the conversion zone explicit wherever a calendar date is required.
Creating and Using LocalDate
Use LocalDate.now() for the current date in the system default zone, or pass a ZoneId when the application needs the date for a particular location. The zone determines which calendar date is returned; the resulting LocalDate does not retain that zone. Use LocalDate.of(year, month, day) for a known date. ofEpochDay and ofYearDay are available when the input is expressed as a day count from the epoch or as a day number within a year.
Run this example:
import java.time.LocalDate;
import java.time.Month;
import java.time.ZoneId;
public class Main {
public static void main(String[] args) {
LocalDate todayInTokyo = LocalDate.now(ZoneId.of("Asia/Tokyo"));
LocalDate dueDate = LocalDate.of(2025, Month.JANUARY, 15);
LocalDate epochDay = LocalDate.ofEpochDay(300);
LocalDate hundredthDay = LocalDate.ofYearDay(2024, 100);
System.out.println("Tokyo date: " + todayInTokyo);
System.out.println("Due date: " + dueDate);
System.out.println("Epoch day 300: " + epochDay);
System.out.println("Day 100 of 2024: " + hundredthDay);
}
}
Tokyo date: 2026-11-04
Due date: 2025-01-15
Epoch day 300: 1970-10-28
Day 100 of 2024: 2024-04-09
LocalDate.now(ZoneId) is a valid way to obtain the date in a supplied zone. It is useful when a service operates in a business zone that may differ from the machine’s default. A date created with of is explicit and stable, while now depends on the clock and zone at runtime. The Tokyo date above reflects the current-date line from the supplied run.
Choosing Between Date and LocalDate
Use LocalDate when the value is a calendar date with no meaningful time, such as a birthday, a billing date, or a due date. Use an instant-bearing type when the value identifies when something happened. Convert that instant through an explicit ZoneId when you need a local date or time for a particular place.
Keep Date where a legacy API requires it, and convert at the boundary rather than using it as the main representation for new date-only logic. In short: LocalDate for a day on the calendar, an instant-bearing type for a moment, and Date for compatibility with older interfaces.