JetBrains released Kotlin 2.5.0-RC on 11 November 2026. A release candidate is the last stop before a stable release, so now is the time to try it on a branch and report problems. This version makes several language features stable, adds experimental companion blocks and full value classes, supports Java 28 bytecode, promotes Swift export to Beta, and turns a JDK 17 requirement for the compiler into an error by default. This tutorial shows how to try it, explains the most useful features with code, and lists what can break.
Everything here comes from JetBrains’ official What’s new in Kotlin 2.5.0-RC page and the GitHub release.
Step 1: Try the RC safely
Use a separate branch and change only the Kotlin version:
// build.gradle.kts
plugins {
kotlin("jvm") version "2.5.0-RC"
}
Make sure your IDE is up to date, because the latest IntelliJ IDEA and Android Studio include the newest Kotlin support. Then run a full build and your tests.
Important: the Kotlin compiler now needs JDK 17 or newer to run. Running it on an older JDK is an error unless you add the temporary opt-out -Xallow-pre-17-runtime-jdk, which JetBrains plans to remove in Kotlin 2.5.20 or 2.6.0. Check your CI images:
java -version # the JDK that runs Gradle and the compiler should be 17+
This is about the JDK that runs the compiler. Your jvmTarget for generated bytecode is a separate setting.
Step 2: Features that are now stable
Name-based destructuring is the default
Kotlin’s classic destructuring, val (a, b) = x, depends on position: it calls component1(), component2() and so on. If someone reorders the properties of a data class, the variables quietly swap. In 2.5, name-based destructuring in only-syntax mode is stable and on by default:
val (x, y) = pointkeeps the old position-based behaviour.(val x, val y) = pointuses the new name-based form, matching on property names.
data class User(val name: String, val email: String)
fun main() {
val user = User("Asha", "[email protected]")
// Position-based (old syntax, unchanged)
val (first, second) = user
println(first) // Asha
// Name-based (new syntax): matched by property name, not position
(val email, val name) = user
println(email) // [email protected]
println(name) // Asha
}
Use the name-based form in new code. It survives refactors that reorder properties.
The unused return value checker is on by default
The checker, introduced as experimental in earlier releases, is now stable and enabled by default. It reports calls whose result should be used but is silently dropped, which is a classic source of bugs with immutable APIs:
fun main() {
val tags = listOf("kotlin", "jvm")
tags + "wasm" // result dropped: tags is unchanged; this is what the checker is built to flag
val updated = tags + "wasm"
println(updated)
}
Expect new warnings in older code after upgrading. Treat each one as a possible bug before you suppress it.
Two more features are now stable: improved compile-time constants and the @IntroducedAt annotation, which generates version-based overloads for optional parameters. Library authors will find the second one useful for adding parameters without breaking binary compatibility.
Step 3: Experimental features worth trying
Companion extensions and companion blocks
Until now, you could only add “static-like” members to a type through its companion object. Kotlin 2.5.0-RC lets you declare companion extensions on any type, and companion blocks that don’t create an object instance. On platforms with static members, the compiler generates real statics, so there’s no need for @JvmStatic:
// Companion extension: works even though Vector has no companion object
companion val Vector.UnitX get() = Vector(1.0, 0.0)
data class Vector(val x: Double, val y: Double) {
companion {
val Zero: Vector get() = Vector(0.0, 0.0)
}
}
fun main() {
println(Vector.UnitX) // Vector(x=1.0, y=0.0)
println(Vector.Zero) // Vector(x=0.0, y=0.0)
}
Opt in with a compiler flag:
kotlin {
compilerOptions {
freeCompilerArgs.add("-Xcompanion-blocks-and-extensions")
}
}
Full value classes
Inline value classes wrap exactly one value. Full value classes can hold several properties. Their identity doesn’t matter, only their data does. The compiler generates equals(), hashCode() and toString(), like a data class, but there are no componentN() functions (use name-based destructuring instead) and no copy():
value class Complex(val real: Double, val imaginary: Double)
sealed interface UserResponse
value class UserFound(val name: String) : UserResponse
value object UserUnknown : UserResponse
fun describe(r: UserResponse) = when (r) {
is UserFound -> "Found ${r.name}"
UserUnknown -> "No such user"
}
value object (a value class with no properties) is handy for states and tokens. Enable the feature with:
kotlin {
compilerOptions {
freeCompilerArgs.add("-Xfull-value-classes")
}
}
Stricter equality checks
With -Xstrict-equality-for-structural-classes, the compiler reports == comparisons between data classes, data objects, final value classes and enums that can never be true, such as comparing a Vector with a Point that has the same properties.
New standard library helpers
Experimental onTrue(), onFalse() and ifOrNull() simplify common Boolean patterns:
@OptIn(ExperimentalStdlibApi::class)
fun main() {
val tags = mutableSetOf("kotlin", "jvm")
tags.add("wasm").onTrue { println("Tag added") }
tags.remove("native").onFalse { println("Tag not found") }
val message = ifOrNull("wasm" in tags) { "Wasm tag is available" }
println(message)
}
There is also an experimental CodePoint value class in kotlin.text.unicode (opt in with @OptIn(ExperimentalUnicodeApi::class)) for working with characters outside the Basic Multilingual Plane, such as emoji, without splitting surrogate pairs.
Step 4: Platform updates
- Kotlin/JVM: the compiler can generate Java 28 bytecode.
- Kotlin/JS: a new
es2020target, which gives youBigIntand other ES2020 features without extra flags:
kotlin {
js {
compilerOptions {
target.set("es2020")
}
}
}
- Kotlin/Native: Swift export is now Beta, with a new DSL.
swiftExport {}becomesexport { swift {} },flattenPackagebecomesrootPackage, and declared dependencies are exported automatically. - Kotlin Multiplatform: an experimental compilation scheme that treats common source sets more like the IDE does, and a new
.karpublication format. JetBrains reports that the cryptography-kotlin project went from 7,539 files and 91 MB to 1,036 files and 23 MB. Library authors can opt in withkotlin.publicationFormat=KOTLIN_ARCHIVEingradle.properties.
What can break
- Compiler JDK below 17 now fails by default.
- New warnings from the unused return value checker.
- Type inference changes: a performance fix can infer different types or pick different overloads in rare builder-inference cases. You can temporarily restore the old behaviour with
-XXLanguage:-EliminateSecondKindIncorporation. - Cross-module klib inlining is now on by default for Native, JS and Wasm. If you hit problems,
-Xklib-ir-inliner=disabledturns it off. Please report the issue too.
Takeaway
Kotlin 2.5.0-RC is a solid preview of 2.5: name-based destructuring and the unused-result checker make everyday code safer, while companion blocks and full value classes hint at the language’s future. Try it on a branch now, make sure CI runs the compiler on JDK 17+, and report anything odd to JetBrains’ YouTrack before the stable release.
