Quick answer: Use timedelta.total_seconds() when you need the complete duration in seconds. It includes days and microseconds, unlike the .seconds attribute, which is only one component of the normalized duration. Choose an explicit rounding policy before converting the resulting float to an integer.
A Python timedelta represents a duration, not a calendar date. To convert the whole duration to seconds, use total_seconds(). It includes days, seconds, and microseconds in one result.
This method is safer than reading the seconds attribute directly. The seconds attribute is only the seconds portion inside one day, while total_seconds() returns the complete duration.
The official Python timedelta.total_seconds documentation defines the method. The CPython datetime source shows the pure-Python reference implementation.
Use total_seconds
Create a duration and call total_seconds() to get a floating-point number of seconds.
from datetime import timedelta
duration = timedelta(minutes=2, seconds=30)
seconds = duration.total_seconds()
print(seconds)
This prints 150.0. The result is a float because microseconds can produce fractional seconds.
Use this value for elapsed time, timeouts, metrics, logs, and comparisons where seconds are the expected unit.
Include Days Correctly
total_seconds() includes the day portion of the duration.
from datetime import timedelta
duration = timedelta(days=1, seconds=30)
print(duration.seconds)
print(duration.total_seconds())
The seconds attribute prints only 30. The full duration is 86430.0 seconds.
This is the most common mistake when converting timedeltas. Use total_seconds() unless you intentionally need the seconds field within one day.
Handle Microseconds
Microseconds appear as the decimal part of the result.
from datetime import timedelta
duration = timedelta(seconds=1, microseconds=250_000)
print(duration.total_seconds())
print(round(duration.total_seconds(), 2))
This returns 1.25. Rounding is optional and should match how precise the output needs to be.
For storage or exact integer math, consider whether milliseconds or microseconds are a better unit than floating-point seconds.
Convert To Integer Seconds
If an API expects whole seconds, choose the rounding behavior deliberately.
from datetime import timedelta
import math
duration = timedelta(seconds=3, microseconds=700_000)
seconds = duration.total_seconds()
print(int(seconds))
print(round(seconds))
print(math.ceil(seconds))
int() truncates toward zero, round() rounds to the nearest integer, and ceil() rounds up.
For timeouts, rounding up can avoid ending too early. For elapsed reporting, rounding to the nearest value may be more natural.
Measure Elapsed Time
Subtracting two datetime values produces a timedelta.
from datetime import datetime, timezone
started = datetime(2026, 7, 9, 8, 0, tzinfo=timezone.utc)
finished = datetime(2026, 7, 9, 8, 2, 30, tzinfo=timezone.utc)
elapsed = finished - started
print(elapsed.total_seconds())
Use aware datetime values when measuring events across systems or time zones.
For a stopwatch inside one running process, time.perf_counter() is often better because it is designed for elapsed time measurement.
Convert Negative Durations
A timedelta can be negative, and total_seconds() preserves the sign.
from datetime import timedelta
late_by = timedelta(seconds=-45)
print(late_by.total_seconds())
print(abs(late_by).total_seconds())
Negative durations are useful when comparing deadlines, schedules, or offsets. Decide whether the sign matters before applying abs().
Avoid Attribute Confusion
A timedelta stores normalized fields: days, seconds, and microseconds. The seconds attribute is not the total duration. It is the leftover seconds after days have been separated.
That is why a duration of two days and five seconds has days == 2, seconds == 5, and total_seconds() == 172805.0. Reading only seconds loses the day portion.
The same idea applies to microseconds. A duration can be shorter than one second, longer than many days, or negative. total_seconds() is the method that combines the fields into one seconds value.
Pick Units For The Next System
Seconds are common, but they are not always the best unit. Some APIs expect milliseconds, some databases store microseconds, and some monitoring systems prefer floating-point seconds. Convert only after checking the receiving system.
For milliseconds, multiply total_seconds() by 1000. For microseconds, multiply by 1_000_000. If the destination needs an integer, choose whether to round, floor, or ceil based on the business rule.
For very long durations, floating-point seconds can lose microsecond precision. That rarely matters for ordinary elapsed-time reporting, but it can matter for exact archival or scientific data. In those cases, store days and microseconds separately or use an integer unit.
Keep Duration And Timestamp Separate
A timestamp answers “when did this happen?” A duration answers “how long did it take?” A timedelta converted to seconds is a duration, not a Unix timestamp.
If you need Unix time, convert a datetime with timestamp-related tools. If you need elapsed time between two moments, subtract the datetimes and call total_seconds() on the resulting duration.
Keeping that distinction clear prevents bugs where elapsed seconds are accidentally stored as absolute dates or where timestamps are treated as short durations.
Use A Short Conversion Checklist
Before converting, ask three questions. Do you need the full duration or only one displayed component? Does the next system expect seconds, milliseconds, or microseconds? Should fractional seconds be preserved, rounded, truncated, or rounded up?
Answering those questions first keeps the code small and prevents hidden assumptions. Most bugs in this area come from choosing the wrong attribute or rounding too early.
The practical rule is to use total_seconds() for the full duration, avoid the seconds attribute for conversion, and pick a rounding policy when an integer is required.
That keeps duration math clear and avoids hidden day or microsecond mistakes.
Use total_seconds() For The Full Duration
A timedelta stores days, seconds, and microseconds as one normalized duration. total_seconds() combines those components into a floating-point number, so a duration longer than one day is not accidentally reduced to the seconds remaining within a day.
Do Not Confuse .seconds With The Total
The seconds attribute is the seconds component after days have been separated. It is useful when inspecting the normalized representation, but it is not the total elapsed time. A duration of one day and two seconds has seconds equal to two while total_seconds() is much larger.
Choose A Whole-Second Policy
total_seconds() can contain a fractional part because timedeltas preserve microseconds. int() truncates toward zero, while floor, ceiling, and round express different business rules, especially for negative durations. Pick the rule that matches billing, display, scheduling, or storage semantics.
Keep Duration Separate From Timestamp
A timedelta describes a length of time, while datetime values identify instants. Add a duration to a datetime when you need another instant; do not serialize a duration as though it were a Unix timestamp or infer a timezone from it.
Test Negative And Small Values
Test days, hours, microseconds, zero, negative intervals, and values near a rounding boundary. Assert the chosen numeric tolerance and conversion policy so a later change from float to integer does not silently change elapsed-time meaning.
The official timedelta.total_seconds() reference explains the complete conversion. The timedelta documentation defines normalized components. Related guidance includes timestamps and time-boundary tests.
For related time boundaries, compare timestamp conversion, current datetimes, and duration tests when keeping instants separate from intervals.
Frequently Asked Questions
How do I convert a Python timedelta to seconds?
Call duration.total_seconds() to get the total duration as a floating-point number of seconds.
Why is timedelta.seconds not the total duration?
The seconds attribute is only the seconds portion after days have been separated; use total_seconds() when days must be included.
How do I get whole seconds?
Choose an explicit policy such as int(), round(), floor, or ceiling based on the application rather than silently discarding fractional seconds.
Is a timedelta the same as a Unix timestamp?
No. A timedelta is a duration between instants, while a timestamp identifies an instant on a time scale.