Skip to main content

Simple module to parse ISO 8601 dates

Project description

Simple module to parse ISO 8601 dates

pip install iso8601




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.



  1. poetry install

  2. poetry run nox

Note that you need all the pythons installed to perform a tox run (see below). pyenv helps hugely, use pyenv install for the versions you need then use ‘pyenv local version …’ to link them in (the tox-pyenv plugin will pick them up).

Alternatively, to test only with your current python:

  1. poetry install

  2. pytest


  1. just prepare-release

  2. just do-release

Supported Python Versions

Tested against:

  • Python 3.7

  • Python 3.8

  • Python 3.9

  • Python 3.10

  • Python 3.11

  • Python 3.12

  • PyPy 3

Python 3 versions < 3.7 are untested but should work.



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

iso8601-2.1.0.tar.gz (6.5 kB view hashes)

Uploaded Source

Built Distribution

iso8601-2.1.0-py3-none-any.whl (7.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page