/commands /kotlin/kotlinc-compile-to-jar

kotlinc hello.kt -include-runtime -d hello.jar: compile and run Kotlin from the command line

updated 2026-10-23

tool: Kotlin
versions: Kotlin 1.x – 2.x (JVM)
os: linux, macos, windows

kotlinc hello.kt -include-runtime -d hello.jar compiles a Kotlin file into a self-contained JAR, and java -jar hello.jar runs it. -d sets the output, either a .jar file or a directory of class files, and -include-runtime puts the Kotlin standard library into the JAR so it runs with nothing but a JVM. The compiler comes with every Kotlin release as a standalone download, or through SDKMAN!, Homebrew or Snap.

Compile and run

hello.kt

fun main(args: Array<String>) {
    val name = args.firstOrNull() ?: "World"
    println("Hello, $name!")
}

bash

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

The first run prints Hello, World!, the second Hello, Kotlin!. Compilation takes a few seconds, because the compiler itself runs on the JVM.

Options and variants

Command	What it does
kotlinc hello.kt -include-runtime -d hello.jar	Self-contained, runnable JAR
kotlinc hello.kt -d hello.jar	Library JAR without the Kotlin runtime; it needs kotlin-stdlib on the class path
kotlinc hello.kt -d out	Write .class files into the out directory
kotlinc src -include-runtime -d app.jar	Compile every .kt file in a directory
kotlinc -script list.kts	Run a Kotlin script (.kts) without producing a JAR
kotlinc -jvm-target 17 hello.kt -d hello.jar	Generate bytecode for a specific JVM version
kotlinc -help	List the available compiler options

Running class files

Without -include-runtime, run the code with the Kotlin runtime on the class path. The class to start is the file name with Kt appended (hello.kt becomes HelloKt). The kotlin script in the compiler's bin folder adds the standard library for you:

bash

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

Pitfalls

kotlinc: command not found. The compiler is not installed or its bin folder is not on PATH. On Windows the documentation recommends the manual install: unzip the compiler and add kotlinc\bin to PATH.
No main manifest attribute. A JAR built without -include-runtime has no Main-Class; java -jar refuses it. Use -include-runtime or run it with kotlin -classpath.
Wrong class name. java -cp out Hello fails with Could not find or load main class: the class is HelloKt, or the name of the object or class that holds main.
Unresolved references. Using a library that is not on the class path fails with Unresolved reference. Pass it with -cp lib.jar, or switch to Gradle, which downloads dependencies.
JVM version. Running bytecode for a newer JVM on an older Java fails with UnsupportedClassVersionError; set -jvm-target to the oldest Java you support.

Confirm it worked

java -jar hello.jar prints the greeting, and jar tf hello.jar (or jar --list --file hello.jar) shows HelloKt.class and the kotlin/ standard library packages inside the JAR.

FAQ

Why is the main class called HelloKt?

Top-level functions in hello.kt are compiled into a class named after the file with Kt appended. -include-runtime writes it as the Main-Class of the JAR, so java -jar finds it; with -cp you have to name HelloKt yourself.

Do I need kotlinc to run the JAR on another machine?

No. A JAR built with -include-runtime contains the Kotlin standard library and needs only a Java runtime: java -jar hello.jar.

How do I compile several files?

Pass them all, or a directory: kotlinc src -include-runtime -d app.jar. For projects with dependencies, use Gradle or Maven with the Kotlin plugin instead of kotlinc.

Sources

errors · kotlinKotlin: error: unresolved reference 'x' (Unresolved reference: x)Kotlin unresolved reference means no visible declaration has that name: a typo, a missing import or a dependency not on the classpath. Fix it and sync Gradle.commands · javajar --create --main-class: create an executable JAR and run it with java -jarCreate an executable JAR with jar --create --file app.jar --main-class and run it with java -jar. Manifest Class-Path, no main manifest attribute, and jar cfe.errors · javaError: Could not find or load main classJava cannot find the class you asked it to run: a package class run by its short name, or a wrong -cp. Use the fully qualified name from the root. Real output.