Introduction

In Python, the right way to convert a datetime.timedelta to seconds is almost always total_seconds(). It returns the full duration as a floating-point number, including days and microseconds, which is what most developers actually need.

Confusion happens because timedelta also exposes .days, .seconds, and .microseconds, and those individual attributes do not mean "the whole duration in seconds." They are normalized pieces of the duration, not a direct substitute for total_seconds().

Why .seconds Is Not the Full Answer

A timedelta stores its value internally as days, seconds, and microseconds. The .seconds attribute is only the leftover seconds part after full days have been separated out.

Example:

1from datetime import timedelta
2
3delta = timedelta(days=2, hours=3, minutes=10)
4
5print(delta.days)          # 2
6print(delta.seconds)       # 11400
7print(delta.total_seconds())

Output:

2
11400
184200.0

11400 is only 3 * 3600 + 10 * 60. It does not include the two full days. That is why .seconds is the wrong choice for most calculations.

Use total_seconds()

The intended API is:

1from datetime import timedelta
2
3delta = timedelta(days=1, hours=2, minutes=30, seconds=15)
4seconds = delta.total_seconds()
5
6print(seconds)

Output:

95415.0

This method includes:

• whole days
• leftover seconds
• microseconds as fractional seconds

That makes it safe for logging durations, computing elapsed time, or converting to minutes and hours afterward.

Converting Differences Between Datetimes

A common pattern is subtracting two datetime objects and then converting the result:

1from datetime import datetime
2
3start = datetime(2025, 1, 1, 9, 0, 0)
4end = datetime(2025, 1, 1, 10, 45, 30)
5
6delta = end - start
7print(delta.total_seconds())

Output:

6330.0

This is cleaner than manually multiplying hours, minutes, and seconds.

Negative Durations

total_seconds() also handles negative timedeltas correctly:

1from datetime import timedelta
2
3delta = timedelta(hours=-1, minutes=-30)
4
5print(delta)
6print(delta.total_seconds())

Output:

-1 day, 22:30:00
-5400.0

The string representation can look surprising because Python normalizes negative timedeltas internally. The method result is often easier to reason about than the printed form.

Integer Seconds vs Fractional Seconds

total_seconds() returns a float, which is useful when microseconds matter:

1from datetime import timedelta
2
3delta = timedelta(seconds=3, microseconds=500000)
4print(delta.total_seconds())

Output:

3.5

If you need an integer, decide whether to truncate, round, or ceil:

1import math
2from datetime import timedelta
3
4delta = timedelta(seconds=3, microseconds=800000)
5
6print(int(delta.total_seconds()))         # 3
7print(round(delta.total_seconds()))       # 4
8print(math.ceil(delta.total_seconds()))   # 4

That choice depends on your business rule. There is no single correct rounding behavior for every application.

Manual Formula

If you ever need the underlying calculation, this is effectively what happens:

1from datetime import timedelta
2
3delta = timedelta(days=1, seconds=5, microseconds=250000)
4
5manual = delta.days * 86400 + delta.seconds + delta.microseconds / 1_000_000
6print(manual)
7print(delta.total_seconds())

In real code, call the method instead of repeating the formula. The built-in method is clearer and less error-prone.

Common Pitfalls

The biggest pitfall is using .seconds and assuming it means total seconds. It does not include whole days, so long durations become wrong silently.

Another trap is forgetting that total_seconds() returns a float. If you pass that value to code expecting an integer number of seconds, decide on truncation or rounding explicitly instead of relying on implicit conversion.

Negative timedeltas also confuse people because their string form is normalized in a way that looks odd at first glance. The numerical result from total_seconds() is usually easier to interpret.

Finally, be careful when subtracting timezone-aware and naive datetimes. If the subtraction itself is wrong, the resulting timedelta will also be wrong, even if the conversion to seconds is correct.

Summary

• Use timedelta.total_seconds() for the full duration in seconds.
• Do not use .seconds when you need total elapsed seconds.
• 'total_seconds() includes days and microseconds.'
• The result is a float, so choose truncation or rounding deliberately if you need an integer.
• Negative timedeltas are supported and often easier to interpret numerically than by string representation.
• When a timedelta comes from datetime subtraction, make sure the original datetimes are compatible first.