# Compiler options in the Kotlin Gradle plugin

Each release of Kotlin includes compilers for the supported targets:
JVM, JavaScript, and native binaries for [supported platforms](native-overview.html#target-platforms).

These compilers are used by:

* The IDE, when you click the Compile or Run button for your Kotlin project.

* Gradle, when you call `gradle build` in a console or in the IDE.

* Maven, when you call `mvn compile` or `mvn test-compile` in a console or in the IDE.

You can also run Kotlin compilers manually from the command line as described
in the [Working with command-line compiler](command-line.html) tutorial.

## How to define options

Kotlin compilers have a number of options for tailoring the compiling process.

The Gradle DSL allows comprehensive
configuration of compiler options. It is available for [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform/multiplatform-dsl-reference.html#compiler-options) and [JVM/Android](#target-the-jvm) projects.

With the Gradle DSL, you can configure compiler options within the build script at three levels:

* [Extension level](#extension-level), in the `kotlin {}` block for all targets and shared source sets.

* [Target level](#target-level), in the block for a specific target.

* [Compilation unit level](#compilation-unit-level), usually in a specific compilation task.

![Kotlin compiler options levels](images/compiler-options-levels.svg)
The settings at a higher level are used as a convention (default) for a lower level:

* Compiler options set at the extension level are the default for target-level options, including shared source sets like `commonMain`, `nativeMain`, and `commonTest`.

* Compiler options set at the target level are the default for options at the compilation unit (task) level, like `compileKotlinJvm` and `compileTestKotlinJvm` tasks.

In turn, configurations made at a lower level override related settings at a higher level:

* Task-level compiler options override related configurations at the target or the extension level.

* Target-level compiler options override related configurations at the extension level.

To find out which level of compiler arguments is applied to the compilation, use the `DEBUG` level of Gradle [logging](https://docs.gradle.org/current/userguide/logging.html).
For JVM and JS/WASM tasks, search for the `"Kotlin compiler args:"` string within the logs; for Native tasks,
search for the `"Arguments ="` string.

Tip:

If you're a third-party plugin author, it's best to apply your configuration on the project level to avoid
overriding issues. You can use the new [Kotlin plugin DSL extension types](whatsnew21.html#new-api-for-kotlin-gradle-plugin-extensions) for this. It's recommended that you document this
configuration on your side explicitly.

### Extension level

You can configure common compiler options for all the targets and shared source sets
in the `compilerOptions {}` block at the top level:

```KOTLIN
kotlin {
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
    }
}
```

### Target level

You can configure compiler options for the JVM/Android target
in the `compilerOptions {}` block inside the `target {}` block:

```KOTLIN
kotlin {
    target {
        compilerOptions {
            optIn.add("kotlin.RequiresOptIn")
        }
    }
}
```

In Kotlin Multiplatform projects, you can configure compiler options inside the
specific target. For example, `jvm { compilerOptions {}}`. For more information, see [Multiplatform Gradle DSL reference](https://kotlinlang.org/docs/multiplatform/multiplatform-dsl-reference.html).

### Compilation unit level

You can configure compiler options for a specific compilation unit or task in a `compilerOptions {}`
block inside the task configuration:

```KOTLIN
tasks.named<KotlinJvmCompile>("compileKotlin"){
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
    }
}
```

You can also access and configure compiler options at a compilation unit level via `KotlinCompilation`:

```KOTLIN
kotlin {
    target {
        val main by compilations.getting {
            compileTaskProvider.configure {
                compilerOptions {
                    optIn.add("kotlin.RequiresOptIn")
                }
            }
        }
    }
}
```

If you want to configure a plugin of a target different from JVM/Android and [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform/multiplatform-dsl-reference.html),
use the `compilerOptions {}` property of the corresponding Kotlin compilation task. The following examples
show how to set this configuration up in both Kotlin and Groovy DSLs:

Kotlin:

```KOTLIN
tasks.named("compileKotlin", org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask::class.java) {
    compilerOptions {
        apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
    }
}
```

Groovy:

```GROOVY
tasks.named('compileKotlin', org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class) {
    compilerOptions {
        apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
    }
}
```

### 

Migrate from `kotlinOptions {}` to `compilerOptions {}`

Before Kotlin 2.2.0, you could configure compiler options using the `kotlinOptions {}` block. Since the `kotlinOptions {}`
block is deprecated from Kotlin 2.0.0, this section provides guidance and recommendations for migrating your build
scripts to use the `compilerOptions {}` block instead:

* [Centralize compiler options and use types](#centralize-compiler-options-and-use-types)

* [Migrate away from android.kotlinOptions](#migrate-away-from-android-kotlinoptions)

* [Migrate freeCompilerArgs](#migrate-freecompilerargs)

#### Centralize compiler options and use types

Whenever possible, configure compiler options at the [extension level](#extension-level), and override them for specific tasks
at the [compilation unit level](#compilation-unit-level).

You can't use raw strings in the `compilerOptions {}` block, so convert them to typed values. For example, if you have:

Kotlin:

```KOTLIN
plugins {
    kotlin("jvm") version "2.3.21"
}

tasks.withType<KotlinCompile>().configureEach {
    kotlinOptions {
        jvmTarget = "17"
        languageVersion = "2.3"
        apiVersion = "2.3"
    }
}
```

Groovy:

```KOTLIN
plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.3.21'
}

tasks.withType(KotlinCompile).configureEach {
    kotlinOptions {
        jvmTarget = '17'
        languageVersion = '2.3'
        apiVersion = '2.3'
    }
}
```

After migration, it should be:

Kotlin:

```KOTLIN
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion

plugins {
    kotlin("jvm") version "2.3.21"
}

kotlin {
    // Extension level
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
        languageVersion = KotlinVersion.fromVersion("2.3")
        apiVersion = KotlinVersion.fromVersion("2.3")
    }
}

// Example of overriding at compilation unit level
tasks.named<KotlinJvmCompile>("compileKotlin"){
    compilerOptions {
        apiVersion = KotlinVersion.fromVersion("2.3")
    }
}
```

Groovy:

```KOTLIN
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion

plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.3.21'
}

kotlin {
  // Extension level
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
        languageVersion = KotlinVersion.fromVersion("2.3")
        apiVersion = KotlinVersion.fromVersion("2.3")
    }
}

// Example of overriding at compilation unit level
tasks.named("compileKotlin", KotlinJvmCompile).configure {
    compilerOptions {
        apiVersion = KotlinVersion.fromVersion("2.3")
    }
}
```

#### 

Migrate away from `android.kotlinOptions`

If your build script previously used `android.kotlinOptions`, migrate to `kotlin.compilerOptions` instead. Either at
the extension level or the target level.

For example, if you have an Android project:

Kotlin:

```KOTLIN
plugins {
    id("com.android.application")
    kotlin("android")
}

android {
    kotlinOptions {
        jvmTarget = "17"
    }
}
```

Groovy:

```KOTLIN
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

android {
    kotlinOptions {
        jvmTarget = '17'
    }
}
```

Update it to:

Kotlin:

```KOTLIN
plugins {
    id("com.android.application")
    kotlin("android")
}

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
    }
}
```

Groovy:

```KOTLIN
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
    }
}
```

And for example, if you have a Kotlin Multiplatform project with an Android target:

Kotlin:

```KOTLIN
plugins {
    kotlin("multiplatform")
    id("com.android.application")
}

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions.jvmTarget = "17"
        }
    }
}
```

Groovy:

```KOTLIN
plugins {
    id 'org.jetbrains.kotlin.multiplatform'
    id 'com.android.application'
}

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions {
                jvmTarget = '17'
            }
        }
    }
}
```

Update it to:

Kotlin:

```KOTLIN
plugins {
    kotlin("multiplatform")
    id("com.android.application")
}

kotlin {
    androidTarget {
        compilerOptions {
            jvmTarget = JvmTarget.fromTarget("17")
        }
    }
}
```

Groovy:

```KOTLIN
plugins {
    id 'org.jetbrains.kotlin.multiplatform'
    id 'com.android.application'
}

kotlin {
    androidTarget {
        compilerOptions {
            jvmTarget = JvmTarget.fromTarget("17")
        }
    }
}
```

#### 

Migrate `freeCompilerArgs`

* Replace all `+=` operations with `add()` or `addAll()` functions.

* If you use the `-opt-in` compiler option, check whether a specialized DSL already is available in the [KGP API reference](https://kotlinlang.org/api/kotlin-gradle-plugin/kotlin-gradle-plugin-api/) and use that instead.

* Migrate any use of the `-progressive` compiler option to use the dedicated DSL: `progressiveMode.set(true)`.

* Migrate any use of the `-Xjvm-default` compiler option to [use the dedicated DSL](#attributes-specific-to-jvm): `jvmDefault.set()`. Use the following mapping for the options: | Before |After | ----------------- | `-Xjvm-default=all-compatibility` |`jvmDefault.set(JvmDefaultMode.ENABLE)` | | `-Xjvm-default=all` |`jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)` | | `-Xjvm-default=disable` |`jvmDefault.set(JvmDefaultMode.DISABLE)` |

For example, if you have:

Kotlin:

```KOTLIN
kotlinOptions {
    freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn"
    freeCompilerArgs += listOf("-Xcontext-receivers", "-Xinline-classes", "-progressive", "-Xjvm-default=all")
}
```

Groovy:

```KOTLIN
kotlinOptions {
    freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn"
    freeCompilerArgs += ["-Xcontext-receivers", "-Xinline-classes", "-progressive", "-Xjvm-default=all"]
}
```

Migrate to:

Kotlin:

```KOTLIN
kotlin {
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
        freeCompilerArgs.addAll(listOf("-Xcontext-receivers", "-Xinline-classes"))
        progressiveMode.set(true)
        jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
    }
}
```

Groovy:

```KOTLIN
kotlin {
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
        freeCompilerArgs.addAll(["-Xcontext-receivers", "-Xinline-classes"])
        progressiveMode.set(true)
        jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
    }
}
```

## Target the JVM

[As explained before](#how-to-define-options), you can define compiler options for your JVM/Android projects at the extension, target, and compilation unit levels (tasks).

Default JVM compilation tasks are called `compileKotlin` for production code and `compileTestKotlin`
for test code. The tasks for custom source sets are named according to their `compile<Name>Kotlin` patterns.

You can see the list of Android compilation tasks by running the `gradlew tasks --all` command in the terminal
and searching for `compile*Kotlin` task names in the `Other tasks` group.

Some important details to be aware of:

* `kotlin.compilerOptions` configures every Kotlin compilation task in the project.

* You can override the configuration applied by `kotlin.compilerOptions` DSL using the `tasks.named<KotlinJvmCompile>("compileKotlin") { }` (or `tasks.withType<KotlinJvmCompile>().configureEach { }`) approach.

## Target JavaScript

JavaScript compilation tasks are called `compileKotlinJs` for production code, `compileTestKotlinJs` for test code, and `compile<Name>KotlinJs` for custom source sets.

To configure a single task, use its name:

Kotlin:

```KOTLIN
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

val compileKotlin: KotlinCompilationTask<*> by tasks

compileKotlin.compilerOptions.suppressWarnings.set(true)
```

Groovy:

```GROOVY
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        suppressWarnings = true
    }
}
```

Note that with the Gradle Kotlin DSL, you should get the task from the project's `tasks` first.

Use the `Kotlin2JsCompile` and `KotlinCompileCommon` types for JS and common targets, respectively.

You can see the list of JavaScript compilation tasks by running the `gradlew tasks --all` command in the terminal
and searching for `compile*KotlinJS` task names in the `Other tasks` group.

## All Kotlin compilation tasks

It is also possible to configure all the Kotlin compilation tasks in the project:

Kotlin:

```KOTLIN
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

tasks.named<KotlinCompilationTask<*>>("compileKotlin").configure {
    compilerOptions { /*...*/ }
}
```

Groovy:

```GROOVY
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions { /*...*/ }
}
```

## All compiler options

Here is a complete list of options for the Gradle compiler:

### Common attributes

| Name |Description |Possible values |Default value |
-----------------------------------------------------
| `optIn` |A property for configuring a list of [opt-in compiler arguments](opt-in-requirements.html) |`listOf( /* opt-ins */ )` |`emptyList()` |
| `progressiveMode` |Enables the [progressive compiler mode](whatsnew13.html#progressive-mode) |`true`, `false` |`false` |
| `extraWarnings` |Enables [additional declaration, expression, and type compiler checks](whatsnew21.html#extra-compiler-checks) that emit warnings if true |`true`, `false` |`false` |

### Attributes specific to JVM

| Name |Description |Possible values |Default value |
-----------------------------------------------------
| `javaParameters` |Generate metadata for Java 1.8 reflection on method parameters |  |false |
| `jvmTarget` |Target version of the generated JVM bytecode |"1.8", "9", "10", ...,  "24", 25". Also, see [Types for compiler options](#types-for-compiler-options) |"1.8" |
| `noJdk` |Don't automatically include the Java runtime into the classpath |  |false |
| `jvmTargetValidationMode` |  * Validation of the [JVM target compatibility](gradle-configure-project.html#check-for-jvm-target-compatibility-of-related-compile-tasks) between Kotlin and Java    * A property for tasks of the `KotlinCompile` type.   |`WARNING`, `ERROR`, `IGNORE` |`ERROR` |
| `jvmDefault` |Control how functions declared in interfaces are compiled to default methods on the JVM |`ENABLE`, `NO_COMPATIBILITY`, `DISABLE` |`ENABLE` |

### Attributes common to JVM and JavaScript

| Name |Description |Possible values |Default value |
-----------------------------------------------------
| `allWarningsAsErrors` |Report an error if there are any warnings |  |false |
| `suppressWarnings` |Don't generate warnings |  |false |
| `verbose` |Enable verbose logging output. Works only when the [Gradle debug log level enabled](https://docs.gradle.org/current/userguide/logging.html) |  |false |
| `freeCompilerArgs` |A list of additional compiler arguments. You can use experimental `-X` arguments here too. See an [example](#example-of-additional-arguments-usage-via-freecompilerargs) |  |[] |
| `apiVersion` |Restrict the use of declarations to those from the specified version of bundled libraries |"1.9", "2.0", "2.1", "2.2", "2.3", "2.4" (EXPERIMENTAL) |  |
| `languageVersion` |Provide source compatibility with the specified version of Kotlin |"1.9", "2.0", "2.1", "2.2", "2.3", "2.4" (EXPERIMENTAL) |  |

Warning:

We are going to deprecate the attribute `freeCompilerArgs` in future releases. If you miss some option in the Kotlin Gradle DSL,
please, [file an issue](https://youtrack.jetbrains.com/newissue?project=kt).

#### Example of additional arguments usage via freeCompilerArgs

Use the `freeCompilerArgs` attribute to supply additional (including experimental) compiler arguments.
You can add a single argument to this attribute or a list of arguments:

Kotlin:

```KOTLIN
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

kotlin {
    compilerOptions {
        // Specifies the version of the Kotlin API and the JVM target
        apiVersion.set(KotlinVersion.KOTLIN_2_3)
        jvmTarget.set(JvmTarget.JVM_1_8)
        
        // Single experimental argument
        freeCompilerArgs.add("-Xexport-kdoc")

        // Single additional argument
        freeCompilerArgs.add("-Xno-param-assertions")

        // List of arguments
        freeCompilerArgs.addAll(
            listOf(
                "-Xno-receiver-assertions",
                "-Xno-call-assertions"
            )
        ) 
    }
}
```

Groovy:

```GROOVY
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        // Specifies the version of the Kotlin API and the JVM target
        apiVersion = KotlinVersion.KOTLIN_2_3
        jvmTarget = JvmTarget.JVM_1_8
        
        // Single experimental argument
        freeCompilerArgs.add("-Xexport-kdoc")
        
        // Single additional argument, can be a key-value pair
        freeCompilerArgs.add("-Xno-param-assertions")
        
        // List of arguments
        freeCompilerArgs.addAll(["-Xno-receiver-assertions", "-Xno-call-assertions"])
    }
}
```

Tip:

The `freeCompilerArgs` attribute is available at the [extension](#extension-level), [target](#target-level), and [compilation unit (task)](#compilation-unit-level) levels.

#### Example of setting languageVersion

To set a language version, use the following syntax:

Kotlin:

```KOTLIN
kotlin {
    compilerOptions {
        languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_3)
    }
}
```

Groovy:

```GROOVY
tasks
    .withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class)
    .configureEach {
        compilerOptions.languageVersion =
            org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_3
    }
```

Also, see [Types for compiler options](#types-for-compiler-options).

### Attributes specific to JavaScript

| Name |Description |Possible values |Default value |
-----------------------------------------------------
| `friendModulesDisabled` |Disable internal declaration export |  |`false` |
| `main` |Specify whether the `main` function should be called upon execution |`JsMainFunctionExecutionMode.CALL`, `JsMainFunctionExecutionMode.NO_CALL` |`JsMainFunctionExecutionMode.CALL` |
| `moduleKind` |The kind of JS module generated by the compiler |`JsModuleKind.MODULE_AMD`, `JsModuleKind.MODULE_PLAIN`, `JsModuleKind.MODULE_ES`, `JsModuleKind.MODULE_COMMONJS`, `JsModuleKind.MODULE_UMD` |`null` |
| `sourceMap` |Generate source map |  |`false` |
| `sourceMapEmbedSources` |Embed source files into the source map |`JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING`, `JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_NEVER`, `JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_ALWAYS` |`null` |
| `sourceMapNamesPolicy` |Add variable and function names that you declared in Kotlin code into the source map. For more information on the behavior, see our [compiler reference](compiler-reference.html#source-map-names-policy-simple-names-fully-qualified-names-no) |`JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES`, `JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_SIMPLE_NAMES`, `JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_NO` |`null` |
| `sourceMapPrefix` |Add the specified prefix to paths in the source map |  |`null` |
| `target` |Generate JS files for specific ECMA version |`"es5"`, `"es2015"` |`"es5"` |
| `useEsClasses` |Let generated JavaScript code use ES2015 classes. Enabled by default in case of ES2015 target usage |  |`null` |

### Types for compiler options

Some of the `compilerOptions` use the new types instead of the `String` type:

| Option |Type |Example |
-------------------------
| `jvmTarget` |[JvmTarget](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-gradle-compiler-types/src/generated/kotlin/org/jetbrains/kotlin/gradle/dsl/JvmTarget.kt) |`compilerOptions.jvmTarget.set(JvmTarget.JVM_11)` |
| `apiVersion` and `languageVersion` |[KotlinVersion](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-gradle-compiler-types/src/generated/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinVersion.kt) |`compilerOptions.languageVersion.set(KotlinVersion.KOTLIN_2_3)` |
| `main` |[JsMainFunctionExecutionMode](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-gradle-compiler-types/src/generated/kotlin/org/jetbrains/kotlin/gradle/dsl/JsMainFunctionExecutionMode.kt) |`compilerOptions.main.set(JsMainFunctionExecutionMode.NO_CALL)` |
| `moduleKind` |[JsModuleKind](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-gradle-compiler-types/src/generated/kotlin/org/jetbrains/kotlin/gradle/dsl/JsModuleKind.kt) |`compilerOptions.moduleKind.set(JsModuleKind.MODULE_ES)` |
| `sourceMapEmbedSources` |[JsSourceMapEmbedMode](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-gradle-compiler-types/src/generated/kotlin/org/jetbrains/kotlin/gradle/dsl/JsSourceMapEmbedMode.kt) |`compilerOptions.sourceMapEmbedSources.set(JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING)` |
| `sourceMapNamesPolicy` |[JsSourceMapNamesPolicy](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-gradle-compiler-types/src/generated/kotlin/org/jetbrains/kotlin/gradle/dsl/JsSourceMapNamesPolicy.kt) |`compilerOptions.sourceMapNamesPolicy.set(JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES)` |

## What's next?

Learn more about:

* [Kotlin Multiplatform DSL reference](https://kotlinlang.org/docs/multiplatform/multiplatform-dsl-reference.html).

* [Incremental compilation, caches support, build reports, and the Kotlin daemon](gradle-compilation-and-caches.html).

* [Gradle basics and specifics](https://docs.gradle.org/current/userguide/userguide.html).

* [Support for Gradle plugin variants](gradle-plugin-variants.html).