Migrate to Kotlin 2.0

If you are using the Navigation SDK for Android 6.0+ you must upgrade to Kotlin 2.0. This page provides guidance to ease the transition to the new Kotlin version.

Gradle and AGP compatibility

Kotlin 2.0 has requirements for the minimum and maximum versions for your Gradle and Android Gradle Plugin (AGP) version. Ensure that your project meets these requirements for Kotlin 2.0.

AGP minimum version for the Navigation SDK 6.0+

We recommend using AGP 7.3+ with the Navigation SDK 6.0. We have verified the SDK with AGP 8.3 and Gradle 8.4, and the SDK is compatible with R8's Full Mode.

Kotlin version compatibility

Kotlin supports backwards compatibility with three previous language versions. This means that if you are already using Kotlin 1.7+ with the Navigation SDK, you should be able to upgrade to Kotlin 2.0 without having to resolve all of the breaking changes. However, this only applies to stable language features. If you are using alpha, beta or experimental features in the Kotlin language, then you may have to make additional changes when upgrading.

Easing the transition: Kotlin compatibility flags

As noted in the previous section, Kotlin supports up to 3 previous versions of the language when upgrading. Kotlin supplies two flags to help with limiting breaking changes:

language-version X.Y

This flag reverts breaking changes to the behavior of a previous Kotlin version. For example, if you are using Kotlin 1.7, you could specify [ - language-version 1.7] and the new breaking changes would no longer take effect:

android {
   kotlinOptions {
       languageVersion = '1.7'
   }
}

api-version X.Y

This flag prevents new APIs from being used before dependent downstream code is ready to incorporate Kotlin 2.0.

android {
   kotlinOptions {
       apiVersion = '1.7'
   }
}

A more targeted approach

In addition to using Kotlin compatibility flags, we recommend reviewing the Kotlin release notes and choosing the behaviors that you would like to retain from the version that you are upgrading from. Kotlin provides a list of breaking changes and the flags that can be set to retain the original behavior in its compatibility guides for each version: