Datetime.replace() Function in Python

The datetime.replace() method in Python allows you to modify specific parts of a datetime or date object without changing the original object. Instead, it returns a new modified object with the updated values.

For example, suppose we booked a flight for March 15, 2025, at 10:00 AM, but it got rescheduled to March 20 at 3:30 PM, now instead of creating a new date-time, we can use replace() to change only the day and time while keeping the year and month the same like this:

flight = datetime(2025, 3, 15, 10, 0)
rescheduled_flight = flight.replace(day=20, hour=15, minute=30)

Syntax

datetime_object.replace(year, month, day, hour, minute, second, microsecond, tzinfo)

Parameters:

• year: New year value (1 to 9999)
• month: New month value (1 to 12)
• day: New day value (1 to 31)
• hour: New hour value (0 to 23)
• minute: New minute value (0 to 59)
• second: New second value (0 to 59)
• microsecond: New microsecond value (0 to 999999)
• tzinfo: New timezone info

Return Value: The method returns a new modified datetime or date object with the updated values. The original object remains unchanged.

Note:

• Only existing attributes in the datetime object can be replaced. Attempting to modify an attribute that isn’t present raises an error.
• The original object is not modified; a new object is returned instead.

Examples of Datetime.replace() Function in Python:

Example 1: Modifying the Year in a Date Object

Let's modify the year of the current date while keeping the month and day unchanged.

import datetime  

# Getting the current date
d = datetime.date.today()  
print("Original Date:", todays_date)  

# Replacing the year with 2000
md = todays_date.replace(year=2000)  
print("Modified Date:", modified_date)  

Original Date: 2025-04-01
Modified Date: 2000-04-01

Explanation:

• datetime.date.today() returns the current date (without time).
• todays_date.replace(year=2000) creates a new date object with the year changed to 2000, but the month and day remain the same.
• The original date and the modified date are printed to show the change

Example 2: Attempting to Replace an Invalid Attribute

Trying to change the hour of a date object will cause an error because a date object does not store time information.

import datetime  

# Getting the current date
t = datetime.date.today()  
print("Original Date:", todays_date)  

# Attempting to replace an hour (which does not exist in date objects)
md = todays_date.replace(hour=3)  
print("Modified Date:", modified_date)  

Output:

Traceback (most recent call last): File "/home/6e1aaed34d749f5b15af6dc27ce73a2d.py", line 9, in <module>   modified_date = todays_date.replace(hour=3)TypeError: 'hour' is an invalid keyword argument for this function

Explanation:

• datetime.date.today() returns the current date without any time-related information.
• replace() method does not support modifying the hour for a date object since a date object does not store time.
• This results in an error, as shown in the traceback.

We see an error because the datetime object doesn't have an hour property. Now, let's create a datetime object with an hour and change the time to 03, while also updating the date to 10.

import datetime  

# Getting the current date and time
t = datetime.datetime.now()  
print("Today's date and time:", todays_datetime)  

# Replacing the hour with 3 and day with 10
md = todays_datetime.replace(day=10, hour=3)  
print("Modified date and time:", modified_datetime)  

Today's date and time: 2025-04-01 12:02:28.866357
Modified date and time: 2025-04-10 03:02:28.866357

Explanation:

• datetime.datetime.now() returns the current date and time.
• replace() method is used to modify both the day and the hour in the datetime object.
• Other attributes (minute, second, etc.) remain unchanged.