datetime.isoformat(sep='T', timespec='auto')

Return a string representing the date and time in ISO 8601 format:

If utcoffset() does not return None, a string is appended, giving the UTC offset:

  • YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], if microsecond is not 0

  • YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]], if microsecond is 0


>>> from datetime import datetime, timezone
>>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
>>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()

The optional argument sep (default 'T') is a one-character separator, placed between the date and time portions of the result. For example:

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     """A time zone with an arbitrary, constant -06:39 offset."""
...     def utcoffset(self, dt):
...         return timedelta(hours=-6, minutes=-39)
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
>>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()

The optional argument timespec specifies the number of additional components of the time to include (the default is 'auto'). It can be one of the following:

  • 'auto': Same as 'seconds' if microsecond is 0, same as 'microseconds' otherwise.

  • 'hours': Include the hour in the two-digit HH format.

  • 'minutes': Include hour and minute in HH:MM format.

  • 'seconds': Include hour, minute, and second in HH:MM:SS format.

  • 'milliseconds': Include full time, but truncate fractional second part to milliseconds. HH:MM:SS.sss format.

  • 'microseconds': Include full time in HH:MM:SS.ffffff format.


Excluded time components are truncated, not rounded.

ValueError will be raised on an invalid timespec argument:

>>> from datetime import datetime
>>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)
>>> dt.isoformat(timespec='microseconds')

New in version 3.6: Added the timespec argument.

Related Reading

datetime — Basic date and time types