kotlinx-datetime: a multiplatform date and time library for Kotlin

The problem kotlinx-datetime solves for Kotlin multiplatform projects

Kotlin multiplatform projects cannot use java.time outside the JVM. Android and desktop builds get it, Kotlin/JS and Kotlin/Native targets do not, so a shared module that stores timestamps or a scheduled meeting time needs an abstraction that compiles everywhere. kotlinx-datetime is JetBrains' answer, published under the Apache-2.0 licence and described in its README as "A multiplatform Kotlin library for working with date and time."

The audience is narrow and specific: developers writing common code that has to build for several Kotlin targets, and who need dates, times and time zone conversion rather than a full calendar framework. The README states the design intent plainly: the library is "pragmatic and focused on the most common problems", it is "not all-encompassing", and the authors "chose convenience over generality, so the API surface this library provides is as minimal as possible to meet the use cases." That sentence should be read as a specification, not as modesty. If your feature list includes recurring events with complex rules or locale-aware month names, this library is not aiming at you.

Instant versus LocalDateTime: the split that shapes the API

The central design decision is a hard boundary between the physical timeline and civil time. On one side sits kotlin.time.Instant, a counter of high-resolution intervals since the start of the time scale. On the other sits LocalDateTime, which carries year, month, day, hour and so on up to nanosecond, with no time zone attached. TimeZone supplies the rules that convert between the two.

The README gives explicit guidance on which type to reach for. Use Instant for events that already happened, such as a log entry, or that will happen at a well-defined moment soon, such as an order confirmation deadline an hour from now. Use LocalDateTime for far-future scheduled events, keeping the TimeZone separately, and the README warns against converting future events to Instant in advance because "time zone rules might change unexpectedly in the future." LocalDate covers dates with no time, such as a birth date. YearMonth covers a year and month with no specific day, such as a credit card expiration date.

The consequence is that calendar arithmetic cannot be done silently. The README notes that operations such as adding a month explicitly take time-zone information as a parameter, so the caller sees that the result depends on civil time zone rules. If you have used APIs where adding a month to an instant quietly changes its length, this is the deliberate opposite.

Conversion looks like this, taken from the README. An Instant is turned into components by naming the zone, and the same instant can be rendered in UTC, in the system zone, or in a named zone fetched by string identifier.

val currentMoment: Instant = Clock.System.now()
val datetimeInUtc: LocalDateTime = currentMoment.toLocalDateTime(TimeZone.UTC)
val datetimeInSystemZone: LocalDateTime = currentMoment.toLocalDateTime(TimeZoneContext.System.currentTimeZone())

val tzBerlin = TimeZoneContext.System.get("Europe/Berlin")
val datetimeInBerlin = currentMoment.toLocalDateTime(tzBerlin)

The README also lists LocalDateTimeOffsetInfo, described as representing an attempt at determining the UTC offset in effect when a given wall-clock time was observed. The word "attempt" is doing real work there: for a wall-clock time that falls in a daylight-saving gap or is ambiguous during a fall-back overlap, there is no single correct offset, and the type is named to reflect that.

Adding the dependency and getting a first timestamp

The README points to its "Using in your projects" section for dependency setup and links Maven Central under the group org.jetbrains.kotlinx and artifact kotlinx-datetime. The current release line shown in the repository is v0.8.0, published on 2026-05-07, preceded by v0.8.0-rc01 and v0.8.0-rc02 in April 2026. The README's Kotlin badge reads 2.3.21, so check your Kotlin version against that before upgrading.

The README does not print a Gradle snippet, so the dependency coordinates have to come from the Maven Central badge: group org.jetbrains.kotlinx, artifact kotlinx-datetime, with the version taken from the release list. Add that artifact to your common source set.

For a first real use, take the current moment and render it in UTC, using the conversion shown in the README's own example. Clock.System.now() returns an Instant, and toLocalDateTime with TimeZone.UTC produces the components you can print or store.

val currentMoment: Instant = Clock.System.now()
val datetimeInUtc: LocalDateTime = currentMoment.toLocalDateTime(TimeZone.UTC)
val datetimeInSystemZone: LocalDateTime = currentMoment.toLocalDateTime(TimeZoneContext.System.currentTimeZone())

You should see a Gregorian date and time with nanosecond precision, with no zone suffix, because LocalDateTime has none. If you want the local wall clock instead, swap TimeZone.UTC for TimeZoneContext.System.currentTimeZone(). That single substitution is the whole mental model of the library: the instant is fixed, and the zone is a parameter you pass in.

Where kotlinx-datetime is the wrong tool

The README is unusually direct about scope. Internationalization, including locale-specific month and day names, is out of scope. The library is based on ISO 8601, and "other ways to represent dates and times are out of its scope." There is no formatter in the type list. If your UI needs "Thursday, 22 September" in a user's locale, kotlinx-datetime will hand you the components and you will write the formatting yourself, per platform, or pull in another library.

The stability badge matters too. The README carries the Kotlin Alpha badge, which is the project's own signal about API stability, and the release history shows a 0.x line with release candidates. Treat the API as movable: pin the version, and read the CHANGELOG.md at the repository root before bumping it.

Time zone data is the third constraint. The repository contains a timezones/ directory and an UPDATE_TIMEZONE_DATABASE.md file at the top level, which tells you the tz database is a maintained input rather than something the library reads from the host operating system on every target. The README does not document how each platform resolves zone data at runtime, nor does it document rollback if a dependency upgrade goes wrong. On a JVM or Android target you may already have java.time available, and for a JVM-only service the argument for adding a multiplatform abstraction is weak: you would be taking on an Alpha dependency to solve a problem you do not have.

kotlinx-datetime versus java.time and kotlin.time

The comparison people actually search for is kotlinx-datetime versus java.time, and the difference is portability rather than API design. java.time is a mature, JVM-only library with a formatting and parsing layer, locale support and a long stability record. kotlinx-datetime compiles across Kotlin targets, and it pays for that by keeping the API minimal and leaving formatting out. The type split is similar in spirit to java.time's Instant and LocalDateTime, so the concepts transfer; what does not transfer is the surrounding machinery.

Against kotlin.time, the boundary is different. kotlin.time provides Instant and Clock, and kotlinx-datetime builds on them: the README's own example calls Clock.System.now() to obtain an Instant and then converts it with a TimeZone. So the two are not competitors. kotlin.time answers "what moment is it", and kotlinx-datetime answers "what does that moment look like as calendar components, and how do I go back". Choosing kotlinx-datetime means accepting that the calendar layer, the time zone database and the conversion rules all come from one library, which is the point of using it.

Maintenance, releases and what the Apache-2.0 licence implies

The repository is not archived, and the last push was on 2026-09-22, so work on the tree is recent. The latest tagged release is v0.8.0 from 2026-05-07. The top-level layout includes benchmarks/, integration-testing/, test-utils/, and a TeamCity build badge in the README, which together suggest a project with its own test and performance infrastructure rather than a single-module library. That is context, not a quality score.

The upgrade cost is the part to plan for. A 0.x version line with release candidates means minor bumps can carry API changes, and the CHANGELOG.md at the repository root is the place to read before moving a version. Because the library bundles time zone data, a version bump can also change how a zone identifier resolves, so a date that parsed correctly before an upgrade is worth re-checking after one.

On licensing: the repository carries the Apache-2.0 licence, and the README's badge links to the Apache 2.0 text. The LICENSE.txt file is at the repository root. Apache-2.0 is a permissive licence with an explicit patent grant and notice requirements, which is normally straightforward for application use, but this is not legal advice and the terms that apply to you are the ones in LICENSE.txt.

Editorial conclusion

Use kotlinx-datetime when one date/time API has to compile for JVM, Android, Kotlin/JS and native targets, and when you want the wall-clock versus instant distinction enforced by the type system. Do not adopt it if you need locale-specific formatting, non-ISO 8601 calendars, or a stable API: the README carries the Kotlin Alpha badge and the current release line is v0.8.0. Before committing, check the KDoc API reference for the exact signatures of TimeZoneContext and LocalDateTimeOffsetInfo, and read UPDATE_TIMEZONE_DATABASE.md to see how time zone data reaches your builds.

Frequently asked questions

Official sources

1. Issues
2. Kotlin/kotlinx-datetime on GitHub
3. License: Apache-2.0
4. README
5. Releases