Python datetime.timedelta()
In Python, the datetime.timedelta()
method returns a timedelta
object that represents the total difference between two dates, times, or datetime
objects. It allows for straightforward time calculations that are essential in scheduling, logging, and time series analysis.
Syntax
import datetime
datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)
Parameters:
days
(Optional): Number of days.seconds
(Optional): Number of seconds.microseconds
(Optional): Number of microseconds.milliseconds
(Optional): Number of milliseconds.minutes
(Optional): Number of minutes.hours
(Optional): Number of hours.weeks
(Optional): Number of weeks.
Return value:
Returns a timedelta
object that represents the difference between two dates, times, or datetime
objects.
Example 1: Adding Days to a Date
This example uses the datetime.timedelta()
method to add days to a date:
import datetime# Assign the current datetimetoday = datetime.datetime.now()print("Today's Date:", today)# Add 5 daysfuture_date = today + datetime.timedelta(days=5)print("Future Date (after 5 days):", future_date)
Here is the output:
Today's Date: 2025-06-09 05:43:08.228494Future Date (after 5 days): 2025-06-14 05:43:08.228494
Note: Since the current
datetime
is fetched, the output may vary each time the code is run.
Example 2: Working with Hours and Minutes
This example uses the datetime.timedelta()
method to add 3 hours and 30 minutes to a date:
import datetimestart_time = datetime.datetime(2025, 6, 8, 14, 0)print("Start Time:", start_time)# Add 3 hours and 30 minutesnew_time = start_time + datetime.timedelta(hours=3, minutes=30)print("New Time:", new_time)
Here is the output:
Start Time: 2025-06-08 14:00:00New Time: 2025-06-08 17:30:00
Codebyte Example: Using Expressions in .timedelta()
This codebyte example uses an expression in the datetime.timedelta()
method to add 60 days to a date:
Frequently Asked Questions
1. Can you subtract timedelta
from a datetime
?
Yes. You can subtract timedelta
objects from datetime
objects:
import datetimeyesterday = datetime.datetime.now() - datetime.timedelta(days=1)print(yesterday)
Here is the output:
2025-06-08 05:46:41.110871
2. How can I convert timedelta
to total seconds?
Use the .total_seconds()
method to convert timedelta
to total seconds:
import datetimedelta = datetime.timedelta(days=1, hours=2)print(delta.total_seconds())
Here is the output:
93600.0
3. Can timedelta handle negative durations?
Yes. You can subtract a future date from an earlier date, resulting in a negative timedelta
.
Contribute to Docs
- Learn more about how to get involved.
- Edit this page on GitHub to fix an error or make an improvement.
- Submit feedback to let us know how we can improve Docs.
Learn Python on Codecademy
- Career path
Computer Science
Looking for an introduction to the theory behind programming? Master Python while learning data structures, algorithms, and more!Includes 6 CoursesWith Professional CertificationBeginner Friendly75 hours - Course
Learn Python 3
Learn the basics of Python 3.12, one of the most powerful, versatile, and in-demand programming languages today.With CertificateBeginner Friendly23 hours