Replacing parts of a datetime

Replacing parts of a datetime with the replace() method is one of the cleanest ways in Python to create a modified copy of a datetime (or date) object while keeping most fields unchanged. Instead of manually reconstructing the object with datetime(year, month, day, ...) and risking errors with time components, replace() lets you update only the fields you care about — year, month, day, hour, minute, second, microsecond, or tzinfo — in a single, readable call. In 2026, this method remains essential for date/time manipulation in data pipelines, scheduling, logging, reporting, and API handling — especially when adjusting timestamps, normalizing dates, or shifting events without losing precision.

Here’s a complete, practical guide to using replace(): syntax, common use cases, real-world patterns, time zone handling, pandas/Polars equivalents, and modern best practices with type hints, safety, and performance.

The replace() method returns a new datetime object with only the specified fields changed — all others remain identical.


from datetime import datetime

dt = datetime(2022, 3, 14, 13, 23, 45)

# Replace date parts only — time stays the same
new_dt = dt.replace(year=2023, month=4, day=15)
print(new_dt)   # 2023-04-15 13:23:45

# Change time only — date stays the same
evening = dt.replace(hour=18, minute=0, second=0)
print(evening)  # 2022-03-14 18:00:00

# Microsecond precision
precise = dt.replace(microsecond=123456)
print(precise)  # 2022-03-14 13:23:45.123456

Real-world pattern: normalizing or shifting timestamps in data processing — very common in logs, event data, financial records, or user activity.


# Normalize all events to start of day
events = [
    datetime(2026, 2, 10, 14, 30),
    datetime(2026, 2, 10, 9, 15),
    datetime(2026, 2, 11, 23, 59)
]

normalized = [event.replace(hour=0, minute=0, second=0, microsecond=0) for event in events]
print(normalized)
# [datetime.datetime(2026, 2, 10, 0, 0), ...]

Time zone replacement — update tzinfo without changing local time.


from zoneinfo import ZoneInfo

naive_dt = datetime(2026, 2, 10, 14, 30)
utc_dt = naive_dt.replace(tzinfo=ZoneInfo("UTC"))
ny_dt = naive_dt.replace(tzinfo=ZoneInfo("America/New_York"))

print(utc_dt)   # 2026-02-10 14:30:00+00:00
print(ny_dt)    # 2026-02-10 14:30:00-05:00

Best practices make replace() safe, readable, and performant. Use keyword arguments only — replace(year=2023, month=4) — positional args are error-prone. Prefer replace() over manual datetime(...) reconstruction — preserves time fields automatically. For large DataFrames, use pandas vectorized .dt.replace() or Polars — df['ts'] = df['ts'].dt.replace(year=2023) is fast and clean. Modern tip: use Polars for huge timestamp columns — pl.col("ts").dt.replace(year=2023) is 10–100× faster than pandas apply. Add type hints — datetime.datetime — improves readability and mypy checks. Handle invalid replacements — replace(day=31, month=2) raises ValueError; wrap in try/except when user input is involved. Use replace() with timedelta for relative shifts — dt.replace(hour=0) + timedelta(days=1) for next day start. Avoid overusing in tight loops — vectorize when possible. Combine with strftime() — dt.replace(hour=0).strftime("%Y-%m-%d") for day-only strings.

replace() gives precise, partial updates to dates and times — no need to rebuild the entire object. In 2026, use keyword args, vectorize in pandas/Polars, handle time zones, and add type hints for safety. Master replace(), and you’ll adjust timestamps, normalize dates, and shift events cleanly and correctly — without losing data or introducing bugs.

Next time you need to change just the year, hour, or timezone of a datetime — reach for replace(). It’s Python’s cleanest way to say: “Keep most of this moment, but update these parts.”

Generating content...