Python datetime.isoformat() Method

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

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.

python
text = moment.isoformat()
text = moment.isoformat(sep=" ")
text = moment.isoformat(timespec="minutes")
CallWhat 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
python
datetime.isoformat(sep='T', timespec='auto')
date.isoformat()
time.isoformat(timespec='auto')
# timespec: 'auto', 'hours', 'minutes', 'seconds', 'milliseconds', 'microseconds'

Parameters

ParameterDescription
sepOptional. One character placed between the date and the time. Default 'T'.
timespecOptional (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 ValueDescription
strThe ISO 8601 text, including the UTC offset for aware values.

Python Examples

Example 1 — Produce ISO Text with Different Separators

Print the default form, a space-separated form, str(), and a date-only form.

python
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())

How It Works

  1. Default T. Without arguments, the date and time are joined by the letter T.
  2. Custom separator. sep=" " gives a friendlier form that many databases also accept.
  3. str() matches. Printing a datetime uses the space-separated ISO form.
  4. 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.

python
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)}")

How It Works

  1. auto keeps everything. The microseconds are non-zero, so 'auto' shows all six digits.
  2. Coarser specs. 'hours', 'minutes', and 'seconds' stop after that unit.
  3. 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.

python
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())

How It Works

  1. Offset suffix. Aware values end with the UTC offset, here +05:45.
  2. UTC is +00:00. ISO text from Python writes UTC as +00:00, not Z.
  3. Lossless. fromisoformat() rebuilds an equal aware datetime from the text.
  4. Aware times too. The timetz() part keeps its offset in time.isoformat().

Frequently Asked Questions

Call moment.isoformat(). For a space instead of T, use moment.isoformat(sep=" ").
Use moment.isoformat(timespec="milliseconds"). Digits beyond milliseconds are truncated.
isoformat() always writes +00:00. Use moment.isoformat().replace("+00:00", "Z") for a UTC value.
With the default timespec="auto", a value whose microsecond is 0 omits the fraction. Pass timespec="microseconds" to always include it.
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

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.

9 people found this page helpful