Python datetime fromisoformat() Method

The fromisoformat() method in Python’s datetime module parses a date_string in ISO 8601 format and returns a datetime object.

ISO 8601 Format

Different cultures around the world have their own conventions for formatting dates. For example, the United States typically uses the month-day-year format (01-05-2024), while many European countries use the day-month-year format (05-01-2024). These variations can lead to miscommunication, especially in international contexts.

To address this, the International Organization for Standardization (ISO) created the ISO 8601 standard. This standard establishes a clear and unambiguous date and time format, with components arranged from most significant to least:

YYYY-MM-DDTHH:MM:SS.mmmmmm

Syntax

datetime.fromisoformat(date_string)

Parameters

ParameterConditionDescription
date_stringRequiredA string representing a date in ISO 8601 format.
This string can represent either a date, a date with time, or a date with time and timezone information.

Return Value

The fromisoformat() method returns a datetime object corresponding to a date_string in ISO 8601 format, with the following exceptions:

  • Time zone offsets may have fractional seconds.
  • The T separator may be replaced by any single unicode character.
  • Fractional hours and minutes are not supported.
  • Reduced precision dates are not currently supported (YYYY-MM, YYYY).
  • Extended date representations are not currently supported (±YYYYYY-MM-DD).
  • Ordinal dates are not currently supported (YYYY-OOO).

Examples

Here are some examples demonstrating how to use fromisoformat():

from datetime import datetime

# Parse a simple date
date_only = datetime.fromisoformat('2023-04-01')
print(date_only)
# Output: 2023-04-01 00:00:00
# Parse a datetime without timezone
datetime_no_tz = datetime.fromisoformat('2023-04-01T12:34:56.789012')
print(datetime_no_tz)
# Output: 2023-04-01 12:34:56.789012
# Parse a datetime with timezone
datetime_with_tz = datetime.fromisoformat('2023-04-01T12:34:56.789012-05:00')
print(datetime_with_tz)
# Output: 2023-04-01 12:34:56.789012-05:00

Prior to Python 3.11, the fromisoformat() method had more limited capabilities in the types of ISO 8601 formats it could understand. It primarily supported only the formats that could be generated by the isoformat() method.

However, this has been expanded. Now, the fromisoformat() method support a variety of ISO 8601 formats. Let’s illustrate this with some examples:

# Parse a simple date
dt = datetime.fromisoformat('2024-11-04')
print(dt)
# Output: 2024-11-04 00:00:00
# Parse a simple date without delimeters
dt = datetime.fromisoformat('20241104')
print(dt)
# Output: 2024-11-04 00:00:00
# Parse a datetime with hours, minutes, and seconds
dt = datetime.fromisoformat('2024-11-04T00:05:23')
print(dt)
# Output: 2024-11-04 00:05:23
# Parse a datetime with UTC timezone (Z)
dt = datetime.fromisoformat('2024-11-04T00:05:23Z')
print(dt)
# Output: 2024-11-04 00:05:23+00:00
# Parse a datetime without delimeters
dt = datetime.fromisoformat('20241104T000523')
print(dt)
# Output: 2024-11-04 00:05:23
# Parse a datetime with week number
dt = datetime.fromisoformat('2024-W01-2T00:05:23.283')
print(dt)
# Output: 2024-01-02 00:05:23.283000
# Parse a datetime with microseconds
dt = datetime.fromisoformat('2024-11-04 00:05:23.283')
print(dt)
# Output: 2024-11-04 00:05:23.283000
# Parse a datetime with microseconds and UTC timezone
dt = datetime.fromisoformat('2024-11-04 00:05:23.283+00:00')
print(dt)
# Output: 2024-11-04 00:05:23.283000+00:00
# Parse a datetime with timezone offset
dt = datetime.fromisoformat('2024-11-04T00:05:23+04:00')
print(dt)
# Output: 2024-11-04 00:05:23+04:00