What it is
The official Kotlin Multiplatform date and time library, providing Instant, LocalDate, LocalDateTime and time zone handling across JVM, Android, iOS and JS.
Instant marks a moment; LocalDate and LocalDateTime describe civil dates without one. Conversion between them always requires an explicit time zone.
Installation
implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")Getting started
The smallest useful thing you can do with it, and what each part means.
kotlin
val now: Instant = Clock.System.now()
// Conversion requires an explicit zone — the API will not guess.
val zone = TimeZone.of("Europe/London")
val local: LocalDateTime = now.toLocalDateTime(zone)
val date = LocalDate(2026, Month.AUGUST, 7)
val tomorrow = date.plus(1, DateTimeUnit.DAY)
// Calendar-aware arithmetic: adding a month is not adding 30 days.
val nextMonth = now.plus(1, DateTimeUnit.MONTH, zone)
val days = date.daysUntil(LocalDate(2026, 12, 25))
val elapsed: Duration = later - now // kotlin.time.DurationAdvanced usage
Where the library earns its place over a simpler alternative.
kotlin
@Serializable
data class Event(
val id: String,
val startsAt: Instant, // serialises as ISO-8601
val localDate: LocalDate,
)
// Across a DST boundary, adding a day is not adding 24 hours.
val zone = TimeZone.of("Europe/London")
val beforeDst = LocalDateTime(2026, 3, 28, 12, 0).toInstant(zone)
val nextDay = beforeDst.plus(1, DateTimeUnit.DAY, zone) // still 12:00 local
val plus24h = beforeDst + 24.hours // now 13:00 localErrors and fixes
The failures you are most likely to hit, and what actually resolves them.
- Times are off by an hour twice a year
- Duration arithmetic across a DST boundary. Use DateTimeUnit with a TimeZone.
- A formatting function is missing
- The API is deliberately smaller than java.time. Use the DateTimeFormat builders, or java.time on JVM-only code.
Best practices
- Store and transmit Instant in UTC; convert to local only for display.
- Always pass an explicit TimeZone rather than relying on the system default.
- Use calendar units with a zone for day and month arithmetic, not fixed Durations.
- On JVM-only projects, java.time is richer — use this when targeting Multiplatform.
Background
Why it exists, and what it was reacting to.
java.time is unavailable on Kotlin/Native and JS. kotlinx-datetime provides one API that works everywhere, with a deliberately smaller surface than java.time.