Kotlin — User Guide

Kotlin is a concise, multiplatform programming language developed by JetBrains and contributors. It compiles to JVM bytecode, JavaScript, native binaries (via LLVM), and WebAssembly from a single language and standard library. This guide shows you how to install the Kotlin toolchain, compile and run Kotlin code from the command line, build projects with Gradle and Maven, target multiple platforms, and use the bundled compiler plugins.

Note

This guide documents the Kotlin compiler and toolchain as built from the JetBrains/kotlin repository on the development branch for Kotlin 2.4 (default language version 2.4). Where a feature was introduced in an earlier release, that release is noted. The kotlinlang.org site hosts the always-current narrative tutorials; this guide is the source-based reference for the compiler's own command-line surface.

1. Quick Start

1.1 Your first program

Create a file named hello.kt:

fun main() {
    println("Hello, Kotlin!")
}

Compile it to a self-contained JAR and run it:

kotlinc hello.kt -include-runtime -d hello.jar
java -jar hello.jar

Hello, Kotlin!

Tip

The -include-runtime flag bundles the Kotlin standard library into the JAR so it runs anywhere a JVM is available, with no extra classpath setup. Omit it when you manage the kotlin-stdlib dependency yourself (for example, in a Gradle build).

1.2 Run without producing a JAR

Compile to a directory and launch with the kotlin runner, which locates the entry point for you:

kotlinc hello.kt -d hello/
kotlin -classpath hello/ HelloKt

Hello, Kotlin!

Note

A top-level main in hello.kt is compiled into a class named HelloKt (the file name, capitalized, with Kt appended). This is the class you pass to kotlin or java.

1.3 Evaluate an expression directly

kotlinc -e "println((1..10).sum())"

55

1.4 Run a script

Kotlin scripts use the .kts extension and need no main function:

// fib.kts
fun fib(n: Int): Int = if (n < 2) n else fib(n - 1) + fib(n - 2)
println((0..10).map(::fib))

kotlinc -script fib.kts

[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]

2. Installation

The command-line compiler ships as a kotlin-compiler-<version>.zip archive containing the kotlinc, kotlinc-jvm, kotlinc-js, and kotlin launcher scripts under a bin/ directory. You can install it through a package manager or unpack it manually.

SDKMAN! (Linux/macOS)

sdk install kotlin
kotlinc -version

Homebrew (macOS)

brew install kotlin
kotlinc -version

Manual (any OS)

# Download kotlin-compiler-<version>.zip from the GitHub Releases page,
# then unzip and add the bin directory to your PATH:
unzip kotlin-compiler-*.zip -d ~/kotlin
export PATH="$PATH:~/kotlin/kotlinc/bin"
kotlinc -version

Windows (Scoop)

scoop install kotlin
kotlinc -version

Important

The command-line compiler requires a Java runtime (JRE/JDK) to execute, because kotlinc itself runs on the JVM. A JDK is also needed to run the Kotlin/JVM output you produce. Install a JDK (for example, from Eclipse Adoptium) and ensure JAVA_HOME points at it before using kotlinc.

2.1 Verify the installation

kotlinc -version

info: kotlinc-jvm 2.4.0 (JRE 21.0.x+...)

2.2 Requirements

Tip

For real projects, you rarely call kotlinc directly. Use Gradle or Maven (Section 7) so dependency resolution, incremental compilation, and multiplatform target wiring are handled for you. The command-line compiler is ideal for small programs, scripts, experiments, and understanding exactly what the build tools invoke under the hood.

3. Using the Command-Line Compiler

The Kotlin distribution provides several launchers:

A kotlinc invocation has the form:

kotlinc [<options>] <source files and directories>

Source arguments may be individual .kt/.kts files or directories, which are scanned recursively.

3.1 Compiling to a directory or JAR

# Compile every .kt under src/ into the classes/ directory
kotlinc src/ -d classes/

# Compile into a single runnable JAR with the runtime bundled
kotlinc src/ -include-runtime -d app.jar

The -d option (<directory|jar>) sets the destination. If the path ends in .jar, a JAR is produced; otherwise class files are written into the directory.

3.2 Adding libraries to the classpath

kotlinc app.kt -classpath "libs/guava.jar:libs/gson.jar" -d app.jar

Note

-classpath (short form -cp) accepts a list of directories and JAR/ZIP archives separated by your platform's path separator (: on Unix/macOS, ; on Windows).

3.3 Running compiled code with kotlin

The kotlin runner inspects its argument and decides how to run it. You can force the mode:

kotlin -classpath app.jar MainKt          # guess (default)
kotlin -howtorun jar app.jar              # run as a JAR
kotlin -howtorun classfile -cp out/ MainKt # run a compiled class
kotlin -howtorun script analysis.kts      # run as a script

Important

The kotlin runner needs to know where the distribution lives; the launcher script sets the kotlin.home system property for you. If you invoke the runner JAR directly, you must pass -Dkotlin.home=<path>, or it exits with error: no kotlin.home system property was passed.

3.4 The REPL

Starting kotlinc with no source files opens an interactive shell:

kotlinc

Welcome to Kotlin version 2.4.0 (JRE 21.0.x)
Type :help for help, :quit for quit
>>> val x = 21
>>> x * 2
res2: kotlin.Int = 42

Warning

The dedicated -Xrepl flag is deprecated. Launch the REPL by running kotlinc with no input files instead.

4. Compiler Options Reference

Kotlin distinguishes standard options (stable, documented, safe for everyday use) from advanced options, which begin with -X. Advanced options control experimental behavior and may change between releases. Run kotlinc -help for standard options and kotlinc -X for the advanced set.

4.1 Common options (all targets)

These options apply to every compilation target.

Tip

Use -progressive in new code to adopt the strictest, most future-proof behavior early. Because progressive-mode code remains backward compatible, you can turn it on without breaking consumers who compile in the default mode.

Selected advanced common options

Caution

Options beginning with -XX (for example -XXLanguage, -XXlenient-mode) are internal and are not intended for production use. They can change or be removed without notice and may slow down or destabilize the compiler.

4.2 Kotlin/JVM options

Note

-jvm-default replaces the deprecated -Xjvm-default. Migrate all-compatibility → enable, all → no-compatibility, and disable → disable.

Selected advanced JVM options

Tip

Set -jvm-target to match the JDK you deploy on. To both target an older API and prevent accidental use of newer JDK APIs, prefer -Xjdk-release=<version> over -jvm-target alone — it validates your code against that JDK's API surface, just like javac --release.

4.3 Kotlin/JS options

Note

Kotlin/JS uses the IR backend. Many JS controls are advanced (-X) options: -Xir-per-module / -Xir-per-file (output granularity), -Xir-dce (dead-code elimination), -Xgenerate-dts (emit a TypeScript .d.ts), and -Xes-classes/-Xes-arrow-functions/-Xes-generators (ES2015 codegen).

4.4 Kotlin/Native options

The Native compiler (konanc, normally invoked through Gradle) produces executables, libraries, and Apple frameworks via LLVM.

Tip

To build an Apple framework for iOS/macOS interop, use -produce framework -target ios_arm64. Advanced caching options like -Xauto-cache-from and -Xic-cache-dir speed up repeated Native builds; in practice the Kotlin Gradle plugin manages these for you.

4.5 Kotlin/Wasm options

WebAssembly support is driven entirely through advanced options:

Note

Kotlin/Wasm is experimental. Build it through the Kotlin Gradle plugin's wasmJs or wasmWasi targets rather than calling the compiler directly.

5. Language Version and API Version

Two options control which language features and library declarations are available:

• -language-version <version> — accept the syntax and semantics of that Kotlin version. Use it to keep a codebase on an older dialect while running a newer compiler.
• -api-version <version> — restrict usage to declarations available in that version of the bundled libraries, so you don't accidentally depend on newer stdlib APIs.

# Compile with the 2.4 compiler but stay source-compatible with 2.2 and
# only use stdlib API present in 2.2
kotlinc app.kt -language-version 2.2 -api-version 2.2 -d app.jar

Important

-api-version cannot be greater than -language-version. If you must build the standard library itself (an unusual case), the compiler offers -Xsuppress-api-version-greater-than-language-version-error, but application code should never need it.

Tip

Adopt experimental features gradually. Most experimental language features are gated behind their own -X flag (for example -Xcontext-parameters, -Xwhen-guards, -Xmulti-dollar-interpolation). Turn them on individually rather than relying on -XXLanguage, which is an internal escape hatch.

6. Scripting

Kotlin scripts (.kts) are programs that run top-to-top without a main function. They are useful for build logic, automation, and quick computations.

// listSizes.main.kts
import java.io.File

File(".").walkTopDown()
    .filter { it.isFile && it.extension == "kt" }
    .forEach { println("${it.length()}\t${it.path}") }

kotlinc -script listSizes.main.kts

Note

The scripting plugin is enabled by default. You can disable default script support with -Xdisable-default-scripting-plugin, set a custom resolver environment with -Xscript-resolver-environment=key=value, or provide your own script definitions with -script-templates. The .main.kts extension activates a script template that supports @file:DependsOn(...) and @file:Repository(...) annotations for declaring dependencies inline.

Warning

Use -Xallow-any-scripts-in-source-roots only when you deliberately want scripts compiled alongside regular sources. By default, scripts in source roots are not compiled as ordinary .kt files.

7. Building Projects with Gradle and Maven

For anything larger than a single file, use a build tool. Both apply the Kotlin compiler with the right classpath, incremental compilation, and target wiring.

7.1 Gradle (recommended)

A minimal Kotlin/JVM build using the Kotlin Gradle plugin:

// build.gradle.kts
plugins {
    kotlin("jvm") version "2.4.0"
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.jetbrains.kotlin:kotlin-stdlib")
    testImplementation(kotlin("test"))
}

Build and test:

./gradlew build
./gradlew test

Configure compiler options through the plugin's DSL rather than raw flags:

kotlin {
    compilerOptions {
        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
        languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_4)
        allWarningsAsErrors.set(true)
    }
}

Tip

Multiplatform projects apply kotlin("multiplatform") and declare targets (jvm(), js(), iosArm64(), wasmJs(), …) in a single build script. The plugin sets up the commonMain source set plus per-platform source sets so you write shared code once and platform-specific code where needed.

7.2 Maven

The Kotlin Maven plugin compiles src/main/kotlin through the kotlin-maven-plugin:

<plugin>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-maven-plugin</artifactId>
    <version>${kotlin.version}</version>
    <executions>
        <execution>
            <id>compile</id>
            <phase>compile</phase>
            <goals><goal>compile</goal></goals>
        </execution>
    </executions>
</plugin>

mvn compile
mvn test

Note

Pass compiler options through <configuration><args> in the plugin block (for example <arg>-Xjsr305=strict</arg>), and add compiler plugins through <compilerPlugins>. The Maven plugin and several other library artifacts are built separately with Maven in this repository (see libraries/ReadMe.md).

8. Multiplatform at a Glance

Kotlin compiles the same language and standard library to several targets. You usually select targets in your Gradle build; under the hood each maps to a compiler backend.

Shared code lives in a common source set and uses expect/actual declarations to bind to platform-specific implementations:

// commonMain
expect fun platformName(): String

// jvmMain
actual fun platformName(): String = "JVM"

// nativeMain
actual fun platformName(): String = "Native"

Note

Compiling common code requires multiplatform support. The Gradle plugin enables it automatically; at the raw-compiler level it is -Xmulti-platform. Cross-platform libraries are distributed as .klib files and passed with -Xklib (JVM) or -library/-l (Native).

9. The Standard Library

Every Kotlin program links against kotlin-stdlib, which provides the core types and thousands of functions. Highlights you will use constantly:

• Collections — List, Set, Map, and a rich set of operators: map, filter, fold, groupBy, associateBy, sortedBy, windowed, chunked.
• Sequences — lazy pipelines via asSequence() for large or infinite data.
• Scope functions — let, run, with, apply, also for concise object configuration and null handling.
• Null safety helpers — ?., ?:, requireNotNull, checkNotNull, takeIf, takeUnless.
• Text — String extensions like trimIndent, split, substringBefore, lines, and multi-dollar string interpolation (experimental, -Xmulti-dollar-interpolation).
• Result and contracts — Result<T>, runCatching, and kotlin.contracts for smarter compiler analysis.

val byFirstLetter = listOf("apple", "apricot", "banana", "cherry")
    .groupBy { it.first() }
// {a=[apple, apricot], b=[banana], c=[cherry]}

Tip

The stdlib ships platform-tailored variants — jvm, js, native-wasm, wasm, plus jdk7/jdk8 add-ons that expose newer JDK APIs (such as java.time and java.nio.file helpers). On the JVM, -no-stdlib removes it from the classpath; you almost never want that outside of building the stdlib itself.

Note

kotlin.test provides a multiplatform assertion API (assertEquals, assertTrue, assertFailsWith) that delegates to the underlying framework (JUnit on JVM, Mocha on JS, and so on). Add it with testImplementation(kotlin("test")).

10. Compiler Plugins

The Kotlin distribution bundles compiler plugins that generate or transform code at compile time. Enable them through your build tool (each has a Gradle plugin id) or with -Xplugin/-P on the command line.

Example — applying serialization in Gradle:

plugins {
    kotlin("jvm") version "2.4.0"
    kotlin("plugin.serialization") version "2.4.0"
}

import kotlinx.serialization.*
import kotlinx.serialization.json.Json

@Serializable
data class Point(val x: Int, val y: Int)

fun main() {
    val json = Json.encodeToString(Point(1, 2))
    println(json)                       // {"x":1,"y":2}
    println(Json.decodeFromString<Point>(json))
}

Note

allopen, noarg, and sam-with-receiver ship preconfigured presets — kotlin("plugin.spring"), kotlin("plugin.jpa") — that apply the plugin with the right marker annotations for those frameworks.

Tip

To pass an option to a plugin from the command line, use -P plugin:<pluginId>:<optionName>=<value> and load the plugin jar with -Xplugin=<path>. Build tools translate their DSL into exactly these flags.

11. Troubleshooting

Error: no kotlin.home system property was passed

Cause: The kotlin runner was started without the distribution location. Solution: Use the kotlin launcher script (which sets -Dkotlin.home) rather than invoking the runner JAR directly, or pass -Dkotlin.home=<path-to-kotlinc>. Prevention: Keep kotlinc/bin on your PATH and call kotlin/kotlinc, not the jars.

Error: error: unable to find main(...) / wrong class name when running

Cause: A top-level main in foo.kt compiles to FooKt, not Foo or Main. Solution: Run kotlin -cp out/ FooKt (file name capitalized + Kt). Prevention: Build a JAR with -include-runtime -d app.jar and run java -jar app.jar; the manifest records the correct entry point.

Error: cannot access built-in declaration with -no-stdlib

Cause: You removed the stdlib from the classpath. Solution: Drop -no-stdlib, or, when you genuinely build without it, add -Xsuppress-missing-builtins-error. Prevention: Let the build tool manage the stdlib dependency.

Error: Inconsistent JVM-target compatibility detected

Cause: Kotlin's -jvm-target and Java's compile target differ in a mixed module. Solution: Set both to the same value — -jvm-target 17 and --release 17 (or the Gradle jvmTarget/sourceCompatibility equivalents). Prevention: Configure one JVM toolchain in Gradle and let it drive both compilers.

Warning: language version X is deprecated

Cause: You pinned -language-version to a version the current compiler is phasing out. Solution: Move to a supported version, or temporarily quiet it with -Xsuppress-version-warnings. Prevention: Track the language version forward as you upgrade the compiler.

Build fails: Dependency verification failed (building Kotlin from source)

Cause: The repository enables Gradle dependency verification; a local artifact is missing or has a different hash than gradle/verification-metadata.xml. Solution: Re-resolve and regenerate metadata with ./gradlew --write-verification-metadata sha256 -Pkotlin.native.enabled=true resolveDependencies (or run ./scripts/update-verification-metadata.sh). Prevention: Only update verification-metadata.xml in commits that change the build.

Windows: Filename too long during a source checkout or build

Cause: Deeply nested test-data paths exceed Windows' default path limit. Solution: Enable long paths for the repo: git config core.longpaths true. Prevention: Clone with long paths enabled from the start.

First Native or idea-full build times out

Cause: Kotlin/Native and IDE dependencies (intellij-core, idea-full) are large downloads. Solution: Increase timeouts: ./gradlew -Dhttp.socketTimeout=60000 -Dhttp.connectionTimeout=60000 <task>. Prevention: Run the first build on a fast connection; subsequent builds reuse the cache.

12. FAQ

Q: What is the difference between kotlinc and kotlinc-jvm? kotlinc is an alias for kotlinc-jvm. Use kotlinc-js to target JavaScript. Kotlin/Native and Kotlin/Wasm are normally built through Gradle.

Q: Do I need a JDK to use Kotlin? Yes for Kotlin/JVM — kotlinc runs on the JVM and produces bytecode that runs on a JDK/JRE. Kotlin/Native produces standalone binaries that don't require a JVM at runtime, but you still build them with the toolchain.

Q: How do I pick the bytecode version? Use -jvm-target <version> (1.8 and 9–26, default 1.8). To also validate against that JDK's API surface, prefer -Xjdk-release=<version>.

Q: What language version does this compiler default to? The default language version on this branch is 2.4. Override it with -language-version to stay source-compatible with an older dialect.

Q: How do I enable an experimental feature? Turn on its specific -X flag (for example -Xcontext-parameters). Avoid -XXLanguage, which is an internal escape hatch not meant for production.

Q: How do I make a runnable JAR? kotlinc src/ -include-runtime -d app.jar, then java -jar app.jar. The -include-runtime flag bundles the stdlib.

Q: How do I run a .kts script? kotlinc -script myScript.kts. For dependency-aware scripts, use the .main.kts extension and @file:DependsOn(...) annotations.

Q: What's the difference between standard and -X options? Standard options (shown by -help) are stable. -X options (shown by -X) are advanced and may change between releases. -XX options are internal and unsupported.

Q: Should I call kotlinc directly in a real project? No — use Gradle or Maven. They handle dependency resolution, incremental compilation, multiplatform targets, and plugin wiring. The CLI is best for scripts, experiments, and learning.

Q: How do I add Kotlin serialization, Spring openness, or JPA no-arg constructors? Apply the matching Gradle plugin: kotlin("plugin.serialization"), kotlin("plugin.spring"), or kotlin("plugin.jpa"). See Section 10.

Q: How do I share code across platforms? Apply kotlin("multiplatform"), declare your targets, write shared code in commonMain, and bind platform specifics with expect/actual.

Q: Where do I report bugs or request features? Kotlin is tracked in YouTrack under the KT project (youtrack.jetbrains.com/issues/KT). The repository's ChangeLog.md lists issues fixed per release.

Q: What license is Kotlin under? Apache License 2.0.

13. Command Reference