Install & Compatibility
Where this runs
tested against v2.3.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse_datetime
✓ from ciso8601 import parse_datetime
parse_datetime_as_naive
✓ from ciso8601 import parse_datetime_as_naive
Use this to parse timezone-aware strings as naive datetimes, ignoring timezone information, which can be faster.
parse_rfc3339
✓ from ciso8601 import parse_rfc3339
For strict RFC 3339 parsing.
This quickstart demonstrates basic parsing of ISO 8601 strings, including naive and timezone-aware datetimes. It also shows how to explicitly parse as naive, ignoring timezone information, and how to use the strict RFC 3339 parser.
import ciso8601
# Parse a naive datetime string
date_str_naive = "2023-10-27T10:00:00"
dt_naive = ciso8601.parse_datetime(date_str_naive)
print(f"Naive: {dt_naive} (Type: {type(dt_naive)}) (TZ: {dt_naive.tzinfo})")
# Parse a timezone-aware datetime string
date_str_aware = "2023-10-27T10:00:00+01:00"
dt_aware = ciso8601.parse_datetime(date_str_aware)
print(f"Aware: {dt_aware} (Type: {type(dt_aware)}) (TZ: {dt_aware.tzinfo})")
# Parse as naive, even if timezone is present
date_str_aware_to_naive = "2023-10-27T10:00:00Z"
dt_forced_naive = ciso8601.parse_datetime_as_naive(date_str_aware_to_naive)
print(f"Forced Naive: {dt_forced_naive} (Type: {type(dt_forced_naive)}) (TZ: {dt_forced_naive.tzinfo})")
# Strict RFC 3339 parsing
# RFC 3339 requires a full date and time with a timezone offset or 'Z'
try:
dt_rfc3339 = ciso8601.parse_rfc3339("2023-10-27T10:00:00Z")
print(f"RFC3339: {dt_rfc3339} (TZ: {dt_rfc3339.tzinfo})")
ciso8601.parse_rfc3339("2023-10-27") # This will raise ValueError
except ValueError as e:
print(f"Error parsing non-RFC3339 string with parse_rfc3339: {e}")
Debug
Known issues
breakingVersion 2.0.0 introduced significant changes to the core implementation that were not entirely backwards compatible. Users upgrading from pre-2.0.0 versions should consult the `CHANGELOG` for migration guidance.fixReview the official `CHANGELOG` on GitHub for specific migration steps. Test thoroughly when upgrading.
affects: <2.0.0 to 2.x.x
breakingIn v2.3.0, the `FixedOffset`'s `dst`, `tzname`, and `utcoffset` methods no longer accept arguments, removing an improper ability that existed in previous versions.fixRemove any arguments passed to `FixedOffset.dst()`, `FixedOffset.tzname()`, or `FixedOffset.utcoffset()` calls. These methods should now be called without arguments.
affects: <2.3.0
gotchaVersions prior to 2.3.3 contained a memory leak in the `FixedOffset_fromutc` function, particularly when dealing with timezone-aware datetimes.fixUpgrade to ciso8601 version 2.3.3 or newer to resolve the memory leak.
affects: <2.3.3
gotchaciso8601 only supports a common subset of the ISO 8601 specification. For example, it only supports the HYPHEN-MINUS (`-`) character for timezone separators, not MINUS SIGN (`−`).fixEnsure input strings conform to the supported subset of ISO 8601 as detailed in the project's documentation. If broader ISO 8601 parsing is required, consider `dateutil.parser.isoparse` or Python 3.11+'s `datetime.fromisoformat`.
affects: All versions
gotchaWhen installing ciso8601 on systems without pre-built wheels, compilation from source is required. This necessitates having a C compiler (e.g., GCC on Linux, MSVC on Windows) and Python development headers (e.g., `python3-dev` on Debian/Ubuntu) installed.fixInstall the necessary build tools and Python development headers for your operating system. For Windows, install 'Build Tools for Visual Studio'.
affects: All versions (when installing from source)
gotchaFor Python 3.11 and newer, the standard library's `datetime.fromisoformat` offers highly performant ISO 8601 parsing. While `ciso8601` still aims to be faster, the performance difference may not be significant enough to warrant an external dependency for all use cases, especially if `datetime.fromisoformat` meets requirements.fixBenchmark `ciso8601.parse_datetime` against `datetime.fromisoformat` for your specific use case on Python 3.11+ to determine if `ciso8601` offers a sufficient performance advantage.
affects: All versions, especially when using Python >= 3.11
gotchaThe `ciso8601.parse_rfc3339` function strictly adheres to the RFC 3339 specification, requiring both date and time components in the input string. Date-only strings, while valid ISO 8601, will raise an error (e.g., 'Time is mandatory in RFC 3339 format') because they do not conform to RFC 3339. For more flexible parsing that supports date-only ISO 8601 strings, use `ciso8601.parse_datetime`.fixEnsure input strings to `ciso8601.parse_rfc3339` always include a time component and timezone offset. If you need to parse date-only ISO 8601 strings, use `ciso8601.parse_datetime` instead.
affects: All versions
Errors
Common errors & fixes
ERROR: Failed building wheel for ciso8601
This error occurs during installation when pip attempts to build the C extension for ciso8601 but fails due to missing compilation tools or development headers specific to your operating system or Python installation.
fixOn Windows, ensure you have Microsoft Visual C++ 14.0 or greater installed (usually via 'Build Tools for Visual Studio'). On Linux, install Python development headers (e.g., `sudo apt-get install python3-dev` or `sudo yum install python3-devel`) and a C compiler (e.g., `sudo apt-get install build-essential` or `sudo yum install gcc`). For macOS, ensure Xcode Command Line Tools are installed (`xcode-select --install`).
ModuleNotFoundError: No module named 'ciso8601'
This means the ciso8601 library is not installed in the Python environment you are currently using, or its installation failed previously.
fixInstall the library using pip: `pip install ciso8601`. If it was installed but still not found, check that your Python interpreter and environment variables are correctly configured to point to the location where the package was installed, or try reactivating your virtual environment.
ValueError: Invalid ISO 8601 date time string
ciso8601's `parse_datetime` function was called with a string that does not conform to the supported subset of ISO 8601 or RFC 3339 formats, or is malformed.
fixEnsure the input string strictly adheres to the ISO 8601 or RFC 3339 standard formats supported by ciso8601. Review the ciso8601 documentation for supported date, time, and timezone formats. For example, '2014-12-05T12:30:45.123456Z' or '2014-12-05T12:30:45+05:30' are typically valid.
ImportError: Cannot parse a timestamp with time zone information without the pytz dependency.
This specific error occurs in Python 2 environments when attempting to parse a timezone-aware ISO 8601 string using `ciso8601` without the `pytz` library installed. In Python 3, `pytz` is not required for this purpose as `ciso8601` utilizes the built-in `datetime.timezone` class.
fixIf working in a Python 2 environment and needing to parse timezone-aware strings, install the `pytz` library: `pip install pytz`. For Python 3, this dependency is not needed.
Upgrade
Version history
2.3.3latest on PyPI · released Aug 20, 2025
Audit
Dependencies
pytzoptionalRequired for parsing timezone-aware ISO 8601 strings in Python 2.7; not needed for Python 3.