Introduction

Java 8 gives you several ways to measure the gap between two LocalDateTime values, but each API answers a slightly different question. ChronoUnit is best for total elapsed units, Duration is good for time-based differences, and Period belongs to date-only calculations rather than full date-time values.

Start With What LocalDateTime Means

LocalDateTime contains date and time fields but no timezone or offset. That means the difference is calculated in local calendar terms, not in terms of real-world timezone transitions.

If daylight saving changes or cross-region timestamps matter, convert to ZonedDateTime or Instant first.

Use ChronoUnit.between for Total Units

When you want the total number of days, hours, minutes, or seconds between two values, ChronoUnit.between is the simplest tool.

1import java.time.LocalDateTime;
2import java.time.temporal.ChronoUnit;
3
4public class ChronoUnitDemo {
5    public static void main(String[] args) {
6        LocalDateTime start = LocalDateTime.of(2026, 1, 1, 8, 0);
7        LocalDateTime end = LocalDateTime.of(2026, 1, 2, 10, 30);
8
9        System.out.println(ChronoUnit.DAYS.between(start, end));
10        System.out.println(ChronoUnit.HOURS.between(start, end));
11        System.out.println(ChronoUnit.MINUTES.between(start, end));
12    }
13}

The important detail is that each call gives a total unit count:

• days: 1
• hours: 26
• minutes: 1590

Those are not component parts. They are full elapsed totals.

Use Duration for Time-Based Breakdown

If you want to break the difference into multiple units in one calculation, Duration is often more convenient.

1import java.time.Duration;
2import java.time.LocalDateTime;
3
4public class DurationDemo {
5    public static void main(String[] args) {
6        LocalDateTime start = LocalDateTime.of(2026, 1, 1, 8, 15);
7        LocalDateTime end = LocalDateTime.of(2026, 1, 2, 10, 45);
8
9        Duration duration = Duration.between(start, end);
10
11        long totalMinutes = duration.toMinutes();
12        long totalHours = duration.toHours();
13        long days = duration.toDays();
14        long hoursPart = totalHours % 24;
15        long minutesPart = totalMinutes % 60;
16
17        System.out.println(days + " days");
18        System.out.println(hoursPart + " hours");
19        System.out.println(minutesPart + " minutes");
20    }
21}

This example produces a component-style breakdown rather than unrelated total counts.

Period Is Not for Full LocalDateTime Differences

Period works with LocalDate, not LocalDateTime, and it measures date-based components such as years, months, and days. If you convert a LocalDateTime to LocalDate, you lose the time-of-day part.

1import java.time.LocalDate;
2import java.time.Period;
3
4public class PeriodDemo {
5    public static void main(String[] args) {
6        LocalDate start = LocalDate.of(2026, 1, 1);
7        LocalDate end = LocalDate.of(2026, 3, 5);
8
9        Period period = Period.between(start, end);
10        System.out.println(period.getMonths());
11        System.out.println(period.getDays());
12    }
13}

Use this only when your requirement is genuinely calendar-based.

Getting Multiple Units Correctly

Developers often want an answer like "2 days, 3 hours, 10 minutes." The safest approach is:

1. compute one duration
2. extract total units
3. compute the remainder for smaller units

Do not call ChronoUnit.DAYS.between, ChronoUnit.HOURS.between, and ChronoUnit.MINUTES.between and then treat those results as component parts. Those values overlap because each one is a total from the same start.

Negative Differences

If the end is before the start, ChronoUnit and Duration will return negative values.

1import java.time.Duration;
2import java.time.LocalDateTime;
3
4public class NegativeDemo {
5    public static void main(String[] args) {
6        LocalDateTime start = LocalDateTime.of(2026, 1, 2, 10, 0);
7        LocalDateTime end = LocalDateTime.of(2026, 1, 1, 8, 0);
8
9        System.out.println(Duration.between(start, end).toHours());
10    }
11}

Sometimes that is correct. Other times you may want Math.abs(...) or explicit input normalization before formatting the result.

Common Pitfalls

The biggest pitfall is mixing total units with component units. 26 total hours is not the same as 1 day and 2 hours, even though they describe the same span.

Another issue is using LocalDateTime when timezone-aware time is actually required. If an event crosses a daylight saving boundary, local date-time arithmetic may not reflect the real elapsed clock time you care about.

Developers also misuse Period for date-time calculations. Period is for date-based components, not for hour and minute differences.

Finally, avoid recomputing the same difference in many unrelated ways. Pick one representation, then derive the display you need from that representation.

Summary

• Use ChronoUnit.between for total elapsed units such as total hours or total minutes.
• Use Duration when you want time-based calculations and remainder-style breakdowns.
• Use Period only for date-based differences, not for full LocalDateTime values.
• Treat LocalDateTime as timezone-free local data, not as a real instant on the global timeline.
• Decide whether you need total units or component parts before choosing the API.