datetime.timedelta

Seven keyword units in, three fields out. Everything is folded into days, seconds (0–86399) and microseconds, so a negative duration shows up as "-1 day, 23:00:00".

datetime classPython 2.3+Live demo
Common call
datetime.now(UTC) + timedelta(days=7)
Returns
timedelta(days=…, seconds=…, microseconds=…)
Replaces
Manual seconds arithmetic: t + 7 * 24 * 3600
Watch out
No months or years — their length varies
timedelta(daysdays — Whole or fractional days.type: int | float · default: 0=0, secondsseconds — Seconds; values ≥ 86400 roll into days.type: int | float · default: 0=0, microsecondsmicroseconds — Microseconds, the resolution. Fractions round half to even.type: int | float · default: 0=0, millisecondsmilliseconds — = 1000 microseconds.type: int | float · default: 0=0, minutesminutes — = 60 seconds.type: int | float · default: 0=0, hourshours — = 3600 seconds.type: int | float · default: 0=0, weeksweeks — = 7 days.type: int | float · default: 0=0)
→ timedelta

Demo

Live evaluation
Mix any units, including negatives. The repr shows how Python stores it; str() is the h:mm:ss form.
Try:
Inputs
daysintdays
hoursinthours
minutesintminutes
secondsintseconds
Code
from datetime import timedelta
d = timedelta(days=1, hours=36, minutes=90, seconds=0)
(d, str(d))
Result
(datetime.timedelta(days=2, seconds=48600), '2 days, 13:30:00')

The normalized form explains the odd-looking reprs: minus one hour is stored as days=-1, seconds=82800 (−86400 + 82800 = −3600 seconds), and str() prints it the same way, "-1 day, 23:00:00". Division by a timedelta needs a non-zero step; % keeps the sign of the step, like int %.

Parameters

NameTypeRequiredDescription
daysint | floatno (0)Whole or fractional days.
secondsint | floatno (0)Seconds; values ≥ 86400 roll into days.
microsecondsint | floatno (0)Microseconds, the resolution. Fractions round half to even.
millisecondsint | floatno (0)= 1000 microseconds.
minutesint | floatno (0)= 60 seconds.
hoursint | floatno (0)= 3600 seconds.
weeksint | floatno (0)= 7 days.

Return value

timedelta — A normalized duration: 0 <= seconds < 86400, 0 <= microseconds < 1000000, days carries the sign.

Common patterns

N days from a date
date + timedelta → date; datetime + timedelta → datetime.
from datetime import date, timedelta
due = date(2026, 9, 29) + timedelta(days=30)
Sum durations
sum() starts from 0 (an int) — give it a timedelta start value.
from datetime import timedelta
total = sum(durations, timedelta())
Format as H:MM without days
divmod on total seconds gives any layout you like.
minutes, seconds = divmod(int(d.total_seconds()), 60)
hours, minutes = divmod(minutes, 60)
label = f'{hours}:{minutes:02d}'
Round a datetime to 15 minutes
timedelta % timedelta gives the remainder to strip off (naive dt; datetime.min is naive).
from datetime import timedelta
q = timedelta(minutes=15)
rounded_down = dt - (dt - dt.min) % q

Examples

1. Units are normalized
from datetime import timedelta timedelta(days=1, hours=36, minutes=90)
Returns
datetime.timedelta(days=2, seconds=48600)
2. Negative durations
from datetime import timedelta d = timedelta(hours=-1) print(d) d
Returns
-1 day, 23:00:00 datetime.timedelta(days=-1, seconds=82800)
3. How many fit
from datetime import timedelta timedelta(weeks=1) / timedelta(days=1)
Returns
7.0
4. Floor division and remainder
from datetime import timedelta divmod(timedelta(hours=10), timedelta(hours=3))
Returns
(3, datetime.timedelta(seconds=3600))
5. Divide by an int
from datetime import timedelta timedelta(minutes=10) / 7
Returns
datetime.timedelta(seconds=85, microseconds=714286)
6. Fractions of a microsecond round to even
from datetime import timedelta (timedelta(microseconds=0.5), timedelta(microseconds=1.5))
Returns
(datetime.timedelta(0), datetime.timedelta(microseconds=2))
7. Compare durations
from datetime import timedelta timedelta(hours=24) == timedelta(days=1)
Returns
True
8. The range limit
from datetime import timedelta timedelta(days=1_000_000_000)
Returns
OverflowError: days=1000000000; must have magnitude <= 999999999

Pitfalls

1. timedelta(months=1)
There is no months (or years) argument — a month is 28 to 31 days. Use replace() on the date, or calendar.monthrange to clamp the day.
months=
from datetime import timedelta
timedelta(months=1)
TypeError: __new__() got an unexpected keyword argument 'months'
replace(month=…)
from datetime import date
date(2026, 9, 29).replace(month=10)
datetime.date(2026, 10, 29)
2. sum() of timedeltas without a start
sum() starts from the int 0, and int + timedelta is not defined.
sum(list)
from datetime import timedelta
sum([timedelta(minutes=30), timedelta(minutes=45)])
TypeError: unsupported operand type(s) for +: 'int' and 'datetime.timedelta'
sum(list, timedelta())
from datetime import timedelta
sum([timedelta(minutes=30), timedelta(minutes=45)], timedelta())
datetime.timedelta(seconds=4500)
3. Reading .seconds as the length
.seconds is only the part below one day. A 26-hour duration has seconds=7200.
.seconds
from datetime import timedelta
timedelta(hours=26).seconds
7200
.total_seconds()
from datetime import timedelta
timedelta(hours=26).total_seconds()
93600.0

When to use

Use it
  • Adding or subtracting fixed amounts of time from dates and datetimes
  • The result of date - date or datetime - datetime
  • Timeouts, TTLs and intervals you want to print or compare
Reach for something else
  • Calendar months and years → replace(), or dateutil.relativedelta (third-party)
  • Wall-clock arithmetic across DST changes → do it in UTC, then convert
  • Measuring code speed → time.perf_counter()

Notes

CPython impl
delta_new in Modules/_datetimemodule.c: int arguments are summed exactly as microseconds; float fractions are accumulated separately and rounded half to even once at the end
Range
timedelta.min is -999999999 days, timedelta.max is 999999999 days, 23:59:59.999999; beyond that OverflowError
Operators
+ - with timedelta, date, datetime; * by int/float; / by int/float/timedelta; // by int/timedelta; % and divmod by timedelta; abs(), -d, comparisons
Truth
timedelta(0) is falsy, every other duration is truthy

FAQ

date + timedelta(days=n). It works for negative n too, and crosses month and year ends correctly: date(2026, 12, 31) + timedelta(days=1) is date(2027, 1, 1).