Python timedelta: Time Differences

Time is tricky in programming. Python's timedelta makes it simple. It represents a duration. You can add or subtract time from dates. This guide covers everything you need.

A timedelta is a difference between two dates or times. Think of it as a time span. It can be days, seconds, or microseconds. It is part of the datetime module.

What is a timedelta?

A timedelta object stores a duration. It does not store specific dates. It only stores the difference. This makes it perfect for calculations.

You create a timedelta using keyword arguments. Common arguments are days, seconds, microseconds, milliseconds, minutes, hours, and weeks.

These arguments are optional. Their default value is zero. Python converts all values to days, seconds, and microseconds internally.

Creating a timedelta Object

Creating a timedelta is straightforward. You call it from the datetime module. Let's see some examples.

 
from datetime import timedelta

# Create a duration of 5 days
five_days = timedelta(days=5)
print(five_days)

# Create a duration of 2 weeks and 3 hours
two_weeks_three_hours = timedelta(weeks=2, hours=3)
print(two_weeks_three_hours)

# Create a duration of 1 day, 12 hours, and 30 minutes
one_day_half = timedelta(days=1, hours=12, minutes=30)
print(one_day_half)

5 days, 0:00:00
14 days, 3:00:00
1 day, 12:30:00

The output shows the duration in a readable format. It shows days, hours, minutes, and seconds. Negative durations are possible too.

Using timedelta with datetime

The real power of timedelta comes with datetime objects. You can add or subtract durations. This helps you find future or past dates.

First, get a current date and time using datetime.now(). Then add a timedelta to it.

 
from datetime import datetime, timedelta

# Get current date and time
now = datetime.now()
print("Now:", now)

# Add 7 days
future_date = now + timedelta(days=7)
print("Future:", future_date)

# Subtract 2 hours
past_time = now - timedelta(hours=2)
print("Past:", past_time)

Now: 2024-01-15 14:30:00.123456
Future: 2024-01-22 14:30:00.123456
Past: 2024-01-15 12:30:00.123456

This is very useful. You can schedule events. You can calculate deadlines. You can find time differences easily.

For more on getting the current time, read our Python datetime now: Get Current Date & Time guide.

Calculating Time Differences

You can subtract two datetime objects. The result is a timedelta. This shows the exact difference between two points in time.

 
from datetime import datetime

# Two different dates
date1 = datetime(2024, 1, 1, 10, 0, 0)
date2 = datetime(2024, 1, 5, 15, 30, 0)

# Calculate difference
difference = date2 - date1
print("Difference:", difference)

# Access specific attributes
print("Days:", difference.days)
print("Seconds:", difference.seconds)
print("Total seconds:", difference.total_seconds())

Difference: 4 days, 5:30:00
Days: 4
Seconds: 19800
Total seconds: 361800.0

The .days attribute gives only whole days. The .seconds attribute gives the remainder in seconds. The .total_seconds() method gives the entire duration in seconds.

This is perfect for measuring elapsed time. You can track how long a task takes.

timedelta Attributes and Methods

A timedelta object has three main attributes. They are days, seconds, and microseconds. You can access them directly.

It also has one important method. The total_seconds() method returns the duration as a float. This is useful for calculations.

 
from datetime import timedelta

duration = timedelta(days=2, hours=6, minutes=30)

# Access attributes
print("Days:", duration.days)
print("Seconds:", duration.seconds)
print("Microseconds:", duration.microseconds)

# Total seconds
total = duration.total_seconds()
print("Total seconds:", total)

Days: 2
Seconds: 23400
Microseconds: 0
Total seconds: 196200.0

Note that seconds are always between 0 and 86399. Microseconds are between 0 and 999999. The days can be any integer.

Comparing timedelta Objects

You can compare two timedelta objects. Use comparison operators like <, >, ==, and !=. This helps you check durations.

 
from datetime import timedelta

short_time = timedelta(hours=1)
long_time = timedelta(days=1)

print("Is short_time less?", short_time < long_time)
print("Are they equal?", short_time == long_time)
print("Is long_time greater?", long_time > short_time)

Is short_time less? True
Are they equal? False
Is long_time greater? True

This is useful for conditional logic. You can check if a deadline is near. You can compare task durations.

Negative timedelta

A timedelta can be negative. This happens when you subtract a larger duration from a smaller one. It also happens when you subtract a later date from an earlier one.

 
from datetime import timedelta

negative_dur = timedelta(days=-1, hours=2)
print("Negative duration:", negative_dur)

# Its attributes are normalized
print("Days:", negative_dur.days)
print("Seconds:", negative_dur.seconds)

Negative duration: -1 day, 2:00:00
Days: -1
Seconds: 7200

Python normalizes negative timedelta objects. The days will be negative. The seconds and microseconds will be positive. This keeps the representation consistent.

Practical Examples

Let's see some real-world uses. You can calculate age. You can find the next weekday. You can measure execution time.

Calculate Age

 
from datetime import datetime

birth_date = datetime(1990, 5, 15)
today = datetime.now()
age = today - birth_date
print("Age in days:", age.days)
print("Age in years:", age.days // 365)

Age in days: 12291
Age in years: 33

Find Next Friday

 
from datetime import datetime, timedelta

today = datetime.now()
# Monday is 0, Sunday is 6
# Friday is 4
days_ahead = (4 - today.weekday()) % 7
if days_ahead == 0:
    days_ahead = 7  # Next week
next_friday = today + timedelta(days=days_ahead)
print("Next Friday:", next_friday.date())

Next Friday: 2024-01-19

Measure Execution Time

 
from datetime import datetime

start = datetime.now()
# Simulate some work
sum(x for x in range(1000000))
end = datetime.now()
elapsed = end - start
print("Elapsed time:", elapsed)
print("In seconds:", elapsed.total_seconds())

Elapsed time: 0:00:00.123456
In seconds: 0.123456

These examples show how useful timedelta is. It handles the math for you.

Common Mistakes

Beginners often confuse timedelta with datetime. Remember, timedelta is a duration. datetime is a specific point in time.

Another mistake is ignoring normalization. When you create a timedelta with large values, Python normalizes them. For example, 25 hours becomes 1 day and 1 hour.

Also, be careful with arithmetic. Adding a timedelta to a datetime is fine. Adding two timedelta objects is also fine. But adding a datetime to a datetime is not allowed.

For more on formatting dates, see our Python Datetime Strftime Guide. It helps you display dates nicely.

If you need to parse strings into dates, check the Python datetime strptime: Parse Strings to Dates guide.

Conclusion

Python's timedelta is a powerful tool. It makes time arithmetic easy. You can add, subtract, and compare durations. You can calculate differences between dates. You can measure elapsed time.

Remember the key points. Use timedelta for durations. Use datetime for specific moments. Access attributes like .days and .seconds. Use .total_seconds() for precise calculations.

Practice with the examples. Experiment with different values. Soon, handling time in Python will feel natural. timedelta is your friend for all time-related tasks.

Start using it today. Your code will be cleaner and more accurate.