skip to content

How does KGP wire in the Kotlin standard library, and when and how would you override that behavior?

level: seniorimportance: nice to knowfreq 30%

answer

  1. stdlib auto-added, version == KGP version
  2. kotlin.stdlib.default.dependency=false to opt out
  3. Opt out to pin/exclude/resolve conflicts
  4. jdk7/jdk8 variants merged into base stdlib
  5. kotlin("test") pulls aligned test stdlib

basics

~20 s

The Kotlin plugin adds the standard library for you automatically, matching the plugin's version, so you don't declare it. You can turn that off with a Gradle property if you need to control the version yourself.

solid answer

~40 s

When you apply the Kotlin/JVM plugin, KGP **automatically adds `org.jetbrains.kotlin:kotlin-stdlib`** to the `api`/`implementation` configurations, with a version matching the Kotlin Gradle Plugin version. This is the `kotlin.stdlib.default.dependency` behavior (default `true`). You override it by setting **`kotlin.stdlib.default.dependency=false`** in `gradle.properties`, after which you must declare stdlib yourself. KGP also controls which stdlib JDK variant via **`kotlin.stdlib.jdk.variants.version.alignment`**—historically there were `kotlin-stdlib-jdk7`/`-jdk8` artifacts, but modern stdlib merged them, so you normally just get `kotlin-stdlib`. You'd disable the auto-dependency to pin an exact stdlib version independent of the plugin, to exclude it (e.g. a library that wants the consumer to provide stdlib), or to resolve version-alignment conflicts. Because stdlib is added as a normal dependency, the **BOM/platform** alignment and Gradle's conflict resolution still apply.

code

kotlin · 8 lines
kotlin
// gradle.properties
// kotlin.stdlib.default.dependency=false

// build.gradle.kts (only needed when the auto-dependency is disabled)
dependencies {
    implementation("org.jetbrains.kotlin:kotlin-stdlib:2.1.0")
    testImplementation(kotlin("test"))
}

go deeper

for a junior

Knows you normally don't declare the standard library because the plugin adds it.

for a middle

Names kotlin.stdlib.default.dependency and that the stdlib version follows the plugin version.

for a senior

Explains when to opt out (pin/exclude/conflict), the merged jdk7/jdk8 variants, and conflict-resolution interactions.

for a principal

Reasons about stdlib version governance across modules/libraries, BOM alignment, and packaging trade-offs for published artifacts.

## Automatic stdlib: the default The **Kotlin standard library** (`kotlin-stdlib`) provides core types and extensions—`List`/`Map` helpers, `let`/`apply`/`run`/`with`/`also` scope functions, `String` extensions, sequences, coroutines-free essentials, etc. Your Kotlin code cannot compile without it. Modern KGP adds it **for you**. When the JVM plugin is applied it injects: ``` implementation("org.jetbrains.kotlin:kotlin-stdlib:<kgp-version>") ``` with the version aligned to the **Kotlin Gradle Plugin** version. This is governed by the Gradle property: ```properties # gradle.properties (default true) kotlin.stdlib.default.dependency=true ``` So in a typical build you simply do **not** declare stdlib at all. ## Overriding the behavior Set it off when you want manual control: ```properties kotlin.stdlib.default.dependency=false ``` Then you must add stdlib explicitly: ```kotlin dependencies { implementation("org.jetbrains.kotlin:kotlin-stdlib:2.1.0") } ``` Reasons to do this: - **Pin a specific stdlib version** independent of the plugin version. - **Exclude stdlib** from a published library so the consumer supplies it (rare). - **Resolve alignment conflicts** when multiple Kotlin versions collide on the classpath. ## stdlib variants and alignment Historically there were `kotlin-stdlib-jdk7` and `kotlin-stdlib-jdk8` add-on artifacts. **Modern stdlib merged those** into the base `kotlin-stdlib`, so you rarely see them now. KGP can still align variant versions via: ```properties kotlin.stdlib.jdk.variants.version.alignment=true ``` which keeps any transitively pulled jdk7/jdk8 variants on the same version as the main stdlib, preventing classpath skew. ## How it interacts with the rest of the build Because stdlib is added as an **ordinary dependency**, it participates in: - **Gradle dependency conflict resolution** (highest version wins by default), - **platform/BOM** constraints if you use a Kotlin BOM, - **`kotlin("test")`** which pulls the test stdlib helpers. ```kotlin dependencies { testImplementation(kotlin("test")) // resolves kotlin-test, aligned to the plugin } ``` ## Practical guidance Leave the default on for applications—it just works and stays aligned with the compiler. Turn it off only when you have a concrete reason (strict version pinning, library packaging, or untangling a conflict). When off, remember stdlib is mandatory; forgetting to add it back produces 'unresolved reference: kotlin' style failures.

  • What version does the auto-added stdlib use?
    It matches the Kotlin Gradle Plugin version, keeping the stdlib aligned with the compiler that produced your bytecode.
  • Why might a published library disable the default stdlib dependency?
    To let the consuming application choose/control the stdlib version, avoiding forcing a specific Kotlin runtime version on downstream users.

saying these in an interview costs you the question

  • Always declaring kotlin-stdlib manually 'to be safe' and risking version drift
  • Not knowing the auto-stdlib version tracks the plugin version
  • Disabling kotlin.stdlib.default.dependency but forgetting to add stdlib back
  • Believing kotlin-stdlib-jdk8 must still be added explicitly in modern Kotlin

context

resolving links…