pyiso8601: ISO 8601 Parsing for Python




This module parses the most common forms of ISO 8601 date strings (e.g. 2007-01-14T20:34:22+00:00) into datetime objects.

>>> import iso8601
>>> iso8601.parse_date("2007-01-25T12:00:00Z")
datetime.datetime(2007, 1, 25, 12, 0, tzinfo=<iso8601.Utc>)

See the LICENSE file for the license this package is released under.

If you want more full featured parsing look at:

Parsed Formats

You can parse full date + times, or just the date. In both cases a datetime instance is returned but with missing times defaulting to 0, and missing days / months defaulting to 1.


  • YYYY-MM (defaults to 1 for the day)
  • YYYY (defaults to 1 for month and day)


  • hh:mm:ss.nn
  • hhmmss.nn
  • hh:mm (defaults to 0 for seconds)
  • hhmm (defaults to 0 for seconds)
  • hh (defaults to 0 for minutes and seconds)

Time Zones

  • Nothing, will use the default timezone given (which in turn defaults to UTC).
  • Z (UTC)
  • +/-hh:mm
  • +/-hhmm
  • +/-hh

Where it Differs From ISO 8601

Known differences from the ISO 8601 spec:

  • You can use a ” ” (space) instead of T for separating date from time.
  • Days and months without a leading 0 (2 vs 02) will be parsed.
  • If time zone information is omitted the default time zone given is used (which in turn defaults to UTC). Use a default of None to yield naive datetime instances.


To install simply use pip:

pip install iso8601


iso8601.is_iso8601(datestring: str) → bool[source]

Check if a string matches an ISO 8601 format.

Parameters:datestring – The string to check for validity
Returns:True if the string matches an ISO 8601 format, False otherwise
iso8601.parse_date(datestring: str, default_timezone: Optional[datetime.timezone, None] = datetime.timezone.utc) → datetime.datetime[source]

Parses ISO 8601 dates into datetime objects

The timezone is parsed from the date string. However it is quite common to have dates without a timezone (not strictly correct). In this case the default timezone specified in default_timezone is used. This is UTC by default.

  • datestring – The date to parse as a string
  • default_timezone – A datetime tzinfo instance to use when no timezone is specified in the datestring. If this is set to None then a naive datetime object is returned.

A datetime.datetime instance


ParseError when there is a problem parsing the date or constructing the datetime instance.

exception iso8601.ParseError[source]

Raised when there is a problem parsing a date string