Gradle’s Kotlin DSL provides an alternative syntax to the traditional Groovy DSL with an enhanced editing experience in supported IDEs, with superior content assist, refactoring, documentation, and more. This chapter provides details of the main Kotlin DSL constructs and how to use it to interact with the Gradle API.

If you are interested in migrating an existing Gradle build to the Kotlin DSL, please also check out the dedicated migration section.

Prerequisites

  • The embedded Kotlin compiler is known to work on Linux, macOS, Windows, Cygwin, FreeBSD and Solaris on x86-64 architectures.

  • Knowledge of Kotlin syntax and basic language features is very helpful. The Kotlin reference documentation and Kotlin Koans will help you to learn the basics.

  • Use of the plugins {} block to declare Gradle plugins significantly improves the editing experience and is highly recommended.

IDE support

The Kotlin DSL is fully supported by IntelliJ IDEA and Android Studio. Other IDEs do not yet provide helpful tools for editing Kotlin DSL files, but you can still import Kotlin-DSL-based builds and work with them as usual.

Table 1. IDE support matrix
Build import Syntax highlighting 1 Semantic editor 2

IntelliJ IDEA

✓

✓

✓

Android Studio

✓

✓

✓

Eclipse IDE

✓

✓

✖

CLion

✓

✓

✖

Apache NetBeans

✓

✓

✖

Visual Studio Code (LSP)

✓

✓

✖

Visual Studio

✓

✖

✖

1 Kotlin syntax highlighting in Gradle Kotlin DSL scripts
2 code completion, navigation to sources, documentation, refactorings etc…​ in Gradle Kotlin DSL scripts

As mentioned in the limitations, you must import your project from the Gradle model to get content-assist and refactoring tools for Kotlin DSL scripts in IntelliJ IDEA.

Builds with slow configuration time might affect the IDE responsiveness, so please check out the performance section to help resolve such issues.

Automatic build import vs. automatic reloading of script dependencies

Both IntelliJ IDEA and Android Studio — which is derived from IntelliJ IDEA — will detect when you make changes to your build logic and offer two suggestions:

  1. Import the whole build again

    IntelliJ IDEA
    IntelliJ IDEA

  2. Reload script dependencies when editing a build script

    Reload script dependencies

We recommend that you disable automatic build import, but enable automatic reloading of script dependencies. That way you get early feedback while editing Gradle scripts and control over when the whole build setup gets synchronized with your IDE.

Troubleshooting

The IDE support is provided by two components:

  • The Kotlin Plugin used by IntelliJ IDEA/Android Studio

  • Gradle

The level of support varies based on the versions of each.

If you run into trouble, the first thing you should try is running ./gradlew tasks from the command line to see whether your issue is limited to the IDE. If you encounter the same problem from the command line, then the issue is with the build rather than the IDE integration.

If you can run the build successfully from the command line but your script editor is complaining, then you should try restarting your IDE and invalidating its caches.

If the above doesn’t work and you suspect an issue with the Kotlin DSL script editor, you can:

  • Run ./gradle tasks to get more details

  • Check the logs in one of these locations:

    • $HOME/Library/Logs/gradle-kotlin-dsl on Mac OS X

    • $HOME/.gradle-kotlin-dsl/log on Linux

    • $HOME/AppData/Local/gradle-kotlin-dsl/log on Windows

  • Open an issue on the Gradle issue tracker, including as much detail as you can.

From version 5.1 onwards, the log directory is cleaned up automatically. It is checked periodically (at most every 24 hours) and log files are deleted if they haven’t been used for 7 days.

If the above isn’t enough to pinpoint the problem, you can enable the org.gradle.kotlin.dsl.logging.tapi system property in your IDE. This will cause the Gradle Daemon to log extra information in its log file located in $HOME/.gradle/daemon. In IntelliJ IDEA this can be done by opening Help > Edit Custom VM Options…​ and adding -Dorg.gradle.kotlin.dsl.logging.tapi=true.

For IDE problems outside of the Kotlin DSL script editor, please open issues in the corresponding IDE’s issue tracker:

Lastly, if you face problems with Gradle itself or with the Kotlin DSL, please open issues on the Gradle issue tracker.

Kotlin DSL scripts

Just like the Groovy-based equivalent, the Kotlin DSL is implemented on top of Gradle’s Java API. Everything you can read in a Kotlin DSL script is Kotlin code compiled and executed by Gradle. Many of the objects, functions and properties you use in your build scripts come from the Gradle API and the APIs of the applied plugins.

You can use the Kotlin DSL reference search functionality to drill through the available members.

Script file names

  • Groovy DSL script files use the