01 Why you should never do this with raw epoch math

It’s tempting to convert both dates into a raw timestamp — seconds or milliseconds since some fixed reference point — subtract one from the other, and divide by the number of seconds in a day. This produces the right answer surprisingly often, which is exactly what makes it dangerous: it quietly breaks on specific dates that don’t show up in casual testing, and the breakage is usually off by exactly one day or one hour, the kind of error that’s easy to miss in a spot-check but devastating in a billing system, a contract deadline calculator, or a flight booking engine.

The two things raw epoch-subtraction math gets wrong are daylight saving time transitions, which add or remove an hour from specific days in many timezones, and the subtlety of what “midnight” means across that transition. Both problems disappear if the subtraction is done using calendar-aware date types rather than raw timestamps — which is the approach every example in this article uses.

02 The right tool: a date library’s built-in subtraction

Every modern standard library ships a date type specifically designed to represent a calendar date without an attached time-of-day or timezone — exactly the right tool for this problem, since “number of days between two dates” is fundamentally a calendar question, not a duration-of-elapsed-time question. Subtracting two such date objects correctly accounts for every calendar irregularity — leap years, varying month lengths, and the fact that some months have 28, 29, 30, or 31 days — without the calling code needing to know any of those rules itself.

03 Code in Python, Java, and JavaScript

Python’s date objects support direct subtraction, returning a timedelta whose .days attribute is exactly the answer.

from datetime import date

def days_between(start: date, end: date) -> int:
    return (end - start).days

# days_between(date(2024, 1, 1), date(2024, 3, 1))  ->  60
# 2024 is a leap year — January has 31 days, February has 29

Java’s java.time package offers a dedicated utility specifically for this kind of calendar-field difference, which is more explicit about its intent than a raw subtraction would be.

import java.time.LocalDate;
import java.time.temporal.ChronoUnit;

public static long daysBetween(LocalDate start, LocalDate end) {
    return ChronoUnit.DAYS.between(start, end);
}

JavaScript lacks a built-in calendar-aware date-only type with native subtraction, which makes it the one language here where care is genuinely required — naive subtraction of two Date objects works in milliseconds, and converting that back to days needs an explicit, deliberate step.

function daysBetween(start, end) {
  // normalize both to UTC midnight first to sidestep DST entirely
  const utcStart = Date.UTC(start.getFullYear(), start.getMonth(), start.getDate());
  const utcEnd   = Date.UTC(end.getFullYear(),   end.getMonth(),   end.getDate());

  const msPerDay = 24 * 60 * 60 * 1000;
  return Math.round((utcEnd - utcStart) / msPerDay);
}

The explicit normalization to UTC midnight in the JavaScript version isn’t decorative — it’s the entire fix for the daylight saving problem covered in detail next.

04 Leap years — the part the calendar quietly handles for you

A year is a leap year, with February gaining a 29th day, if it’s divisible by 4 — except century years, which are leap years only if also divisible by 400. That means 2024 and 2028 are leap years, but 1900 was not, while 2000 was. This rule exists to keep the calendar year synchronized with the actual time it takes Earth to orbit the sun, which isn’t a clean 365 days but closer to 365.2425.

None of the date-library examples above needed to encode that rule explicitly — it’s already built into how the standard library’s date type counts forward from one date to another. This is precisely the value of routing date arithmetic through a real date type instead of hand-rolling it: leap year handling, varying month lengths, and similar calendar quirks are exactly the kind of detail that’s easy to get subtly wrong by hand and is worth letting a well-tested library handle instead.

05 Daylight saving time: the classic off-by-one-hour bug

In timezones that observe daylight saving time, one day each year is 23 hours long and another is 25 hours long, even though every calendar still shows them as a normal single date. If date arithmetic is done using full timestamps including time-of-day in local time, subtracting two dates that straddle one of those transitions can come out a fraction of a day short or long — exactly enough to round to the wrong whole number of days.

06 Inclusive versus exclusive day counts

A subtler question that has nothing to do with calendar mechanics: does “days between January 1st and January 3rd” mean 2 or 3? Plain subtraction, as shown in every example above, gives 2 — it’s measuring the gap between the dates, not the count of calendar days that includes both endpoints. Many real-world contexts — counting the length of a hotel stay, a rental period, or a billing cycle — actually want the inclusive count, which simply means adding 1 to the subtraction result.

07 A quick checklist for date-difference code

• Use a calendar-only date type whenever the question is genuinely about calendar dates rather than precise elapsed time.
• If you must use full timestamps, normalize to UTC first before any subtraction, to sidestep daylight saving entirely.
• Decide explicitly on inclusive versus exclusive counting, and document the choice next to the function rather than leaving it to be inferred.
• Test across a leap year boundary and a daylight saving transition date specifically — these are exactly the dates where naive implementations break, and they won’t show up in casual day-to-day testing.
• Avoid raw epoch-millisecond division by a fixed day length unless the inputs are already guaranteed to be UTC — it’s the single most common source of date-difference bugs in real codebases.