all Python 3datetimeterm

datetime.timedelta

timedelta

A span of time. It supports operations with dates: addition, subtraction and comparison. It stores days, seconds and microseconds.

Syntax

from datetime import timedelta
timedelta(days=0, seconds=0, ...)

Only days, seconds and microseconds are stored: weeks, hours and minutes are folded into them at construction, and there are no months or years at all, so "one month later" cannot be expressed with a timedelta. Beware of .seconds — it is the leftover within a day (0-86399), not the whole span; use total_seconds() when you need the full length.

Examples

from datetime import datetime, timedelta
td = timedelta(days=7)
print(td)  # → 7 days, 0:00:00
next_week = datetime.now() + td
print(next_week.date())
td2 = timedelta(hours=2, minutes=30)
print(td2.total_seconds())  # → 9000.0
d1 = datetime(2024,12,31)
d2 = datetime(2024,1,1)
print((d1-d2).days)  # → 365
print(timedelta(weeks=2))  # → 14 days

See also

Open in the full glossarydocs.python.orgReport an inaccuracy