Migrate Gradle build scripts to Kotlin DSL

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.

Rename build.gradle to build.gradle.kts

In the Project tool window, right-click build.gradle and select Refactor | Rename Shift+F6.
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.

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 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.

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

                        repositories {
                            mavenCentral()
                        }

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

                        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:

applicationDefaultJvmArgs = ["-Dfile.encoding=UTF-8"]

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.

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

                    

                        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:

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

                    

                         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.

                        test {
                            useJUnitPlatform()
                        }
                    

                        tasks.test {
                            useJUnitPlatform()
                        }
                    

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.

Replace apply plugin with the plugins block

Open build.gradle.kts in the editor.
If your script applies plugins with apply(plugin = "..."), IntelliJ IDEA underlines the call and shows a warning.
apply(plugin = "java") // highlighted by inspection apply(plugin = "application")
Place the caret on the highlighted call and press Alt+Enter 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.
plugins { java application }
However, if you have a third-party plugin, then the following syntax applies:
plugins { id("com.github.johnrengelman.shadow") version "8.1.1" }
Sync the Gradle 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.

Remove the redundant stdlib dependency

Open build.gradle.kts.
If you have applied the kotlin("jvm") plugin and also declared stdlib explicitly, IntelliJ IDEA marks the dependency as redundant:
plugins { kotlin("jvm") version "2.1.0" } dependencies { implementation(kotlin("stdlib")) // highlighted as redundant }
Place the caret on the highlighted dependency and press Alt+Enter. Select Remove redundant dependency.
IntelliJ IDEA removes the explicit stdlib declaration. The dependency is still on the classpath via the Kotlin plugin.

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.

Rename a symbol used in build files

Place the caret on any symbol you want to rename — for example, a property declared in buildSrc and referenced in build.gradle.kts.
Press Shift+F6 to open the Rename dialog.
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:

04 June 2026