Python datetime: Dates, Times, Timedeltas, and Timezones

The Two Core Types: date and datetime

The datetime module gives you four things worth knowing: date, time, datetime, and timedelta. The first three are what they sound like; the fourth is a span of time.

from datetime import date, datetime, timedelta

today = date.today()
now = datetime.now()

print(today)
print(now)
print(type(today), type(now))

A date represents a day - year, month, day - with no clock attached. A datetime is a date plus a time. If you don't need the clock, date is the tidier choice.

Creating Specific Dates

Construct directly:

from datetime import date, datetime

launch = date(2026, 1, 15)
meeting = datetime(2026, 1, 15, 14, 30)

print(launch)
print(meeting)

Arguments are year, month, day for date, and up to year, month, day, hour, minute, second, microsecond for datetime.

Reading Fields

Every date/datetime has attributes:

from datetime import datetime

now = datetime(2026, 4, 20, 9, 30, 15)

print(now.year, now.month, now.day)
print(now.hour, now.minute, now.second)
print(now.weekday())        # 0 = Monday, 6 = Sunday
print(now.isoweekday())     # 1 = Monday, 7 = Sunday
print(now.isoformat())

isoformat() is your friend for machine-readable output - it produces something like "2026-04-20T09:30:15" that other systems can parse unambiguously.

Formatting With strftime

For human-readable output, .strftime(fmt) turns a date or datetime into a formatted string:

from datetime import datetime

now = datetime(2026, 4, 20, 9, 30)

print(now.strftime("%Y-%m-%d"))          # 2026-04-20
print(now.strftime("%d %B %Y"))          # 20 April 2026
print(now.strftime("%I:%M %p"))          # 09:30 AM
print(now.strftime("%A, %d %b"))         # Monday, 20 Apr

The format codes most often worth remembering:

• %Y - 4-digit year (2026)
• %m - month number, zero-padded (04)
• %d - day of month, zero-padded (20)
• %H / %I - hour, 24/12 hour format
• %M - minute
• %S - second
• %A / %a - weekday name full / abbreviated (Monday / Mon)
• %B / %b - month name full / abbreviated (April / Apr)
• %p - AM/PM

You don't need to memorize them; bookmark a reference and look them up when you need one.

Parsing With strptime

The reverse direction: take a string with a known shape and turn it into a datetime:

from datetime import datetime

text = "2026-04-20 09:30"
parsed = datetime.strptime(text, "%Y-%m-%d %H:%M")

print(parsed)
print(parsed.year, parsed.hour)

The format string must match the input exactly. If it doesn't, strptime raises ValueError.

For ISO-8601 strings (the machine-readable standard), there's a simpler shortcut in modern Python:

from datetime import datetime

d = datetime.fromisoformat("2026-04-20T09:30:00")
print(d)

If you're dealing with random formats, the external dateutil package (pip install python-dateutil) has a forgiving parser.parse() that takes a reasonable guess.

Arithmetic With timedelta

To do math on dates, use timedelta for the difference or offset:

from datetime import date, datetime, timedelta

today = date(2026, 4, 20)
next_week = today + timedelta(days=7)
yesterday = today - timedelta(days=1)

print(next_week, yesterday)

# Subtracting two dates gives you a timedelta.
gap = date(2027, 1, 1) - today
print(gap)
print(gap.days)

timedelta arguments: days, seconds, microseconds, milliseconds, minutes, hours, weeks. No months or years - months are variable length. For month/year math, use dateutil.relativedelta:

from dateutil.relativedelta import relativedelta
from datetime import date

today = date.today()
next_quarter = today + relativedelta(months=3)
print(next_quarter)

Timezones: Naive vs Aware

A datetime without timezone info is naive - Python doesn't know what timezone it represents. Time math on naive datetimes is fine as long as you stay within one logical timezone; the trouble starts the moment data from different zones meets.

An aware datetime carries timezone info with it. Attach a timezone explicitly:

from datetime import datetime, timezone, timedelta

utc_now = datetime.now(timezone.utc)
print(utc_now)
print(utc_now.tzinfo)

Python 3.9 added the zoneinfo module for named timezones (using the system's IANA database):

from datetime import datetime
from zoneinfo import ZoneInfo

now_tokyo = datetime.now(ZoneInfo("Asia/Tokyo"))
now_ny = datetime.now(ZoneInfo("America/New_York"))

print(now_tokyo)
print(now_ny)
print(now_tokyo - now_ny)   # timedelta is zero-ish - same moment, different clocks

Convert between zones with .astimezone():

from datetime import datetime
from zoneinfo import ZoneInfo

utc = datetime(2026, 4, 20, 12, 0, tzinfo=ZoneInfo("UTC"))
berlin = utc.astimezone(ZoneInfo("Europe/Berlin"))

print(utc)
print(berlin)

A rule worth committing to memory: store datetimes in UTC, convert to local zones only at display time. That one habit prevents most timezone bugs.

Timestamps

A Unix timestamp is the number of seconds since 1970-01-01 UTC. Python converts easily:

from datetime import datetime, timezone

now = datetime.now(timezone.utc)
ts = now.timestamp()

print(ts)
print(datetime.fromtimestamp(ts, tz=timezone.utc))

Timestamps are useful for comparisons, sorting, and interop with other systems. For human-facing output, convert back to a datetime first.

Measuring How Long Something Takes

For quick timings, subtract two datetimes:

from datetime import datetime
import time

start = datetime.now()
time.sleep(0.2)
elapsed = datetime.now() - start

print(elapsed.total_seconds())

For more serious performance measurement, use time.perf_counter() - it has sub-microsecond resolution and is immune to system clock changes. datetime.now() is fine for "how long did this API call take" style numbers.

Patterns You'll Reuse

from datetime import date, datetime, timedelta, timezone

# Today's date in ISO format
print(date.today().isoformat())

# Age in years (roughly - not exact across leap years)
dob = date(1990, 7, 15)
days_old = (date.today() - dob).days
print(days_old // 365, "years old")

# Start of current hour in UTC
now = datetime.now(timezone.utc)
start_of_hour = now.replace(minute=0, second=0, microsecond=0)
print(start_of_hour)

# Seven days ago
print(date.today() - timedelta(days=7))

What to Take Away

• date, datetime, and timedelta cover 90% of needs.
• Use ISO-8601 for machine-readable; strftime for human-readable.
• Store in UTC; convert at display time.
• Use zoneinfo for named timezones.
• For months and years, reach for dateutil.relativedelta.

One more tool for your real-world toolkit: regular expressions, up next.