Python datetime.replace() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
datetime method

Definition

replace(**fields) returns a new object that is a copy of the original with the given fields changed. Fields you do not pass keep their old values, and the original object is never modified, because datetime objects are immutable.

On a datetime you can change year, month, day, hour, minute, second, microsecond, tzinfo, and fold. replace(tzinfo=...) attaches or removes a zone without converting the clock time; use astimezone() to convert.

datetime.replace() is an instance method of datetime.datetime: call it on an existing object with dot notation, such as moment.replace(...). Import the class first, for example from datetime import datetime. The date and time classes have a method with the same name.

Syntax

Pass only the fields you want to change, as keyword arguments.

python
new = moment.replace(year=2025)
new = moment.replace(hour=0, minute=0, second=0, microsecond=0)
new = moment.replace(tzinfo=timezone.utc)
CallWhat it does
datetime(2024, 3, 15, 10, 30).replace(day=1)Returns datetime.datetime(2024, 3, 1, 10, 30).
datetime(2024, 3, 15, 10, 30).replace(tzinfo=timezone.utc)Returns datetime.datetime(2024, 3, 15, 10, 30, tzinfo=datetime.timezone.utc).
date(2024, 2, 29).replace(year=2025)Raises ValueError: 2025 has no 29 February.

date.replace() accepts only year, month, and day; time.replace() accepts the clock fields, tzinfo, and fold.

Method signatures
python
datetime.replace(year=self.year, month=self.month, day=self.day,
                 hour=self.hour, minute=self.minute, second=self.second,
                 microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)
date.replace(year=self.year, month=self.month, day=self.day)

Parameters

ParameterDescription
year, month, dayNew calendar fields. The resulting date must exist.
hour, minute, second, microsecondNew clock fields in their usual ranges (0-23, 0-59, 0-59, 0-999999).
tzinfoA tzinfo to attach, or None to make the result naive.
foldKeyword-only, 0 or 1, to pick the first or second occurrence of a repeated local hour.

Return Value

Return ValueDescription
datetimeA new object of the same type with the chosen fields replaced.

Python Examples

Example 1 — Change the Year and Truncate to Midnight

Build two new values from one datetime and confirm the original is unchanged.

python
from datetime import datetime

moment = datetime(2024, 3, 15, 10, 30, 45, 123456)
print(moment.replace(year=2025))
print(moment.replace(hour=0, minute=0, second=0, microsecond=0))
print(moment)

How It Works

  1. One field. year=2025 changes only the year; everything else is copied.
  2. Start of day. Zeroing the four clock fields truncates the value to midnight.
  3. Immutable original. moment still prints its old value because replace() returned new objects.

Example 2 — Handle Dates That Do Not Exist

Moving 29 February to another year only works for leap years.

python
from datetime import date

leap_day = date(2024, 2, 29)
for year in (2028, 2025):
    try:
        print(leap_day.replace(year=year))
    except ValueError:
        print(year, "has no February 29")
first_of_month = leap_day.replace(day=1)
print(first_of_month)

How It Works

  1. Valid move. 2028 is a leap year, so 29 February exists there.
  2. Invalid move. 2025 is not a leap year, so the constructor check raises ValueError.
  3. First of the month. replace(day=1) is a quick way to get the month start.

Example 3 — replace(tzinfo=...) Relabels, astimezone() Converts

Attach UTC+05:30 to a UTC value both ways and compare with the original instant.

python
from datetime import datetime, timedelta, timezone

ist = timezone(timedelta(hours=5, minutes=30))
moment = datetime(2024, 3, 15, 10, 30, tzinfo=timezone.utc)

relabelled = moment.replace(tzinfo=ist)
converted = moment.astimezone(ist)
print(relabelled)
print(converted)
print(relabelled == moment, converted == moment)
print(moment.replace(tzinfo=None))

How It Works

  1. Same clock, new zone. replace(tzinfo=ist) keeps 10:30 and only changes the label, which is a different instant.
  2. Real conversion. astimezone() moves the clock to 16:00 so the instant stays the same.
  3. Equality tells them apart. Only the converted value equals the original moment.
  4. Strip the zone. tzinfo=None makes a naive copy with the same clock reading.

Frequently Asked Questions

Use moment.replace(year=2025). It returns a new datetime.
datetime objects are immutable. Assign the result: moment = moment.replace(hour=0).
moment.replace(tzinfo=None) returns a naive copy with the same clock time.
replace() only relabels the zone and keeps the clock time; astimezone() converts the clock time so the instant stays the same.
moment.replace(hour=0, minute=0, second=0, microsecond=0).

Next: datetime.strftime()

Format a date or datetime as text using % codes such as %Y-%m-%d %H:%M.

strftime() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

12 people found this page helpful