Creating timedeltas is a core skill for working with time differences in Python — the timedelta class from the datetime module lets you represent durations as days, seconds, and microseconds, then use them to shift dates/times, compute intervals, or measure elapsed time. In 2026, timedelta remains the standard for date/time arithmetic — essential for scheduling, age calculations, timeouts, performance benchmarking, data filtering by time windows, and any logic involving durations or offsets. It’s precise, handles edge cases like leap seconds (when used with aware datetimes), and integrates seamlessly with pandas/Polars for vectorized operations on large timestamp data.
Here’s a complete, practical guide to creating and using timedelta: constructor parameters, common creation patterns, arithmetic examples, real-world uses, and modern best practices with type hints, time zones, and scalability.
The timedelta constructor accepts keyword arguments for weeks, days, hours, minutes, seconds, milliseconds, and microseconds — all optional, defaulting to zero.
from datetime import timedelta
# Basic durations
two_days = timedelta(days=2)
print(two_days) # 2 days, 0:00:00
three_hours_thirty_min = timedelta(hours=3, minutes=30)
print(three_hours_thirty_min) # 3:30:00
micro_precise = timedelta(microseconds=123456)
print(micro_precise) # 0:00:00.123456
# Combined
full_duration = timedelta(weeks=1, days=2, hours=3, minutes=30, seconds=45, microseconds=123456)
print(full_duration) # 9 days, 3:30:45.123456
Arithmetic with timedelta — add/subtract from date or datetime to shift time, or add/subtract timedeltas themselves.
from datetime import datetime
dt = datetime(2023, 3, 14, 13, 30, 45)
# Add duration
new_dt = dt + timedelta(days=2, hours=3, minutes=30)
print(new_dt) # 2023-03-16 17:00:45
# Subtract one week
last_week = dt - timedelta(weeks=1)
print(last_week) # 2023-03-07 13:30:45
# Add two durations
extra = timedelta(hours=2, seconds=30)
total_dur = timedelta(days=2, hours=3, minutes=30) + extra
print(total_dur) # 2 days, 5:31:00
Real-world pattern: calculating time intervals, deadlines, or elapsed time — common in user sessions, task scheduling, logs, and performance monitoring.
# Time since user signup
signup = datetime(2023, 1, 1, 10, 0)
now = datetime.now()
time_since = now - signup
print(f"Days since signup: {time_since.days}")
print(f"Total seconds: {time_since.total_seconds():.0f}")
# Days until project deadline
deadline = datetime(2026, 12, 31, 23, 59)
days_left = (deadline - now).days
print(f"Days until deadline: {days_left}")
Best practices make timedelta usage safe, readable, and performant. Use keyword arguments — timedelta(days=2, hours=3) — clearer than positional. Prefer total_seconds() for floating-point durations — avoids integer truncation. Modern tip: use Polars for large timestamp differences — pl.col("end") - pl.col("start") returns duration in days/seconds/microseconds — 10–100× faster than pandas. Add type hints — timedelta — improves readability and mypy checks. Handle negative deltas — if delta.days < 0 for past events. For month/year jumps, use dateutil.relativedelta — dt + relativedelta(months=3) — handles month-end correctly (unlike timedelta). In production, use UTC for all stored timestamps — convert local only for display. Combine with pandas — df['duration'] = df['end'] - df['start'] — vectorized and fast. Wrap arithmetic over user input in try/except — invalid dates raise errors.
Creating and using timedelta makes time shifts and intervals clean, precise, and reliable — add/subtract time, compute spans, and handle real-world time logic without bugs. In 2026, use keyword args, UTC, type hints, and Polars for scale. Master durations, and you’ll build accurate scheduling, analytics, timers, and time-based features effortlessly.
Next time you need to add days, subtract hours, or find the time between events — reach for timedelta. It’s Python’s cleanest way to do date/time math — accurately and efficiently.