kotlinx-datetime is a multiplatform Kotlin library for working with date and time.
The library addresses the common need to handle dates and times correctly across different platforms while maintaining a clear separation between physical time (instants) and civil time (human-readable components like year, month, and day). It solves this by providing distinct types for different temporal concepts: LocalDateTime for date and time components without timezone information, LocalDate for dates only, LocalTime for times only, and Instant paired with TimeZone for timezone-aware conversions. The design explicitly requires timezone information as a parameter when performing calendar-based operations on instants, preventing the kind of timezone-related bugs that arise from mixing physical and civil time concepts.
The library is built on the ISO 8601 standard and intentionally keeps its scope narrow, focusing on the most common developer needs rather than attempting to be all-encompassing. It provides no locale-specific utilities like translated month names, and it does not support non-ISO calendar systems. This pragmatic approach results in a minimal API surface. The type system includes LocalDateTime, LocalDate, YearMonth, LocalTime, TimeZone, FixedOffsetTimeZone, DateTimePeriod, DatePeriod, DateTimeUnit, UtcOffset, and LocalDateTimeOffsetInfo, giving developers the tools needed for typical date and time operations without unnecessary complexity.
Developers should choose this library if they need reliable date and time handling in Kotlin multiplatform projects and want a straightforward API that avoids the pitfalls of mixing instant and civil time concepts. It suits projects that work with ISO 8601 dates and times and do not require specialized calendar systems or internationalization features. The library's explicit timezone handling makes it particularly valuable for applications where timezone correctness is important.
The project maintains active development with regular commits addressing bug fixes and feature enhancements. Pull requests receive timely review and feedback from maintainers. The codebase shows consistent attention to test coverage and documentation updates alongside code changes.
