---
title: "A More Reliable Compilation Scheme for Kotlin Multiplatform Modules"
description: "Kotlin Multiplatform’s current compilation scheme can cause IDE and compiler disagreements or unexpected resolution of platform-specific declarations from common source sets. In Kotlin 2.5.0-Beta1, an optional separate compilation approach aligns compiler behavior with IDE analysis, making common code resolve only against metadata KLIB declarations. This also eliminates issues like overload selection differing by target and type inference failures in platform code. Separate compilation is experimental and disabled by default, enabled by adding kotlin.kmp.separateCompilation=true to gradle.properties. Known issues include problems with cinterop commonization and single-target modules; library authors must publish metadata KLIBs for the feature to work correctly."
---

# A More Reliable Compilation Scheme for Kotlin Multiplatform Modules

[Jetbrains](https://yomu.fyi/company/jetbrains) · Aleksey Zamulla · Sep 28, 2026

**Type:** Announcement

## Summary

Kotlin Multiplatform’s current compilation scheme can cause IDE and compiler disagreements or unexpected resolution of platform-specific declarations from common source sets. In Kotlin 2.5.0-Beta1, an optional separate compilation approach aligns compiler behavior with IDE analysis, making common code resolve only against metadata KLIB declarations. This also eliminates issues like overload selection differing by target and type inference failures in platform code. Separate compilation is experimental and disabled by default, enabled by adding kotlin.kmp.separateCompilation=true to gradle.properties. Known issues include problems with cinterop commonization and single-target modules; library authors must publish metadata KLIBs for the feature to work correctly.

## Context

Kotlin Multiplatform projects with multiple source sets (e.g., commonMain and jvmMain) produce platform artifacts and metadata KLIBs. During compilation of a platform source set, the compiler compiles common source set code against the platform artifacts of dependencies, which can lead to unexpected resolution of platform-only declarations. The IDE, however, resolves common code against only the metadata KLIB (common declarations), causing disagreements between IDE analysis and compiler behavior.

## Takeaways

- Separate compilation resolves common source set calls using metadata KLIBs only, preventing implicit resolution to platform declarations.
- Enable separate compilation by setting kotlin.kmp.separateCompilation=true in gradle.properties; it is experimental and disabled by default.
- Library authors must publish metadata KLIBs for separate compilation to work correctly in downstream projects.

## FAQ

### How do I enable separate compilation?

Add the compiler option kotlin.kmp.separateCompilation=true to your gradle.properties file. The feature is experimental and disabled by default.

### What is needed from library authors?

Library authors must publish metadata KLIBs for separate compilation to work correctly. The KMP Gradle plugin does this by default, but it becomes essential under the new compilation scheme.

### Are there known issues?

Yes. For example, with commonization of cinterops (issues KT-88178, KT-41509) and various smaller problems (KT-88148). KMP modules with a single declared target are not affected.

**Tags:** [Compilation](https://yomu.fyi/topic/compilation), [Kotlin Multiplatform](https://yomu.fyi/topic/kotlin-multiplatform)

- Source: [Jetbrains](https://blog.jetbrains.com/kotlin/2026/09/a-more-reliable-compilation-scheme-for-kotlin-multiplatform-modules)
- Source URL: https://blog.jetbrains.com/kotlin/2026/09/a-more-reliable-compilation-scheme-for-kotlin-multiplatform-modules
- Ingested by Yomu: 2026-09-28T12:00:12.573Z

[Read original post](https://blog.jetbrains.com/kotlin/2026/09/a-more-reliable-compilation-scheme-for-kotlin-multiplatform-modules)