📅 Date Difference Calculator

What this calculator returns

The Date Difference Calculator measures the elapsed calendar distance between two valid dates, then reports both human calendar units and exact whole-day totals. It also works as a date arithmetic tool for adding or subtracting years, months, weeks, and days from a starting date.

• Difference between two dates - returns a calendar-aware {years, months, days} breakdown, direction (forward, backward, or same), total days, weeks plus remainder days, hours, minutes, seconds, and Monday-Friday business days.
• Add duration - starts from one date and adds integer years, months, weeks, and days, returning the resulting date, weekday, and YYYY-MM-DD output.
• Subtract duration - applies the same date arithmetic in reverse. Negative duration components are accepted, so subtracting -1 year is equivalent to adding 1 year.

How the calendar difference is calculated

For two dates A (start) and B (end) with B >= A, the years/months/days result uses a calendar-carry rule. This is the result people usually expect for questions like "how long from 2024-01-31 to 2024-03-01?", because month length matters instead of treating every month as a fixed number of days.

years  = bYear  - aYear
months = bMonth - aMonth
days   = bDay   - aDay

if days < 0:
    days   += daysInMonth(bYear, bMonth - 1)
    months -= 1

if months < 0:
    months += 12
    years  -= 1

If the user enters the later date first, the same calculation is performed in chronological order and the tool reports direction: backward. The calendar magnitude stays non-negative, while the absolute totals show elapsed whole days between the two UTC midnights.

Worked date difference example

From 2024-01-01 to 2026-05-26:

• Calendar: 2 years, 4 months, 25 days.
• Total days: 876 (= 125 weeks + 1 day).
• Total hours: 21,024; minutes 1,261,440; seconds 75,686,400.
• Business days (Mon-Fri inclusive between the two dates): 627.
• Direction: forward (start < end).

This vector is cross-checked against the timeanddate.com Date Duration Calculator.

Month-end and leap-year behavior

When adding or subtracting whole months across a month boundary, the day of month is clamped to the last valid day of the resulting month. This avoids rollover surprises such as January 31 becoming March 2 when February is too short.

• 2024-01-31 + 1 month = 2024-02-29 (2024 is a leap year, so Feb has 29 days).
• 2025-01-31 + 1 month = 2025-02-28 (2025 is a common year).
• 2024-03-31 + 1 month = 2024-04-30 (April has 30 days).
• 2026-03-01 - 1 year = 2025-03-01 (no clamp needed).

The operation order is deliberate: years first, then months, then clamp, then weeks and days as a flat day count. That mirrors the default constrained overflow behavior documented for Temporal.PlainDate calendar arithmetic.

Use cases

• Project deadlines - count total days, weeks, and business days remaining before a milestone.
• Billing cycles - add 1 month, 3 months, or 12 months while keeping last-of-month schedules aligned to real month ends.
• Contracts and renewals - calculate end dates for fixed terms such as 30 days, 90 days, 12 months, or 24 months.
• Travel planning - compare calendar days, weekdays, and weekend spans when planning itineraries or leave.
• Anniversaries and records - answer "how long has it been?" in years, months, days, and total elapsed days.

Calendar definition

The tool uses the proleptic Gregorian calendar: the modern Gregorian leap-year rule is extended backward and forward for all supported years. Internally, dates are normalized at UTC midnight with Date.UTC, so the same input produces the same result regardless of the user's local time zone or DST rules. Years from -9999 through 9999 are supported, and invalid calendar dates such as February 30 are rejected instead of being silently rolled over.

References

• ISO 8601 defines the internationally recognized year-month-day date order used by the displayed YYYY-MM-DD output.
• RFC 3339 profiles ISO 8601 for Internet timestamps and documents Gregorian leap-year and full-date constraints.
• ECMAScript Date time values define UTC day arithmetic using the proleptic Gregorian calendar and 86,400-second days.
• ECMAScript Date.UTC is the UTC date construction primitive used to avoid local-time drift.
• Temporal.PlainDate documents constrained overflow for month arithmetic such as January 31 plus one month.
• timeanddate.com Date Duration Calculator is used as an independent cross-check for the pinned date-difference examples.
• For exact age with birthday-specific output, use the Age Calculator.
• For leap-year handling details, use the Leap Year Checker.
• For weekday lookups, use the Day of Week Calculator.