# Migrate Gradle build scripts to Kotlin DSL

> **TL;DR**
> Required plugin: Gradle ([installed and enabled](managing-plugins.html#open-plugin-settings) by default)
>
>
>
> Gradle version: 5.0 or later

The Kotlin DSL is the recommended way to write Gradle build scripts. It offers type-safe accessors, full IDE support with code completion and inline documentation, and catches configuration errors at compile time rather than at runtime.

This tutorial shows how to convert a Groovy DSL `build.gradle` file to a Kotlin DSL `build.gradle.kts` file, and how IntelliJ IDEA helps you along the way with completion, inspections, and refactoring.

## Step 1. Rename the build script

Renaming the file is all Gradle needs to switch the DSL. IntelliJ IDEA detects the change and re-indexes the build immediately.

Procedure: Rename build.gradle to build.gradle.kts

1. In the Project tool window, right-click `build.gradle` and select Refactor | Rename `Shift+F6` (Windows), `⇧ F6` (macOS), `⇧ F6` (IntelliJ IDEA Classic (macOS)), `⌘ ⌥ R` (macOS System Shortcuts), `Shift+F6` (XWin), `Shift+F6` (GNOME), `Shift+F6` (KDE), `Shift+F6` (Emacs), `Shift+F6` (Sublime Text), `⇧ F6` (Sublime Text (macOS)), `Ctrl+R` (NetBeans), `Ctrl+R, R` (Visual Studio), `⌘ R, R` (Visual Studio (macOS)), `Alt+Shift+R` (Eclipse), `⇧ F6` (Eclipse (macOS)).

2. Change the name to `build.gradle.kts` and click Refactor.

IntelliJ IDEA renames the file and triggers a Gradle sync. The Gradle tool window shows the sync progress.

> **Note:**
> If your project has a `settings.gradle` file, rename it to `settings.gradle.kts` as well. Mixed Groovy/Kotlin DSL setups are supported, but full Kotlin DSL is easier to maintain.

Synchronize your project. Once the sync is complete, let's check which syntax needs to be fixed.

## Step 2. Update the script syntax

The Kotlin DSL uses Kotlin syntax, so a few constructs need to be updated. The most common changes are listed below. Once the file is open, IntelliJ IDEA provides full Kotlin code completion and inline documentation in the editor — press `Ctrl+Q` (Windows), `F1` (macOS), `⌃ J` (IntelliJ IDEA Classic (macOS)), `⌘ I` (macOS System Shortcuts), `Ctrl+Q` (XWin), `Ctrl+Q` (GNOME), `Ctrl+Q` (KDE), `Ctrl+Q` (Emacs), `Ctrl+Q` (Sublime Text), `Ctrl+Q` (Sublime Text (macOS)), `Ctrl+Q` (NetBeans), `Ctrl+K, I` (Visual Studio), `⌘ K, I` (Visual Studio (macOS)), `Alt+Middle-Click` (Eclipse), `⌥ Middle-Click` (Eclipse (macOS)) on any symbol to see its documentation.

### Strings and method calls

Replace single-quoted Groovy strings with double-quoted Kotlin strings, and add parentheses to method calls that lacked them in Groovy.

> **Note:**
> Don't forget to change the syntax in the `plugins` section as well.

Groovy DSL:

```GROOVY
group = 'org.example'
version = '1.0-SNAPSHOT'

repositories {
    mavenCentral()
}

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter:5.11.0'
}
```

Kotlin DSL:

```KOTLIN
group = "org.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.11.0")
}
```

Don't forget to change  Groovy list literals `[]` as well. Check the following example:

Groovy DSL:
`applicationDefaultJvmArgs = ["-Dfile.encoding=UTF-8"]`

Kotlin DSL:
`applicationDefaultJvmArgs = listOf ("-Dfile.encoding=UTF-8")`

Also, keep in mind that there are no dynamic extensions in Kotlin. So, if you have `ext` block inside the `build.gradle`, check the following example for the Kotlin DSL syntax.

Groovy DSL:

```GROOVY
ext {
    junitVersion = "5.10.2"
    guavaVersion = "33.0.0-jre"
}

```

Kotlin DSL:

```KOTLIN
val junitVersion = "5.10.2"
val guavaVersion = "33.0.0-jre"
```

If you have the `attributes` block that uses Groovy's map syntax (`"key": value`), you need to change the syntax as well since Kotlin builds a map with `mapOf(...)` and `to` pairs instead of colons. Check the following example:

Groovy DSL:

```GROOVY
attributes(
        "Implementation-Title": project.name,
        "Implementation-Version": project.version,
        "Main-Class": "com.example.app.App"
)

```

Kotlin DSL:

```KOTLIN
attributes(mapOf(
    "Implementation-Title" to project.name,
    "Implementation-Version" to project.version,
    "Main-Class" to "com.example.app.App"
))
```

### Task configuration

In the Kotlin DSL, task configuration uses type-safe accessors. Use `tasks.test` instead of the dynamic `test` shorthand.

Groovy DSL:

```GROOVY
test {
    useJUnitPlatform()
}
```

Kotlin DSL:

```KOTLIN
tasks.test {
    useJUnitPlatform()
}
```

> **Tip:**
> Start typing `tasks.` and press `Ctrl+Space` (Windows), `⌃ Space` (macOS), `⌃ Space` (IntelliJ IDEA Classic (macOS)), `⌃ Space` (macOS System Shortcuts), `Ctrl+Space` (XWin), `Ctrl+Space` (GNOME), `Ctrl+Space` (KDE), `Alt+/` (Emacs), `Ctrl+Space` (Sublime Text), `⌃ Space` (Sublime Text (macOS)), `Ctrl+Space` (NetBeans), `Ctrl+Space` (Visual Studio), `⌃ Space` (Visual Studio (macOS)), `Ctrl+Space` (Eclipse), `⌃ Space` (Eclipse (macOS)) to see all available type-safe task accessors for the plugins applied to your project.

## Step 3. Migrate to the plugins block

If your build script uses the legacy `apply plugin:` syntax, IntelliJ IDEA highlights it with the Use 'plugins' block instead of 'apply plugin' inspection. Migrating to the `plugins {}` block enables type-safe accessors for the plugin's extensions and tasks.

Procedure: Replace apply plugin with the plugins block

1. Open `build.gradle.kts` in the editor.

If your script applies plugins with `apply(plugin = "...")`, IntelliJ IDEA underlines the call and shows a warning.

```KOTLIN
apply(plugin = "java")       // highlighted by inspection
apply(plugin = "application")
```

2. Place the caret on the highlighted call and press `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (NetBeans), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS)) to open the intention list. Select Use 'plugins' block.

IntelliJ IDEA replaces all `apply(plugin = ...)` calls with a single `plugins {}` block at the top of the file.

```KOTLIN
plugins {
    java
    application
}
```

However, if you have a third-party plugin, then the following syntax applies:

```KOTLIN
plugins {
    id("com.github.johnrengelman.shadow") version "8.1.1"
}
```

3. [Sync the Gradle project](work-with-gradle-projects.html#gradle_refresh_project) to apply the changes.

After the sync, type-safe accessors for the plugins (such as `application { ... }`) become available with full completion support.

## Step 4. Remove the redundant Kotlin standard library dependency

When you use the Kotlin Gradle plugin, it automatically adds the Kotlin standard library as a dependency. If your build script also declares it explicitly, IntelliJ IDEA highlights the redundant entry with the Redundant Kotlin standard library dependency inspection.

Procedure: Remove the redundant stdlib dependency

1. Open `build.gradle.kts`.

If you have applied the `kotlin("jvm")` plugin and also declared `stdlib` explicitly, IntelliJ IDEA marks the dependency as redundant:

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

dependencies {
    implementation(kotlin("stdlib"))  // highlighted as redundant
}
```

2. Place the caret on the highlighted dependency and press `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (NetBeans), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS)). Select Remove redundant dependency.

IntelliJ IDEA removes the explicit `stdlib` declaration. The dependency is still on the classpath via the Kotlin plugin.

> **Note:**
> The generating of dependencies in `build.gradls.kts` is quite easy, just start typing a dependency scope or a name of the dependency you want to add and the code completion suggestions become available.

## Step 5. Rename symbols across build files

IntelliJ IDEA treats Gradle build files as first-class Kotlin source files. The Rename refactoring works not only across `build.gradle.kts`, `settings.gradle.kts`, but also across any `buildSrc` files in the same project.

Procedure: Rename a symbol used in build files

1. Place the caret on any symbol you want to rename — for example, a property declared in `buildSrc` and referenced in `build.gradle.kts`.

2. Press `Shift+F6` (Windows), `⇧ F6` (macOS), `⇧ F6` (IntelliJ IDEA Classic (macOS)), `⌘ ⌥ R` (macOS System Shortcuts), `Shift+F6` (XWin), `Shift+F6` (GNOME), `Shift+F6` (KDE), `Shift+F6` (Emacs), `Shift+F6` (Sublime Text), `⇧ F6` (Sublime Text (macOS)), `Ctrl+R` (NetBeans), `Ctrl+R, R` (Visual Studio), `⌘ R, R` (Visual Studio (macOS)), `Alt+Shift+R` (Eclipse), `⇧ F6` (Eclipse (macOS)) to open the Rename dialog.

3. Enter the new name and click Refactor.

IntelliJ IDEA updates all references across the build files automatically.

## What's next

After migrating to the Kotlin DSL, you can explore more IDE features for Gradle projects:

* [Run and manage Gradle tasks](work-with-gradle-tasks.html)

* [Visualize project dependencies](work-with-gradle-dependency-diagram.html)

* [Getting started with Gradle in IntelliJ IDEA](getting-started-with-gradle.html)