Home Python Datetime Methods isoformat() Definition isoformat() returns the datetime as an ISO 8601 string: YYYY-MM-DDTHH:MM:SS, followed by .ffffff when microseconds are not zero and by +HH:MM when the value is aware.
sep picks the character between date and time, and timespec chooses how much of the time to show. fromisoformat() parses the result back to an equal datetime, which makes ISO text ideal for JSON, logs, and databases.
datetime.isoformat() is an instance method of datetime.datetime: call it on an existing object with dot notation, such as moment.isoformat(...). Import the class first, for example from datetime import datetime. The date and time classes have a method with the same name.
Syntax Call it with no arguments, or choose a separator and a precision.
text = moment.isoformat()
text = moment.isoformat(sep=" ")
text = moment.isoformat(timespec="minutes") Call What it does datetime(2024, 3, 15, 10, 30).isoformat()Returns '2024-03-15T10:30:00'. datetime(2024, 3, 15, 10, 30, 0, 500).isoformat(" ")Returns '2024-03-15 10:30:00.000500'. datetime(2024, 3, 15, 10, 30, tzinfo=timezone.utc).isoformat(timespec="minutes")Returns '2024-03-15T10:30+00:00'.
str(moment) is the same as moment.isoformat(sep=" "). date.isoformat() takes no arguments and returns YYYY-MM-DD.
Method signatures datetime.isoformat(sep='T', timespec='auto')
date.isoformat()
time.isoformat(timespec='auto')
# timespec: 'auto', 'hours', 'minutes', 'seconds', 'milliseconds', 'microseconds' Parameters Parameter Description sep Optional. One character placed between the date and the time. Default 'T'. timespec Optional (3.6+). 'auto' (default) shows microseconds only when non-zero; the other values fix the precision. Extra digits are cut off, not rounded.
Return Value Return Value Description str The ISO 8601 text, including the UTC offset for aware values.
Important
An unknown timespec raises ValueError, and a sep longer than one character raises TypeError. Because 'auto' drops .000000, output width can change between values; pass timespec="microseconds" for fixed-width text.
Python Examples 1. Separators 2. timespec values 3. Offsets and round trips Example 1 — Produce ISO Text with Different Separators Print the default form, a space-separated form, str(), and a date-only form.
from datetime import date, datetime
moment = datetime(2024, 3, 15, 10, 30, 45)
print(moment.isoformat())
print(moment.isoformat(sep=" "))
print(str(moment))
print(date(2024, 3, 15).isoformat()) 2024-03-15T10:30:45
2024-03-15 10:30:45
2024-03-15 10:30:45
2024-03-15 How It Works Default T. Without arguments, the date and time are joined by the letter T.Custom separator. sep=" " gives a friendlier form that many databases also accept.str() matches. Printing a datetime uses the space-separated ISO form.Date objects. date.isoformat() returns just YYYY-MM-DD.Example 2 — Compare Every timespec Value Format one moment with each timespec option, right-aligning the option names in a 12-character column.
from datetime import datetime
moment = datetime(2024, 3, 15, 10, 30, 45, 123456)
for spec in ("auto", "hours", "minutes", "seconds", "milliseconds", "microseconds"):
print(f"{spec:>12}: {moment.isoformat(timespec=spec)}") auto: 2024-03-15T10:30:45.123456
hours: 2024-03-15T10
minutes: 2024-03-15T10:30
seconds: 2024-03-15T10:30:45
milliseconds: 2024-03-15T10:30:45.123
microseconds: 2024-03-15T10:30:45.123456 How It Works auto keeps everything. The microseconds are non-zero, so 'auto' shows all six digits.Coarser specs. 'hours', 'minutes', and 'seconds' stop after that unit.Truncated, not rounded. 'milliseconds' keeps .123 from 123456 microseconds by cutting the last three digits.Example 3 — Write Offsets and Parse Them Back Format an aware datetime at UTC+05:45, a UTC midnight, and an aware time, and check the round trip.
from datetime import datetime, timedelta, timezone
nepal = timezone(timedelta(hours=5, minutes=45))
moment = datetime(2024, 1, 1, 0, 0, 5, tzinfo=nepal)
text = moment.isoformat()
print(text)
print(datetime(2024, 1, 1, tzinfo=timezone.utc).isoformat())
print(datetime.fromisoformat(text) == moment)
print(moment.timetz().isoformat()) 2024-01-01T00:00:05+05:45
2024-01-01T00:00:00+00:00
True
00:00:05+05:45 How It Works Offset suffix. Aware values end with the UTC offset, here +05:45.UTC is +00:00. ISO text from Python writes UTC as +00:00, not Z.Lossless. fromisoformat() rebuilds an equal aware datetime from the text.Aware times too. The timetz() part keeps its offset in time.isoformat().Frequently Asked Questions How do I convert a datetime to an ISO 8601 string? Call moment.isoformat(). For a space instead of T, use moment.isoformat(sep=" ").
How do I get milliseconds instead of microseconds? Use moment.isoformat(timespec="milliseconds"). Digits beyond milliseconds are truncated.
How do I output Z instead of +00:00? isoformat() always writes +00:00. Use moment.isoformat().replace("+00:00", "Z") for a UTC value.
Why are the microseconds sometimes missing? With the default timespec="auto", a value whose microsecond is 0 omits the fraction. Pass timespec="microseconds" to always include it.
How do I parse the text back? Use datetime.fromisoformat(text). Output of isoformat() is accepted by every Python version since 3.7.
Next: date.isoweekday() Return the day of the week as 1 (Monday) to 7 (Sunday).
isoweekday() → About the author Developer, cloud engineer, and technical writer
I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.
9 people found this page helpful
Helpful Share Copy link Suggestion