Koin Annotations - from KSP to Kotlin Compiler

[arnaudgiuliani]

TL;DR — Koin Annotations is part of the main Koin project and is not deprecated. The legacy koin-ksp-compiler processor is deprecated and will be removed in a future Koin version.
Migrate to the Koin Compiler Plugin — your annotations stay exactly the same.

What is Koin Annotations?

Koin Annotations is the annotation-based way to define your dependencies in Koin — @Singleton, @Factory, @KoinViewModel, @Module, @ComponentScan, @Named, @InjectedParam, etc.

It is part of the main Koin project:

• Lives in the same repository
• Ships under the same Koin version as koin-core (covered by koin-bom)
• Same release cycle, same maintainers
• Full feature parity with the DSL — both are first-class citizens

Read more: What is Koin Annotations?

What's changing?

For a long time, Koin Annotations was processed by koin-ksp-compiler, a KSP-based annotation processor that generated Kotlin source files at build time.

We've replaced that pipeline with the Koin Compiler Plugin — a native Kotlin Compiler Plugin (K2) that integrates directly with the Kotlin compiler.

	koin-ksp-compiler (legacy)	Koin Compiler Plugin (now)
Status	⚠️ Deprecated	✅ Recommended
Tech	KSP annotation processor	Native Kotlin Compiler Plugin (K2)
Generated files	Yes (visible sources)	None
KMP setup	Per-target KSP configuration	Single Gradle plugin
Compile-time graph check	Limited	Full graph + per-module + call-site
Kotlin	1.x and 2.x	2.x (K2)

Read more: Koin Compiler Plugin

Your annotations don't change

This is the important part: migration does not touch your annotations.

// This code is identical before and after migration.
@Singleton
class UserRepository(private val api: ApiService)

@KoinViewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()

@Module
@ComponentScan("com.myapp")
class AppModule

• Same annotation names
• Same parameters (@Named, @InjectedParam, @Property, @Provided, …)
• Same module/component scan semantics

The only changes are at the build configuration level: you swap the KSP plugin for the Koin Compiler Plugin and delete the previously-generated sources.

Why migrate?

• Faster builds — no separate KSP round, no generated-file IO
• Simpler setup — one Gradle plugin, no per-target KSP config in KMP
• Cleaner project — no generated sources to commit/ignore
• Stronger compile-time safety — per-module, full-graph, and call-site validation
• Future-proof — koin-ksp-compiler will be removed in an upcoming Koin release

Migration links

• 📖 Migrating Koin Annotations: KSP to Compiler Plugin — step-by-step guide
• ⚙️ Koin Compiler Plugin Setup — Gradle configuration
• 🧠 Koin Compiler Plugin (overview) — how it works
• 📚 Koin Annotations Reference — full annotation catalog
• ❓ What is Koin Annotations? — recap of the annotation style

Need help?

If something doesn't migrate cleanly, please comment on this issue with:

• Your Kotlin version
• Your Koin version (before & after)
• The annotation(s) or module(s) involved
• The exact build error or unexpected behavior

We'll use this issue as the central place to track migration feedback during the deprecation window.

[xertrec]

For me the migration encountered some trouble.

• kotlin: 2.3.21
• koin:
  before: 4.1.1
  after: 4.2.1
• koin-plugin: 1.0.0-RC2
  I was using koin-annotations 2.3.1

The annotation used is @KoinViewModel and @InjectedParam.
The error is that all 3 params annotated with @InjectedParam, receive the same value, even when I send only one param and the rest are null

[arnaudgiuliani]

Hi @xertrec — confirmed working on Koin Compiler Plugin 1.0.0.

Verified on an Android playground (real by viewModel { parametersOf(…) }) with two @KoinViewModel shapes — same-type pair (String, String) and mixed-type pair (String, Int). Both receive their positional values correctly; no misroute.

Could you re-test on 1.0.0 and reopen if you still see the issue? If you do, please share the constructor signature so we can extend the test fixtures.

[xertrec]

@arnaudgiuliani This is the signature of the ViewModel where I replicated it:

@KoinViewModel
class MainViewModel(
    @InjectedParam val param1: String,
    @InjectedParam val nullParam1: String?,
    @InjectedParam val nullParam2: String?,
): ViewModel()

I made a repository with the repro if you need it

[arnaudgiuliani]

Try Koin Compiler 1.0 👍

[xertrec]

Try Koin Compiler 1.0 👍

In the repo I reproduced it, it's using Koin 1.0