How to Calculate the Difference Between Two Dates (Years, Months, Days)

Calculating the difference between two dates seems like it should be simple subtraction, and for a raw day-count, it basically is — convert both dates to timestamps, subtract, divide by milliseconds-per-day. Where it gets genuinely tricky is expressing that difference in years, months, and days simultaneously, which is what most real use cases actually want ("how old is this person" or "how long has this project been running" rarely wants a bare day-count).

The core difficulty is that months and years aren't fixed-length units — February has 28 or 29 days, other months have 30 or 31, and a year is sometimes 365 days and sometimes 366. A calculation that treats a 'month' as a fixed 30-day chunk produces results that are subtly wrong and get more wrong the larger the date range involved, which is exactly the kind of bug that's easy to miss in testing with a small date range and only becomes obviously wrong on real user data months later.

The correct approach works calendar-field by calendar-field rather than through pure timestamp arithmetic — comparing year, month, and day components directly, borrowing from the next-higher unit when a lower unit goes negative (similar to how you'd do subtraction by hand with borrowing). If the day-of-month in the end date is smaller than the day-of-month in the start date, you borrow a month (adding that month's actual day-count, not a flat 30); if the resulting month count is negative, you borrow a year.

Leap years need explicit handling within this borrowing logic, specifically around February. When borrowing a month lands you on February, the number of days you add back needs to be 28 or 29 depending on whether that specific year is a leap year — determined by the standard rule (divisible by 4, except century years, except again years divisible by 400), not just 'every 4 years,' which incorrectly treats years like 1900 as leap years when they aren't.

A related edge case worth handling deliberately: calculating 'one month later' from a date near month-end. One month after January 31st has no single obviously-correct answer, since February doesn't have 31 days — most implementations land on the last day of February (28th or 29th), which matches how people intuitively think about 'a month later' better than overflowing into March 2nd or 3rd would.

For date differences that span a genuinely long range — calculating someone's exact age, or the duration of a multi-year project — the field-by-field borrowing approach stays accurate regardless of how many leap years or varying-length months fall within the range, which pure day-count division fundamentally cannot guarantee once you're trying to express the answer in years and months rather than just total days.

If you're implementing this yourself, test explicitly against known tricky cases before trusting the general logic: a range that crosses February 29th, a range where the end date's day-of-month is earlier than the start date's (forcing a borrow), and a range spanning a non-leap century year like 1900 or 2100. These three cases catch the vast majority of real date-math bugs.

Our Date Calculator handles all of this correctly out of the box — pick two dates and get an accurate years/months/days breakdown plus a total day-count, calculated with proper calendar-aware logic rather than an approximation.