The datetime module is Python's standard library for dates, clock times, and durations. Nothing to install: import a class, build an object such as datetime(2024, 3, 15, 10, 30), then compare, subtract, format, or parse it.
Import the classes you need by name. This is the style used in every example on this site:
Python
from datetime import date, datetime, time, timedelta, timezone
day = date(2024, 3, 15) # a calendar day
clock = time(10, 30) # a clock time
moment = datetime.combine(day, clock) # 2024-03-15 10:30:00
later = moment + timedelta(days=1, hours=2) # arithmetic with durations
aware = moment.replace(tzinfo=timezone.utc) # attach a time zone
print(later, aware.isoformat())
The module and the class share a name.
After import datetime, write datetime.datetime.now(). After from datetime import datetime, write datetime.now(). Mixing the two styles in one file causes AttributeError.
A duration stored as days, seconds, and microseconds
timedelta(hours=36)
tzinfo
Abstract base class for time zone rules
Subclass it, or use timezone
timezone
A ready-made tzinfo with a fixed UTC offset
timezone(timedelta(hours=5, minutes=30))
For real zones with daylight saving rules, Python 3.9+ adds zoneinfo (on Windows it needs the tzdata package), so these examples use fixed offsets.
Concept
Naive vs Aware Objects
A datetime is aware when its tzinfo returns an offset from utcoffset(); it names one exact instant. It is naive when tzinfo is None: just a wall-clock reading in an unknown zone.
timestamp(), astimezone(), and fromtimestamp() without tz treat naive values as the machine's local time, so results differ between computers. Store aware UTC values and convert only for display. Subtracting or ordering naive against aware raises TypeError; == returns False.
Reference
Format Codes Cheat Sheet
Used by strftime() and strptime(). The last column shows the result for datetime(2024, 3, 15, 9, 5, 7, 42000, tzinfo=timezone(timedelta(hours=5, minutes=30))) with the default C/English locale:
Code
Meaning
Result
%Y
Year with century
2024
%y
Year without century, 2 digits
24
%m
Month, 2 digits
03
%d
Day of the month, 2 digits
15
%H
Hour, 24-hour clock
09
%I
Hour, 12-hour clock
09
%p
AM or PM (locale)
AM
%M
Minute
05
%S
Second
07
%f
Microsecond, 6 digits
042000
%a
Weekday, short name (locale)
Fri
%A
Weekday, full name (locale)
Friday
%b
Month, short name (locale)
Mar
%B
Month, full name (locale)
March
%j
Day of the year, 3 digits
075
%w
Weekday number, Sunday is 0
5
%U
Week of the year, Sunday first
10
%W
Week of the year, Monday first
11
%z
UTC offset as +HHMM (empty if naive)
+0530
%Z
Time zone name (empty if naive)
UTC+05:30
%%
A literal percent sign
%
%a, %A, %b, %B, and %p follow the locale. Avoid platform-only codes such as %-d and %#d.
Concept
ISO 8601 Text and Epoch Timestamps
ISO 8601 writes the biggest unit first, 2024-03-15T10:30:00+05:30, so it sorts correctly as text. isoformat() writes it and fromisoformat() reads it back.
A POSIX timestamp counts seconds since 1970-01-01 00:00:00 UTC: 1710498645 is 2024-03-15 10:30:45 UTC. timestamp() returns it as a float; fromtimestamp(ts, tz=timezone.utc) turns it back. Divide JavaScript milliseconds by 1000 first.
The standard library module for dates and times. Its classes date, time, datetime, timedelta, tzinfo, and timezone let you create, compare, format, parse, and do arithmetic with dates.
An aware datetime has a tzinfo with a UTC offset, so it marks one exact instant. A naive one has no offset, and ordering or subtracting it against an aware value raises TypeError.
After import datetime, the name datetime is the module, so you write datetime.datetime.now(). After from datetime import datetime, it is the class, so you write datetime.now().
No. utcnow() and utcfromtimestamp() are deprecated since Python 3.12. Use datetime.now(timezone.utc) and datetime.fromtimestamp(ts, tz=timezone.utc) for aware UTC values.
strftime() or isoformat() write text; strptime() or fromisoformat() parse it. ISO 8601 text such as 2024-03-15T10:30:00+05:30 is the safest format to store.