Configure a Maven project

When you introduce Kotlin to your existing Java Maven project or create a new Kotlin Maven project, you need to add the Kotlin Maven plugin that compiles Kotlin sources and modules.

Currently, only Maven v3 is supported.

Automatic configuration

You can simplify Maven configuration in both mixed Java-Kotlin projects and in pure Kotlin projects using the <extensions> option. This approach saves you time because you don't need to configure the Maven compiler plugin.

To apply the Kotlin Maven plugin with <extensions>, update your pom.xml build file as follows:

In the <properties> section, define the version of Kotlin you want to use in the kotlin.version property:
<properties> <kotlin.version>2.3.21</kotlin.version> </properties>
In the <build><plugins> section, add the Kotlin Maven plugin with the enabled <extensions> option:
<build> <plugins>  <plugin> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-plugin</artifactId> <version>${kotlin.version}</version> <extensions>true</extensions>  </plugin>  </plugins> </build>

The <extensions> option:

Registers src/main/kotlin and src/test/kotlin directories as source roots if they already exist but are not specified in the plugin configuration.
Adds the kotlin-stdlib dependency if it's not already defined in the project.
Adds compile, test-compile, kapt, and test-kapt executions to your build, bound to their appropriate lifecycle phases. So you don't need to manually set up the <executions> section with <id> and <goals>.

If you have a mixed Java and Kotlin project, the configuration ensures that:

Kotlin code is compiled first.
Java code is compiled after Kotlin and can reference Kotlin classes.
Default Maven behavior doesn't override the plugin order.

The extension configuration replaces the whole <executions> section. If you need to configure an execution, see an example in Compile Kotlin and Java sources.

Change Maven compiler version

Currently, the default version of the Maven compiler plugin used with <extensions> is 3.10.1. You can set a different version separately:

<build>
    <plugins>
        <!-- Kotlin compiler plugin configuration -->
        <plugin>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-plugin</artifactId>
            <version>${kotlin.version}</version>
            <extensions>true</extensions>
        </plugin>
        <!-- Maven compiler plugin configuration for Java classes -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.15.0</version>
        </plugin>
    </plugins>
</build>

Manual configuration

Without enabling <extensions> in the Kotlin Maven plugin, you need to configure the project manually to ensure that the source code compiles correctly.

You can set up your Maven project to compile a combination of Java and Kotlin sources or Kotlin-only sources.

Compile Kotlin and Java sources

To compile a project with both Kotlin and Java source files, ensure that the Kotlin compiler runs before the Java compiler.

The Java compiler can't see Kotlin declarations until they are compiled into .class files. If your Java code uses Kotlin classes, those classes must be compiled first to avoid cannot find symbol errors.

Maven determines plugin execution order based on two main factors:

The order of plugin declarations in the pom.xml file.
Built-in default executions, such as default-compile and default-testCompile, which always run before user-defined executions, regardless of their position in the pom.xml file.

To control the execution order:

Declare kotlin-maven-plugin before maven-compiler-plugin.
Disable the Java compiler plugin's default executions.
Add custom executions to control compile phases explicitly.

To apply the Kotlin Maven plugin, update your pom.xml build file as follows:

<build>
    <plugins>
        <!-- Kotlin compiler plugin configuration -->
        <plugin>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-plugin</artifactId>
            <version>${kotlin.version}</version>
            <executions>
                <execution>
                    <id>kotlin-compile</id>
                    <phase>compile</phase>
                    <goals>
                        <goal>compile</goal>
                    </goals>
                    <configuration>
                        <sourceDirs>
                            <sourceDir>src/main/kotlin</sourceDir>
                            <!-- Ensure Kotlin code can reference Java code -->
                            <sourceDir>src/main/java</sourceDir>
                        </sourceDirs>
                    </configuration>
                </execution>
                <execution>
                    <id>kotlin-test-compile</id>
                    <phase>test-compile</phase>
                    <goals>
                        <goal>test-compile</goal>
                    </goals>
                    <configuration>
                        <sourceDirs>
                            <sourceDir>src/test/kotlin</sourceDir>
                            <sourceDir>src/test/java</sourceDir>
                        </sourceDirs>
                    </configuration>
                </execution>
            </executions>
        </plugin>

        <!-- Maven compiler plugin configuration -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.15.0</version>
            <executions>
                <!-- Disable default executions -->
                <execution>
                    <id>default-compile</id>
                    <phase>none</phase>
                </execution>
                <execution>
                    <id>default-testCompile</id>
                    <phase>none</phase>
                </execution>

                <!-- Define custom executions -->
                <execution>
                    <id>java-compile</id>
                    <phase>compile</phase>
                    <goals>
                        <goal>compile</goal>
                    </goals>
                </execution>
                <execution>
                    <id>java-test-compile</id>
                    <phase>test-compile</phase>
                    <goals>
                        <goal>testCompile</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

This configuration ensures that:

Kotlin code is compiled first.
Java code is compiled after Kotlin and can reference Kotlin classes.
Default Maven behavior doesn't override the plugin order.

For more details on how Maven handles plugin executions, see Guide to default plugin execution IDs in the official Maven documentation.

Compile Kotlin-only sources

To compile a project with just Kotlin source files, declare source roots and configure the Kotlin Maven plugin:

Specify the source directories in the <build> section:
<build> <sourceDirectory>src/main/kotlin</sourceDirectory> <testSourceDirectory>src/test/kotlin</testSourceDirectory> </build>
Ensure that the Kotlin Maven plugin is applied:
<build> <plugins> <plugin> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-plugin</artifactId> <version>${kotlin.version}</version> <executions> <execution> <id>compile</id> <goals> <goal>compile</goal> </goals> </execution> <execution> <id>test-compile</id> <goals> <goal>test-compile</goal> </goals> </execution> </executions> </plugin> </plugins> </build>

Use JDK 17

To use JDK 17, in your .mvn/jvm.config file, add:

--add-opens=java.base/java.lang=ALL-UNNAMED
--add-opens=java.base/java.io=ALL-UNNAMED

What's next?

Set dependencies in your Kotlin Maven project

16 April 2026