When developing for resource-constrained environments, experimenting with language internals, or creating a custom runtime for educational purposes, you might wonder: Can you compile and run a Kotlin project without kotlin-stdlib?

If you've tried excluding org.jetbrains.kotlin:kotlin-stdlib in Gradle, you likely ran into immediate compiler or runtime crashes, such as:

java.lang.NoClassDefFoundError: kotlin/jvm/internal/Intrinsics

In this guide, we will break down why this happens and explore the exact compiler flags and Gradle configurations needed to build a Kotlin project independent of the default standard library.

Why Does Kotlin Depend on the Standard Library by Default?

Even for basic constructs, the Kotlin compiler generates bytecode that calls into runtime helper classes. The most prominent is kotlin.jvm.internal.Intrinsics, which provides runtime null-safety checks (such as checking non-nullable parameters at the beginning of method calls).

Additionally, modern versions of the Kotlin Gradle Plugin automatically inject kotlin-stdlib as a dependency unless explicitly told otherwise.

Step 1: Disable the Default Stdlib in Gradle

Since Kotlin 1.4, the Gradle plugin automatically includes the standard library dependency. To disable this behavior globally across your project, add the following line to your gradle.properties file:

kotlin.stdlib.default.dependency=false

This stops Gradle from injecting kotlin-stdlib into your project's compile and runtime classpaths automatically.

Step 2: Tell the Kotlin Compiler to Ignore the Stdlib

Even if Gradle doesn't provide the library, the Kotlin compiler itself expects one to be present unless you pass the -no-stdlib flag. You also need to disable the compiler assertions that generate calls to kotlin.jvm.internal.Intrinsics.

Update your build.gradle.kts with the following compiler options:

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {\n    compilerOptions {\n        freeCompilerArgs.addAll(\n            "-no-stdlib",\n            "-Xno-param-assertions",\n            "-Xno-call-assertions"\n        )\n    }\n}
  • -no-stdlib: Instructs kotlinc not to include the bundled Kotlin standard library on the classpath.
  • -Xno-param-assertions: Prevents the compiler from generating calls like Intrinsics.checkNotNullParameter() at the start of functions.
  • -Xno-call-assertions: Prevents generated null-checks on the results of Java platform calls.

Step 3: Providing Minimal Runtime Classes

Even with assertions disabled, Kotlin requires foundational language structures to be defined somewhere. If you write your own standard library, you must provide your own definitions for essential constructs, such as:

  • kotlin.Unit
  • kotlin.Any
  • kotlin.Nothing
  • kotlin.jvm.internal.Intrinsics (for certain primitive and reflection calls)

By default, the compiler prohibits user code from declaring classes in the kotlin root package. To allow your custom standard library to define these core structures, add the internal compiler flag to your Gradle configuration:

freeCompilerArgs.add("-Xallow-kotlin-package")

Example: A Bare-Bones Intrinsics Stub

If you encounter cases where the compiler still looks for Intrinsics, you can stub out the class in your own sources:

package kotlin.jvm.internal\n\nobject Intrinsics {\n    @JvmStatic\n    fun checkNotNull(value: Any?) {\n        if (value == null) throw NullPointerException()\n    }\n}

Can You Rely Purely on Java's Standard Library?

Kotlin's basic types (like Int, String, and List) map to Java primitives or standard Java objects (like java.lang.String and java.util.List) at compile time. However, Kotlin relies on its own collection and utility abstractions that sit on top of the Java runtime.

While you can compile pure Kotlin code without the official kotlin-stdlib artifact, you cannot completely dispense with Kotlin's core types. You must either provide a minimal stub containing the runtime symbols the compiler expects, or compile your project alongside your own replacement library.

Summary

To create a Kotlin project without the standard library:

  1. Set kotlin.stdlib.default.dependency=false in gradle.properties.
  2. Pass -no-stdlib, -Xno-param-assertions, and -Xno-call-assertions via compilerOptions.freeCompilerArgs.
  3. If defining core classes inside the kotlin.* namespace, enable -Xallow-kotlin-package.