# Koin Documentation (full text)

> Every page of the Koin documentation, in sidebar order. Index: https://insert-koin.io/llms.txt

# Welcome

Source: https://insert-koin.io/docs/intro

Koin is a dependency injection framework for Kotlin. You declare how your classes are built in modules, Koin creates and wires the instances at runtime, and the optional Koin Compiler Plugin checks the whole graph when you build. It runs on Android, Compose, Kotlin Multiplatform, Ktor and any Kotlin/JVM application.

This page is a map of the documentation. Each section below says which question it answers and where to start.

```kotlin
class UserRepository(private val api: ApiService)

val appModule = module {
    single<ApiService>()
    single<UserRepository>()
}

fun main() {
    startKoin { modules(appModule) }
}
```

## I want to...

- Understand dependency injection first: [What is Dependency Injection?](/docs/intro/what-is-dependency-injection)
- Understand how Koin works in five minutes: [Core Concepts](/docs/intro/core-concepts)
- Pick between DSL and annotations: [Choosing your style](/docs/intro/choosing-your-style)
- Add Koin to my Gradle build: [Gradle Setup](/docs/setup/gradle)
- Inject a ViewModel in a Composable: [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel)
- Inject in an Activity, Fragment or Service: [Android Entry Points](/docs/reference/koin-android/entry-points)
- Wire Retrofit, Room or OkHttp: [Android Library Integration](/docs/reference/koin-android/binding-patterns)
- Share modules between Android and iOS: [KMP Sharing Patterns](/docs/reference/koin-core/kmp-shared-modules)
- Pass a runtime value such as an ID to a definition: [Injected Parameters](/docs/reference/koin-core/injection-parameters)
- Test my Koin configuration: [Verifying your Koin configuration](/docs/reference/koin-test/verify) and [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety)
- Fix a "No definition found" error: [Troubleshooting](/docs/reference/koin-core/troubleshooting)
- Migrate from Hilt: [Migrating from Hilt](/docs/reference/koin-android/hilt-migration)
- Move my annotations from KSP to the Compiler Plugin: [Migrating from KSP](/docs/migration/from-ksp-to-compiler-plugin)
- See how Koin behaves in production: [Production Monitoring](/docs/tooling/production-monitoring)

## Where to go

### Get Started

What is Koin, how does it work, which style should I use?

- [What is Koin?](/docs/intro/what-is-koin): what Koin is and how it works, runtime and compile time.
- [Core Concepts](/docs/intro/core-concepts): definitions, modules, the container, injection, scopes.
- [Choosing your style](/docs/intro/choosing-your-style): annotations or the DSL (Compiler Plugin, Constructor or Classic DSL).
- [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin): what the plugin does at build time.

### Setup

What do I add to my build?

- [Setup](/docs/setup): what to install for each platform.
- [Gradle Setup](/docs/setup/gradle): the BOM and every Koin artifact.
- [Compiler Plugin Setup](/docs/setup/compiler-plugin): install and configure the Gradle plugin.

### Tutorials

How do I build a first app with Koin, step by step?

- [Kotlin](/docs/quickstart/kotlin): a plain Kotlin application.
- [Android - ViewModel](/docs/quickstart/android-viewmodel) and [Android - Jetpack Compose](/docs/quickstart/android-compose).
- [Compose Multiplatform](/docs/quickstart/cmp): shared UI on Android and iOS.
- [Ktor](/docs/quickstart/ktor): a server application.

### Core

How do I declare, organize and retrieve dependencies on any platform?

- [Starting Koin](/docs/reference/koin-core/starting-koin): `startKoin`, logging, properties.
- [Modules](/docs/reference/koin-core/modules) and [Definitions](/docs/reference/koin-core/definitions): declare what Koin builds.
- [Scopes](/docs/reference/koin-core/scopes): instances tied to a lifecycle.
- [Troubleshooting](/docs/reference/koin-core/troubleshooting): errors and how to read them.

### Platforms

How do I use Koin with a specific platform or framework?

- Android: [Start Koin on Android](/docs/reference/koin-android/start), [Android ViewModel](/docs/reference/koin-android/viewmodel), [Multi-Module Android Apps](/docs/reference/koin-android/multi-module).
- Compose: [Koin for Compose](/docs/reference/koin-compose/compose), [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel), [Navigation 3](/docs/reference/koin-compose/navigation3).
- Kotlin Multiplatform: [KMP Setup](/docs/reference/koin-core/kmp-setup), [Sharing Patterns](/docs/reference/koin-core/kmp-shared-modules).
- Ktor: [Koin for Ktor](/docs/reference/koin-ktor/ktor), [Request Scopes](/docs/reference/koin-ktor/ktor-scopes).

### Testing

How do I test code that uses Koin, and test the configuration itself?

- [Injecting in Tests](/docs/reference/koin-test/testing): `KoinTest`, replacing definitions with fakes.
- [Verifying your Koin configuration](/docs/reference/koin-test/verify): check modules in a unit test.
- [Android Instrumented Testing](/docs/reference/koin-android/instrumented-testing) and [Testing Composables](/docs/reference/koin-compose/compose-testing).

### Production & Tooling

Which tools help me write, inspect and run Koin apps?

- [Tooling](/docs/tooling): overview of the tools around Koin.
- [IDE Plugin](/docs/tooling/ide-plugin): navigation and checks in Android Studio and IntelliJ IDEA.
- [Monitor](/docs/tooling/monitor) and [Production Monitoring](/docs/tooling/production-monitoring): see what Koin does at runtime.

### Migration

I use another framework or an older Koin setup. How do I move?

- [Koin vs Hilt](/docs/intro/koin-vs-hilt): how the two compare.
- [Migrating from Hilt](/docs/reference/koin-android/hilt-migration): step-by-step guide.
- [JSR-330 Compatibility](/docs/reference/koin-android/jsr330): keep `@Inject` and `@Singleton` from `javax.inject`.
- [Migrating from KSP](/docs/migration/from-ksp-to-compiler-plugin): move annotations to the Compiler Plugin.

### Reference

What are all the keywords, annotations and options?

- [DSL Reference](/docs/reference/koin-core/dsl): every DSL keyword.
- [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): every annotation and its parameters.
- [Compiler Plugin Options](/docs/reference/koin-annotations/options): every Gradle option of the plugin.

### Support

Which version should I use, what changed, where do I get help?

- [Releases](/docs/support/releases): versions, changes and upgrade notes.
- [API Stability](/docs/support/api-stability): what stable, experimental and internal mean.
- [Support](/docs/support): roadmap, community and support options.

## Related

- [What is Koin?](/docs/intro/what-is-koin): the next page to read if you are new to Koin.
- [Core Concepts](/docs/intro/core-concepts): the mental model behind every other page.
- [Setup](/docs/setup): install Koin for your platform.

---

# What is Dependency Injection?

Source: https://insert-koin.io/docs/intro/what-is-dependency-injection

Dependency injection (DI) is a design pattern where an object receives the objects it needs from outside instead of creating them itself. This page explains the pattern without assuming any framework, then shows where a DI container such as Koin fits. If you already know DI, go to [Core Concepts](/docs/intro/core-concepts).

## What is a dependency?

A dependency is an object that another object needs to do its work. A `Car` needs an `Engine` to drive.

### Without dependency injection

```kotlin
class Engine {
    fun start() {
        println("Engine starting...")
    }
}

class Car {
    private val engine = Engine() // Car creates its own engine

    fun drive() {
        engine.start()
        println("Car is driving")
    }
}
```

This works, but it has costs:

- **Tight coupling**: `Car` is tied to one `Engine` implementation.
- **Hard to test**: you can't test `Car` with a fake engine.
- **Hard to change**: switching to an electric engine means editing `Car`.
- **Lifecycle in the wrong place**: `Car` decides when an `Engine` is created and how many exist.

### With dependency injection

```kotlin
class Car(private val engine: Engine) {
    fun drive() {
        engine.start()
        println("Car is driving")
    }
}

val gasolineCar = Car(GasEngine())
val electricCar = Car(ElectricEngine())
```

`Car` no longer knows how an `Engine` is built. You can pass any implementation, including a fake in tests, and the constructor shows exactly what `Car` needs.

## Ways to provide dependencies

### Constructor injection

Dependencies are constructor parameters:

```kotlin
class UserRepository(
    private val database: Database,
    private val apiClient: ApiClient,
) {
    fun getUser(id: String): User =
        database.query(id) ?: apiClient.fetchUser(id)
}
```

Dependencies are explicit, required, and can be immutable (`val`). The class can be created and tested without any framework. This is the approach to use by default.

### Field injection

Dependencies are assigned to properties after the object is created. This is needed when a framework creates the object and you don't control its constructor, as with an Android `Activity`:

```kotlin
class UserActivity : AppCompatActivity() {
    private val viewModel: UserViewModel by viewModel() // filled by Koin on first access
}
```

Use it only at these framework entry points. Below them, use constructor injection.

### Method injection

A dependency is passed to the method that needs it:

```kotlin
class ReportGenerator {
    fun generateReport(data: DataSource) {
        ...
    }
}
```

This fits a dependency that changes on every call, or one that only one method uses.

## Manual and automated dependency injection

### Wiring by hand

You can apply DI without any library, by building the object graph yourself:

```kotlin
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val database = Database()
        val apiClient = ApiClient()
        val userRepository = UserRepository(database, apiClient)
        val authRepository = AuthRepository(database, apiClient)
        val userService = UserService(userRepository, authRepository)
        val viewModel = UserViewModel(userService)
    }
}
```

As the app grows, this code is repeated in many places, must be updated whenever a constructor changes, and gives no control over how long each object lives.

### A container written by hand

A common next step is a container object that centralizes creation:

```kotlin
object AppContainer {
    private val database by lazy { Database() }
    private val apiClient by lazy { ApiClient() }

    val userRepository by lazy { UserRepository(database, apiClient) }
    val authRepository by lazy { AuthRepository(database, apiClient) }

    fun createUserViewModel() = UserViewModel(
        UserService(userRepository, authRepository)
    )
}

class MainActivity : AppCompatActivity() {
    private val viewModel = AppContainer.createUserViewModel()
}
```

This removes the repetition, but you still write and maintain every constructor call, and lifecycles beyond "one instance" or "a new instance" (an instance per screen, per session) need more hand-written code.

### A DI container

A DI library automates the container. You declare which classes exist and how long they live, and the library builds the graph. With Koin:

**Compiler Plugin DSL**
```kotlin
val appModule = module {
    single<Database>()
    single<ApiClient>()
    single<UserRepository>()
    single<AuthRepository>()
    single<UserService>()
    viewModel<UserViewModel>()
}
```

**Annotations**
```kotlin
@Singleton
class UserRepository(private val database: Database, private val apiClient: ApiClient)

@Singleton
class UserService(private val userRepository: UserRepository, private val authRepository: AuthRepository)

@KoinViewModel
class UserViewModel(private val userService: UserService) : ViewModel()

// Database, ApiClient and AuthRepository are annotated the same way

@Module
@ComponentScan("com.example.app")
class AppModule
```

**Constructor / Classic DSL**
```kotlin
val appModule = module {
    singleOf(::Database)
    singleOf(::ApiClient)
    singleOf(::UserRepository)
    singleOf(::AuthRepository)
    singleOf(::UserService)
    viewModelOf(::UserViewModel)
}
```

The Activity then asks for the top of the graph:

```kotlin
class MainActivity : AppCompatActivity() {
    private val viewModel: UserViewModel by viewModel()
}
```

The container creates `UserViewModel` and everything below it, keeps one `Database` for the whole app, and gives a new `UserViewModel` to each screen. [Core Concepts](/docs/intro/core-concepts) explains these pieces.

## How DI libraries build the graph

DI libraries differ in when and how they build the graph:

| Approach | How it works | Examples |
|----------|--------------|----------|
| Reflection | Reads constructors at runtime and calls them by reflection | Guice, Spring |
| Annotation processing | Generates factory source code at build time | Dagger, Hilt |
| Compiler plugin | Rewrites code inside the compiler and checks the graph at build time | Koin Compiler Plugin |
| Runtime DSL | You write the factories as Kotlin lambdas, the container runs them at runtime | Koin Classic DSL |

Koin keeps a runtime container in all cases. The Compiler Plugin adds the wiring and the build-time checks on top. See [What is Koin?](/docs/intro/what-is-koin) for what this means in practice.

## Service locator and dependency injection

The two patterns are often confused.

With a **service locator**, a class asks a registry for its dependencies:

```kotlin
class UserService : KoinComponent {
    private val repository: UserRepository by inject() // pulled from the container
}
```

With **dependency injection**, the dependencies are given to the class:

```kotlin
class UserService(
    private val repository: UserRepository // pushed in from outside
)
```

| Aspect | Service locator | Dependency injection |
|--------|-----------------|----------------------|
| Visibility of dependencies | Hidden inside the class | Visible in the constructor |
| Testing | Needs the container, or a test version of it | Pass fakes to the constructor |
| Coupling | The class depends on the container | The class depends only on its parameters |
| In Koin | `get()`, `by inject()`, `KoinComponent` | Constructor parameters resolved by a module |
| Good fit | Framework classes you don't construct | Business logic, repositories, services |

Koin supports both. Use dependency injection for your own classes, and the service locator style only where a framework creates the object (an `Activity`, a `Fragment`, a Ktor route):

```kotlin
// avoid: hidden dependency, needs Koin in tests
class UserService : KoinComponent {
    private val repository: UserRepository = get()
}

// prefer: explicit dependency
class UserService(private val repository: UserRepository)
```

## What you gain

### Testability

```kotlin
class UserService(private val repository: UserRepository)

@Test
fun getUser() {
    val repository = mockk<UserRepository>()
    every { repository.findUser("123") } returns testUser

    val service = UserService(repository)

    assertEquals(testUser, service.getUser("123"))
}
```

A class that receives its dependencies can be tested by calling its constructor. No container is needed.

### Swappable implementations

```kotlin
val appModule = module {
    single<EmailService> { SmtpEmailService() }
}

val testModule = module {
    single<EmailService> { FakeEmailService() }
}
```

Consumers depend on `EmailService`. Which implementation they get is decided in one place, the module.

### Central configuration

```kotlin
startKoin {
    modules(dataModule, domainModule, presentationModule)
}
```

The whole object graph is described by a few modules, usually one per layer or feature, instead of being spread across the code.

### Lifecycle management

```kotlin
val appModule = module {
    single<Database>()     // one instance for the app
    factory<Presenter>()   // a new instance on every request

    scope<UserSession> {
        scoped<CartRepository>() // one instance per session
    }
}
```

The container decides how long each object lives, so classes don't manage the lifetime of their dependencies. See [Scopes](/docs/reference/koin-core/scopes).

## Related

- [What is Koin?](/docs/intro/what-is-koin): how Koin implements a DI container.
- [Core Concepts](/docs/intro/core-concepts): definitions, modules, injection and scopes in Koin.
- [Retrieving Dependencies](/docs/reference/koin-core/injection): `get()` and `inject()` in detail.
- [Injecting in Tests](/docs/reference/koin-test/testing): test code that uses Koin.

---

# What is Koin?

Source: https://insert-koin.io/docs/intro/what-is-koin

Koin is a dependency injection framework for Kotlin. This page explains how it works, what it costs and what it gives you, and how the project is organized. If dependency injection is new to you, read [What is Dependency Injection?](/docs/intro/what-is-dependency-injection) first.

## How Koin works

You describe your classes in modules, start Koin once, and ask for instances where you need them:

```kotlin
class ApiService
class UserRepository(private val api: ApiService)

val appModule = module {
    single<ApiService>()
    single<UserRepository>()
}

fun main() {
    startKoin {
        modules(appModule)
    }
}
```

Two parts work together:

- **Runtime container**: `startKoin` loads your modules into a container. Each definition is a Kotlin function that builds one type. When something asks for a `UserRepository`, Koin runs that function, resolves its constructor parameters from the container, and keeps or discards the instance depending on the definition type (`single`, `factory`, `scoped`). Koin does not build objects by reflection.
- **Compile-time checks (optional)**: the [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin) is a Kotlin compiler plugin. It reads your constructors to generate the wiring, then checks at build time that every dependency of the assembled graph is declared. A missing definition becomes a build error instead of a crash.

[Core Concepts](/docs/intro/core-concepts) explains modules, definitions, scopes and injection with one running example.

## What the runtime model costs and gives

Because the graph lives in a runtime container, Koin can change it while the app runs:

- **Dynamic modules**: load and unload modules after start with `loadKoinModules()` and `unloadKoinModules()`, for feature flags or on-demand features. See [Starting Koin](/docs/reference/koin-core/starting-koin).
- **Lazy modules**: load part of the graph in the background to reduce startup work. See [Lazy Modules](/docs/reference/koin-core/lazy-modules).
- **Scopes created at runtime**: open and close scopes for a session, a screen or a request. See [Scopes](/docs/reference/koin-core/scopes).
- **No generated sources**: nothing to commit, nothing to configure per Kotlin Multiplatform target.

The same model has costs you should know:

- **Startup work**: modules are registered when Koin starts, and every lookup goes through the container. For most apps this is small, but eager definitions (`createdAtStart`) run on the thread that starts Koin.
- **Runtime errors without the plugin**: with the Constructor or Classic DSL and no plugin, a missing definition is only found when the code runs. You can catch it in a unit test with [`verify()`](/docs/reference/koin-test/verify), or at build time with the Compiler Plugin.
- **Limits of compile-time checks**: the plugin validates the graph assembled at a Koin entry point such as `startKoin`. Modules loaded later with `loadKoinModules()` can't be proven at build time, and a library module with no entry point is only checked when an app assembles it. See [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety).
- **Kotlin version coupling**: the Compiler Plugin depends on compiler internals, so each plugin release is verified on a list of Kotlin versions. See [Compiler Plugin Setup](/docs/setup/compiler-plugin).

## Constructor injection and service locator

Your classes receive their dependencies through the constructor. Koin only retrieves an instance where it cannot create the object itself, at an entry point:

```kotlin
// Koin creates these: dependencies come through the constructor
class UserRepository(private val api: UserApi)
class UserViewModel(private val repository: UserRepository) : ViewModel()

// Android creates the Activity: it retrieves its ViewModel from Koin
class UserActivity : AppCompatActivity() {
    private val viewModel: UserViewModel by viewModel()
}
```

The dependency is visible in the signature, and you can test `UserRepository` and `UserViewModel` without Koin. Retrieval functions such as `by inject()`, `by viewModel()` or `koinInject()` belong to entry points: an `Activity`, a `Fragment`, a root Composable, `main()`, a Ktor route, a test. [What is Dependency Injection?](/docs/intro/what-is-dependency-injection) compares the two patterns, and [Retrieving Dependencies](/docs/reference/koin-core/injection) covers `get()` and `inject()`.

## Two styles, one container

| Style | Example | Needs |
|-------|---------|-------|
| Compiler Plugin DSL | `single<UserRepository>()` | Koin Compiler Plugin |
| Annotations | `@Singleton class UserRepository(...)` | Koin Compiler Plugin, `koin-annotations` |
| Constructor DSL | `singleOf(::UserRepository)` | Nothing extra (the plugin adds compile-time checks) |
| Classic DSL | `single { UserRepository(get()) }` | Nothing extra (the plugin adds compile-time checks) |

Annotations are one style; the Compiler Plugin, Constructor and Classic DSL are the three forms of the other, the Koin DSL. All produce the same definitions in the same container. Pick one style per project. [Choosing your style](/docs/intro/choosing-your-style) compares them and gives a default.

## Annotations status

The `koin-annotations` library (`@Singleton`, `@Factory`, `@KoinViewModel`, `@Module`, `@ComponentScan`) is part of the main Koin project: same repository, same version, same BOM. It is not deprecated. What is deprecated is `koin-ksp-compiler`, the KSP processor that used to read these annotations. The Koin Compiler Plugin replaces it, with the same annotations. See [Migrating from KSP to the Compiler Plugin](/docs/migration/from-ksp-to-compiler-plugin).

## Platforms

Koin is a Kotlin Multiplatform library. The core runs on every Kotlin target, and integration libraries add platform APIs:

| Platform | Main artifact | Start here |
|----------|---------------|------------|
| Kotlin/JVM | `koin-core` | [Kotlin tutorial](/docs/quickstart/kotlin) |
| Android | `koin-android` | [Start Koin on Android](/docs/reference/koin-android/start) |
| Jetpack Compose, Compose Multiplatform | `koin-compose`, `koin-compose-viewmodel` | [Koin for Compose](/docs/reference/koin-compose/compose) |
| Kotlin Multiplatform (iOS, desktop, web, native) | `koin-core` | [Kotlin Multiplatform Setup](/docs/reference/koin-core/kmp-setup) |
| Ktor server | `koin-ktor` | [Koin for Ktor](/docs/reference/koin-ktor/ktor) |

The full artifact list is in [Gradle Setup](/docs/setup/gradle).

## The Koin project

Koin is open source under the Apache 2.0 license. It is made of:

- **Koin libraries**: core, Android, Compose, Ktor, test and annotations, all released under one version. Source: [InsertKoinIO/koin](https://github.com/InsertKoinIO/koin).
- **Koin Compiler Plugin**: the Kotlin compiler plugin and its Gradle plugin, with its own version. Source: [InsertKoinIO/koin-compiler-plugin](https://github.com/InsertKoinIO/koin-compiler-plugin).
- **Koin IDE Plugin**: navigation and checks in Android Studio and IntelliJ IDEA. See [IDE Plugin](/docs/tooling/ide-plugin).
- **Samples**: runnable apps for each tutorial in [InsertKoinIO/koin-getting-started](https://github.com/InsertKoinIO/koin-getting-started).

If you know Hilt or Dagger, [Koin vs Hilt](/docs/intro/koin-vs-hilt) compares the two approaches.

## Related

- [Core Concepts](/docs/intro/core-concepts): the mental model, with one example built step by step.
- [Choosing your style](/docs/intro/choosing-your-style): which declaration style to use.
- [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin): what happens at build time.
- [Setup](/docs/setup): add Koin to your project.
- [Tutorials](/docs/quickstart/kotlin): build a first app.

---

# Core Concepts

Source: https://insert-koin.io/docs/intro/core-concepts

This page builds one small example step by step to explain the ideas behind every other page: definitions, modules, the Koin container, injection, scopes, qualifiers and compile-time checks. Each section is short and links to the page that holds the detail. It assumes you know what dependency injection is (see [What is Dependency Injection?](/docs/intro/what-is-dependency-injection)).

Code samples come in three tabs: Compiler Plugin DSL, Annotations, Constructor / Classic DSL. Pick yours, the choice applies to every page. If you are not sure which style to use, read [Choosing your style](/docs/intro/choosing-your-style).

## The example

Three plain Kotlin classes. Each one receives what it needs in its constructor and knows nothing about Koin:

```kotlin
class ApiService

class UserRepository(private val api: ApiService)

class UserViewModel(private val repository: UserRepository) : ViewModel()
```

Koin's job is to create `ApiService`, pass it to `UserRepository`, and pass that to `UserViewModel`, without you writing the wiring by hand.

## Definition

A **definition** tells Koin how to create one type and how long to keep the instance:

**Compiler Plugin DSL**
```kotlin
single<ApiService>()
single<UserRepository>()
viewModel<UserViewModel>()
```

**Annotations**
```kotlin
@Singleton
class ApiService

@Singleton
class UserRepository(private val api: ApiService)

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

**Constructor / Classic DSL**
```kotlin
singleOf(::ApiService)
singleOf(::UserRepository)
viewModelOf(::UserViewModel)
```

The keyword sets the lifetime. `single` keeps one instance for the whole container. `factory` creates a new instance on every request. `viewModel` follows the ViewModel lifecycle. Koin reads the constructor of `UserRepository`, sees it needs an `ApiService`, and resolves it from the container.

Detail: [Definitions](/docs/reference/koin-core/definitions).

## Module

A **module** groups definitions. You usually have one module per feature or layer:

**Compiler Plugin DSL**
```kotlin
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*

val appModule = module {
    single<ApiService>()
    single<UserRepository>()
    viewModel<UserViewModel>()
}
```

**Annotations**
```kotlin
@Module
@ComponentScan("com.example.app")
class AppModule
```

`@ComponentScan` collects every annotated class in the package `com.example.app` and its subpackages.

**Constructor / Classic DSL**
```kotlin
import org.koin.dsl.module
import org.koin.core.module.dsl.*

val appModule = module {
    singleOf(::ApiService)
    singleOf(::UserRepository)
    viewModelOf(::UserViewModel)
}
```

A module is only a description. Nothing is created until Koin starts and someone asks for an instance. Modules can include other modules, so a large app is a tree of small modules.

Detail: [Modules](/docs/reference/koin-core/modules).

## The Koin container

`startKoin` creates the **container** (a `KoinApplication`) and loads your modules into it. You call it once, at the entry point of your app:

**Compiler Plugin DSL**
```kotlin
fun main() {
    startKoin {
        modules(appModule)
    }
}
```

**Annotations**
```kotlin
import org.koin.plugin.module.dsl.startKoin

@KoinApplication(modules = [AppModule::class])
class MyApp

fun main() {
    startKoin<MyApp>()
}
```

**Constructor / Classic DSL**
```kotlin
fun main() {
    startKoin {
        modules(appModule)
    }
}
```

On Android you call it in `Application.onCreate()` and pass the Android context with `androidContext(this)`. The container holds the definitions and the instances created so far. `stopKoin()` closes it and releases every `single`.

Detail: [Starting Koin](/docs/reference/koin-core/starting-koin), and [Start Koin on Android](/docs/reference/koin-android/start).

## Injection

There are two ways an object gets its dependencies.

**Constructor injection**: the dependency is a constructor parameter, and Koin passes it when it creates the object. `UserRepository` and `UserViewModel` in this example already use it. This is the default: the class stays plain Kotlin and you can test it by calling the constructor with fakes.

**Retrieving from the container**: some classes are created by a framework, not by Koin (an Android `Activity`, a Composable, a Ktor route). They ask the container with `get()` (now) or `inject()` (lazily, on first access):

```kotlin
import org.koin.androidx.viewmodel.ext.android.viewModel

class UserActivity : AppCompatActivity() {
    private val viewModel: UserViewModel by viewModel()
}
```

```kotlin
import org.koin.compose.viewmodel.koinViewModel

@Composable
fun UserScreen(viewModel: UserViewModel = koinViewModel()) {
    ...
}
```

Retrieving is the same in every style. Keep it at these entry points: everything below them uses constructor injection.

Detail: [Retrieving Dependencies](/docs/reference/koin-core/injection), [Android Entry Points](/docs/reference/koin-android/entry-points), [Koin for Compose](/docs/reference/koin-compose/compose).

## The graph

Put together, the container holds this graph:

```text
startKoin
  └── appModule
        ├── single     ApiService
        ├── single     UserRepository  ── needs ── ApiService
        └── viewModel  UserViewModel   ── needs ── UserRepository

UserActivity ── by viewModel() ──> UserViewModel
```

When `UserActivity` asks for `UserViewModel`, Koin creates `ApiService` (once), then `UserRepository` (once), then a `UserViewModel` bound to the Activity's ViewModel lifecycle.

## Scope

A `single` lives as long as the container, a `factory` lives as long as the caller keeps it. A **scope** covers the space between: instances that live as long as something else, such as a user session, a screen or a request.

Say a `CartRepository` should exist only while a user is logged in:

**Compiler Plugin DSL**
```kotlin
class UserSession
class CartRepository(private val api: ApiService)

val sessionModule = module {
    scope<UserSession> {
        scoped<CartRepository>()
    }
}
```

**Annotations**
```kotlin
class UserSession

@Scope(UserSession::class)
@Scoped
class CartRepository(private val api: ApiService)
```

**Constructor / Classic DSL**
```kotlin
class UserSession
class CartRepository(private val api: ApiService)

val sessionModule = module {
    scope<UserSession> {
        scopedOf(::CartRepository)
    }
}
```

You open the scope when the session starts and close it when the session ends:

```kotlin
// inside a KoinComponent
val sessionScope = getKoin().createScope<UserSession>("session-42")
val cart: CartRepository = sessionScope.get()

sessionScope.close() // releases CartRepository
```

A scoped definition can use definitions from the root container (`ApiService` here). On Android, Koin provides ready-made scopes for Activities, Fragments and ViewModels, so you rarely create scopes by hand.

Detail: [Scopes](/docs/reference/koin-core/scopes), and [Android Scopes](/docs/reference/koin-android/scope).

## Qualifier

Koin finds a definition by its type. When two definitions provide the same type, a **qualifier** gives each one a name:

**Compiler Plugin DSL**
```kotlin
interface NetworkClient

@Named("auth")
class AuthClient : NetworkClient

@Named("public")
class PublicClient : NetworkClient

class UserRepository(@Named("auth") private val client: NetworkClient)

val networkModule = module {
    single<AuthClient>() bind NetworkClient::class
    single<PublicClient>() bind NetworkClient::class
    single<UserRepository>()
}
```

**Annotations**
```kotlin
@Singleton
@Named("auth")
class AuthClient : NetworkClient

@Singleton
@Named("public")
class PublicClient : NetworkClient

@Singleton
class UserRepository(@Named("auth") private val client: NetworkClient)
```

**Constructor / Classic DSL**
```kotlin
val networkModule = module {
    single<NetworkClient>(named("auth")) { AuthClient() }
    single<NetworkClient>(named("public")) { PublicClient() }
    single { UserRepository(get(named("auth"))) }
}
```

Detail: [Qualifiers](/docs/reference/koin-core/qualifiers).

## Compile-time checks

Without the Compiler Plugin, a missing definition shows up when the code runs: `get()` throws `NoDefinitionFoundException`. With the [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin), the same mistake fails the build. If you remove `single<ApiService>()` from `appModule`, compilation stops with:

```text
[Koin][KOIN-D001] Missing dependency: ApiService
  required by: UserRepository (parameter 'api')
  in module: ...
```

The plugin checks the full graph at each entry point (`startKoin`, `@KoinApplication`, Ktor's `install(Koin)`) and every `get()`, `inject()` or `koinViewModel()` call. With the Constructor or Classic DSL and no plugin, you get a similar check in a unit test with `verify()`.

Detail: [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety), [Verifying your Koin configuration](/docs/reference/koin-test/verify).

## Related

- [Choosing your style](/docs/intro/choosing-your-style): which declaration style to use.
- [Setup](/docs/setup): add Koin and the Compiler Plugin to your build.
- [Tutorials](/docs/quickstart/kotlin): build a complete app with these concepts.
- [Definitions](/docs/reference/koin-core/definitions): every definition type in detail.
- [Scopes](/docs/reference/koin-core/scopes): lifecycles beyond single and factory.

---

# Choosing your style

Source: https://insert-koin.io/docs/intro/choosing-your-style

Koin offers two styles to declare definitions, both filling the same container: **annotations** on your classes, or the **Koin DSL** in `module { }` blocks. The DSL comes in three forms: the Compiler Plugin DSL (`single<T>()`), the Constructor DSL (`singleOf(::T)`) and the Classic DSL (`single { T(get()) }`). The choice changes how you write modules, not how Koin works at runtime. This page shows each style, its requirements and tradeoffs, and recommends a default. It assumes you know what a definition and a module are (see [Core Concepts](/docs/intro/core-concepts)).

## The styles side by side

The same module in each style:

**Compiler Plugin DSL**
```kotlin
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*

val appModule = module {
    single<ApiService>()
    single<UserRepositoryImpl>() bind UserRepository::class
    viewModel<UserViewModel>()
}
```

You name the type. The [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin) reads its constructor and generates the wiring.

**Annotations**
```kotlin
@Singleton
class ApiService

@Singleton
class UserRepositoryImpl(private val api: ApiService) : UserRepository

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

@Module
@ComponentScan("com.example.app")
class AppModule
```

You annotate each class. `@ComponentScan` gathers them into a module, and the Compiler Plugin generates the wiring. Interfaces are bound automatically.

**Constructor / Classic DSL**
Constructor DSL, with constructor references:

```kotlin
import org.koin.dsl.module
import org.koin.core.module.dsl.*

val appModule = module {
    singleOf(::ApiService)
    singleOf(::UserRepositoryImpl) bind UserRepository::class
    viewModelOf(::UserViewModel)
}
```

Classic DSL, with the constructor call written by hand:

```kotlin
val appModule = module {
    single { ApiService() }
    single<UserRepository> { UserRepositoryImpl(get()) }
    viewModel { UserViewModel(get()) }
}
```

Both forms work without the compiler plugin. When the plugin is applied, they are checked at build time too.

## Requirements

| | Compiler Plugin DSL | Annotations | Constructor / Classic DSL |
|---|---|---|---|
| Koin version | 4.2.0+ | 4.2.0+ | Any |
| Kotlin version | 2.3.20+ (K2) | 2.3.20+ (K2) | Any version supported by your Koin version |
| Gradle plugin | `io.insert-koin.compiler.plugin` (required) | `io.insert-koin.compiler.plugin` (required) | Optional: adds compile-time checks |
| Extra dependency | `koin-annotations` only for parameter annotations (`@Named`, `@InjectedParam`) | `koin-annotations` | None |
| Imports | `org.koin.plugin.module.dsl.*` | `org.koin.core.annotation.*` | `org.koin.core.module.dsl.*` (Constructor), `org.koin.dsl.*` (Classic) |

Each Compiler Plugin release is verified on a list of Kotlin versions. Plugin 1.2.1 is verified on Kotlin 2.3.20, 2.4.0, 2.4.10 and 2.4.20. Installation steps are in [Compiler Plugin Setup](/docs/setup/compiler-plugin).

:::warning
The Compiler Plugin DSL functions (`single<T>()`, `factory<T>()`, `create(::T)`) are stubs. Without the Gradle plugin applied, the code compiles but throws `NotImplementedError` at runtime. Apply the plugin in every Gradle module that uses them.
:::

## Tradeoffs

### Compiler Plugin DSL

- **Compile-time checks**: the full graph and every `get()` call site are validated at build time.
- **No wiring code**: no `get()`, no constructor references. Adding a constructor parameter needs no module change.
- **Explicit modules**: you see every definition of a module in one place, and you can use Kotlin code (conditions, loops) around them.
- **Parameter annotations**: qualifiers and injected parameters are declared on the class (`@Named`, `@InjectedParam`), so the class depends on `koin-annotations`.
- **Kotlin coupling**: you need a recent K2 compiler, and a new Kotlin release may need a new plugin release.

### Annotations

- **Compile-time checks**: same as the Compiler Plugin DSL.
- **Definition next to the class**: the lifetime and bindings are visible where the class is written. Teams coming from Hilt, Dagger or Spring find the model familiar.
- **Automatic binding**: a class is bound to all its supertypes unless you list `binds`.
- **Scanning configuration**: definitions are found by package. You need `@Module` and `@ComponentScan` with the right packages, and `@Configuration` or `@KoinApplication` to assemble modules across Gradle modules. A class outside the scanned packages is not part of the module. The compile-time check reports it only if another definition needs it.
- **Gaps**: some options exist only in the DSL, such as the `onClose` callback. You write those definitions in a DSL module.
- **Kotlin coupling**: same as the Compiler Plugin DSL.

### Constructor DSL and Classic DSL

- **Works everywhere**: the compiler plugin is optional, no Kotlin version constraint beyond Koin's own.
- **Compile-time checks with the plugin**: since Compiler Plugin 1.2.0, applying the plugin checks `singleOf(::T)`, `factoryOf(::T)`, `scopedOf(::T)` and `viewModelOf(::T)` like `single<T>()`, and hand-written lambdas through their `get()` calls. Existing modules get compile-time checks without a rewrite.
- **Full control (Classic DSL)**: the lambda is plain Kotlin, so you can call builders, read configuration or choose an implementation at runtime.
- **Runtime errors without the plugin**: a missing definition is found when the code runs. Use [`verify()`](/docs/reference/koin-test/verify) in a unit test to catch it earlier.
- **Wiring to maintain**: `single { UserRepository(get(), get()) }` must follow constructor changes by hand. `singleOf(::UserRepository)` follows them, but needs explicit calls for nullable, lazy or qualified parameters.

## Which one to pick

Pick one style for the project and state it: annotations or the DSL.

For a new project on Kotlin 2.3.20 or later, use the **Compiler Plugin DSL**. It gives compile-time checks, keeps DI out of your classes and keeps modules as explicit Kotlin code. If your team prefers to declare definitions on the class, as with Hilt or Dagger, use **annotations**: they get the same checks and are JSR-330 compatible (`@Inject`, `@Singleton`, `@Named`).

Keep the **Constructor or Classic DSL** if you can't use a recent Kotlin version, if you build a library that must not require a compiler plugin from its users, or if your existing modules work and you don't want to change them. Apply the Compiler Plugin to get compile-time checks on them without a rewrite. Use a Classic DSL lambda wherever a definition needs custom logic.

## Mixing styles

All styles produce the same definitions, so one project can use several. Prefer one style per project. If you mix annotations and the DSL, keep one style per module. Common cases:

- **Compiler Plugin DSL and Classic DSL in one module**: write `single<T>()` for most definitions, and a lambda where you need custom logic. Both are DSL forms, so this is not mixing styles.
- **Annotations with a few DSL modules**: start from your `@KoinApplication` class and add DSL modules in the configuration block.
- **DSL start with annotated modules**: load a `@Module` class into a regular `startKoin`.

```kotlin
import org.koin.plugin.module.dsl.module
import org.koin.plugin.module.dsl.startKoin

// annotated application, plus DSL modules
startKoin<MyApp> {
    modules(legacyModule)
}

// DSL application, plus an annotated module
startKoin {
    modules(appModule)
    module<NetworkModule>()
}
```

`@Module(includes = [...])` and `@KoinApplication(modules = [...])` only accept `@Module` classes, not DSL `module { }` values. See [Modules](/docs/reference/koin-core/modules) and [Starting Koin](/docs/reference/koin-core/starting-koin) for the full rules.

## The KSP processor is deprecated

Before the Compiler Plugin, annotations were processed by `koin-ksp-compiler`, a KSP processor. That processor is deprecated and will be removed in a future Koin version. The annotations themselves are not deprecated: `koin-annotations` is part of the main Koin project and ships with each Koin version. If you use KSP today, your annotated classes stay the same and only the build setup and the start code change. See [Migrating from KSP to the Compiler Plugin](/docs/migration/from-ksp-to-compiler-plugin).

## Tabs on every page

Code samples in these docs use the same three tabs: Compiler Plugin DSL, Annotations, Constructor / Classic DSL. When you select a tab, the choice is saved in your browser and applied on every page. Samples that are the same in all styles, such as `by inject()` in an Activity, are shown once without tabs.

## Related

- [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin): how the plugin works and what it validates.
- [Compiler Plugin Setup](/docs/setup/compiler-plugin): install the Gradle plugin.
- [Definitions](/docs/reference/koin-core/definitions): every definition type, in every style.
- [DSL Reference](/docs/reference/koin-core/dsl) and [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): every keyword and annotation.
- [Migrating from KSP](/docs/migration/from-ksp-to-compiler-plugin): move from `koin-ksp-compiler`.

---

# Koin Compiler Plugin

Source: https://insert-koin.io/docs/intro/koin-compiler-plugin

The Koin Compiler Plugin is a Kotlin compiler plugin that runs inside the Kotlin compiler (K2). It writes the constructor wiring for your definitions and checks your dependency graph at build time. It powers both the Compiler Plugin DSL and annotations. This page explains what it does and how. To install it, see [Compiler Plugin Setup](/docs/setup/compiler-plugin). To compare it with the Constructor and Classic DSL, see [Choosing your style](/docs/intro/choosing-your-style).

## What it does to your code

You write the type, the plugin writes the constructor call:

**Compiler Plugin DSL**
```kotlin
class UserRepository(private val api: ApiService, private val cache: UserCache)

val appModule = module {
    single<UserRepository>()
}
```

**Annotations**
```kotlin
@Singleton
class UserRepository(private val api: ApiService, private val cache: UserCache)
```

**Constructor / Classic DSL**
The Classic DSL does not need the plugin: you write the wiring yourself. The Constructor DSL (`singleOf(::T)`) doesn't need it either.

```kotlin
val appModule = module {
    single { UserRepository(get(), get()) }
}
```

If the plugin is applied, it still checks these `get()` calls and `singleOf(::T)` definitions at build time.

During compilation, the plugin replaces `single<UserRepository>()` (or the `@Singleton` class) with the equivalent of:

```kotlin
single { UserRepository(get(), get()) }
```

The generated code is the same runtime code the Classic DSL uses. Nothing changes at runtime: definitions go into the same container, and Koin resolves them the same way. Each parameter type is handled: nullable types use `getOrNull()`, `Lazy<T>` uses `inject()`, `List<T>` uses `getAll()`, and annotated parameters (`@Named`, `@InjectedParam`, `@Property`) use the matching call. The full table is in [Definitions](/docs/reference/koin-core/definitions#constructor-parameters).

In DSL style, the module says where a class is registered, and annotations on the class's parameters say how they are resolved:

```kotlin
class UserPresenter(
    @InjectedParam val userId: String,
    @Named("remote") val api: ApiService,
    val repository: UserRepository,
)

val appModule = module {
    factory<UserPresenter>()
}
```

## How it works

The plugin hooks into two phases of the Kotlin K2 compiler:

```text
Kotlin sources
     │
     ▼
  FIR (frontend)   finds @Module, @ComponentScan, @Configuration and declares
                   the generated module properties and cross-module hints
     │
     ▼
  IR (backend)     1. collects annotated definitions and fills the modules
                   2. rewrites DSL calls: single<T>() becomes single { T(get()) }
                   3. at entry points (startKoin, @KoinApplication), assembles
                      the full graph and validates it
                   4. validates get(), inject(), koinViewModel() call sites
     │
     ▼
  Bytecode (JVM, Android, Native, JS, Wasm)
```

No source file is generated in your project. To see across Gradle modules, the plugin adds small synthetic marker functions ("hints") to each compiled module. A downstream module reads them to find definitions declared in its dependencies. This is why every Gradle module that declares Koin definitions must apply the plugin.

## What it validates

The plugin validates the graph at each Koin entry point: `startKoin`, `koinApplication`, `@KoinApplication`, `KoinApplication.withConfiguration<T>()` and Ktor's `install(Koin) {}`. For each definition it checks that every non-nullable constructor parameter has a matching definition, with the right qualifier and in a reachable scope. It also checks every `get<T>()`, `inject<T>()` and `koinViewModel<T>()` call.

A missing dependency fails the build:

```text
[Koin][KOIN-D001] Missing dependency: ApiService
  required by: UserRepository (parameter 'api')
  in module: ...
```

The full list of checks, error codes and the `@Provided` escape hatch are in [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety).

## Limits

- **Runtime-loaded modules**: modules added later with `loadKoinModules()` are not part of the graph the plugin sees. Types they provide must be marked `@Provided`.
- **Library modules alone**: a Gradle module with no Koin entry point is not validated on its own. It is checked when an app module assembles it.
- **Incremental compilation**: like other IR compiler plugins, some changes (moving classes between scanned packages, changing qualifiers) can leave stale results. A clean build fixes them. See [Compiler Plugin Setup](/docs/setup/compiler-plugin) for details.
- **Kotlin versions**: the plugin uses compiler APIs that change between Kotlin releases. Each plugin release is verified on a list of Kotlin versions, and other versions print a warning.

## Requirements

- Kotlin 2.3.20 or later (K2 compiler). Plugin 1.2.1 is verified on Kotlin 2.3.20, 2.4.0, 2.4.10 and 2.4.20.
- Koin 4.2.0 or later.
- Gradle plugin `io.insert-koin.compiler.plugin`, applied in every Gradle module that declares definitions.

The Compiler Plugin DSL lives in the package `org.koin.plugin.module.dsl`, shipped with `koin-core`. The Classic DSL stays in `org.koin.dsl`, the Constructor DSL in `org.koin.core.module.dsl`.

The plugin replaces the deprecated KSP processor `koin-ksp-compiler`, with the same annotations. See [Migrating from KSP](/docs/migration/from-ksp-to-compiler-plugin). The source is on GitHub: [InsertKoinIO/koin-compiler-plugin](https://github.com/InsertKoinIO/koin-compiler-plugin).

## Related

- [Compiler Plugin Setup](/docs/setup/compiler-plugin): install and configure the plugin.
- [Choosing your style](/docs/intro/choosing-your-style): annotations or the DSL (Compiler Plugin, Constructor or Classic DSL).
- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): every check and error code.
- [Compiler Plugin Options](/docs/reference/koin-annotations/options): every Gradle option.
- [Definitions](/docs/reference/koin-core/definitions): how constructor parameters are resolved.

---

# Setup

Source: https://insert-koin.io/docs/setup

This section explains what to add to your Gradle build to use Koin. Pick your platform below, then follow the linked section of [Gradle Setup](/docs/setup/gradle). If you have not chosen a declaration style yet, read [Choosing your style](/docs/intro/choosing-your-style) first: it decides whether you also need the Compiler Plugin.

## What to install

| Platform | Artifacts | Setup |
|----------|-----------|-------|
| Kotlin/JVM | `koin-core` | [Kotlin/JVM](/docs/setup/gradle#kotlin) |
| Android | `koin-android` | [Android](/docs/setup/gradle#android) |
| Android with Jetpack Compose | `koin-android`, `koin-compose`, `koin-compose-viewmodel` | [Jetpack Compose](/docs/setup/gradle#compose-android) |
| Compose Multiplatform | `koin-compose`, `koin-compose-viewmodel` | [Compose Multiplatform](/docs/setup/gradle#compose) |
| Kotlin Multiplatform | `koin-core` in `commonMain` | [Kotlin Multiplatform](/docs/setup/gradle#kotlin-multiplatform) |
| Ktor | `koin-ktor`, `koin-logger-slf4j` | [Ktor](/docs/setup/gradle#ktor) |
| Tests | `koin-test`, `koin-test-junit4` or `koin-test-junit5` | [Testing](/docs/setup/gradle#testing) |

## Recommended setup

For a new project:

1. **Koin BOM**: import `io.insert-koin:koin-bom` and declare Koin artifacts without versions, so they always match. See [Gradle Setup](/docs/setup/gradle).
2. **Koin Compiler Plugin**: apply the Gradle plugin `io.insert-koin.compiler.plugin` to get the Compiler Plugin DSL or annotations, with compile-time checks. It needs Kotlin 2.3.20 or later. See [Compiler Plugin Setup](/docs/setup/compiler-plugin).

If you use the Constructor or Classic DSL only, step 1 is enough. Step 2 is still recommended: it adds compile-time checks to those definitions.

:::warning
The KSP processor `koin-ksp-compiler` is deprecated. Its setup is kept in [KSP Processor Setup](/docs/setup/annotations-ksp) for existing projects only. New projects use the Compiler Plugin.
:::

## Versions

| Component | Current version | Kotlin |
|-----------|-----------------|----------|
| Koin (all libraries, including `koin-annotations`) | 4.2.2 | Built with 2.3.20 |
| Koin Compiler Plugin | 1.2.1 | Verified on 2.3.20, 2.4.0, 2.4.10, 2.4.20 (needs Koin 4.2.0+) |

Latest published versions:

- Koin: [![Maven Central](https://img.shields.io/maven-central/v/io.insert-koin/koin-core?label=latest)](https://mvnrepository.com/artifact/io.insert-koin/koin-core)
- Koin Compiler Plugin: [![Maven Central](https://img.shields.io/maven-central/v/io.insert-koin/koin-compiler-plugin?label=latest)](https://mvnrepository.com/artifact/io.insert-koin/koin-compiler-plugin)

Older Koin lines:

| Koin | Kotlin | Compiler Plugin |
|------|--------|-----------------|
| 4.2.x | 2.3.20+ | Yes |
| 4.1.x | 2.1+ | No, KSP processor only |
| 4.0.x | 1.9+ | No, KSP processor only |
| 3.5.x | 1.8+ | No |

What changed between versions and how to upgrade is in [Releases](/docs/support/releases).

## Related

- [Gradle Setup](/docs/setup/gradle): the BOM and every Koin artifact.
- [Compiler Plugin Setup](/docs/setup/compiler-plugin): install and configure the plugin.
- [Choosing your style](/docs/intro/choosing-your-style): which style needs what.
- [Tutorials](/docs/quickstart/kotlin): a first app on each platform.
- [Releases](/docs/support/releases): versions and upgrade notes.

---

# Gradle Setup

Source: https://insert-koin.io/docs/setup/gradle

This page lists the Gradle dependencies for each platform and every published Koin artifact. Samples use the Kotlin DSL (`build.gradle.kts`) and a version catalog. To add compile-time checks and the Compiler Plugin DSL, also follow [Compiler Plugin Setup](/docs/setup/compiler-plugin).

## Versions

All Koin libraries, including `koin-annotations`, share one version. The current stable version is 4.2.2.

- Koin: [![Maven Central](https://img.shields.io/maven-central/v/io.insert-koin/koin-core?label=latest)](https://mvnrepository.com/artifact/io.insert-koin/koin-core)

All artifacts are on [Maven Central](https://central.sonatype.com/search?q=io.insert-koin) under the group `io.insert-koin`. Version history and upgrade notes are in [Releases](/docs/support/releases).

## Koin BOM

The Koin BOM (bill of materials) pins every Koin library to the same version. You declare the BOM version once and add Koin libraries without a version. When you update the BOM, all Koin libraries move together.

In `gradle/libs.versions.toml`:

```toml
[versions]
koin = "4.2.2"

[libraries]
koin-bom = { module = "io.insert-koin:koin-bom", version.ref = "koin" }
koin-core = { module = "io.insert-koin:koin-core" }
koin-android = { module = "io.insert-koin:koin-android" }
koin-compose = { module = "io.insert-koin:koin-compose" }
koin-compose-viewmodel = { module = "io.insert-koin:koin-compose-viewmodel" }
koin-compose-viewmodel-navigation = { module = "io.insert-koin:koin-compose-viewmodel-navigation" }
koin-ktor = { module = "io.insert-koin:koin-ktor" }
koin-logger-slf4j = { module = "io.insert-koin:koin-logger-slf4j" }
koin-annotations = { module = "io.insert-koin:koin-annotations" }
koin-test = { module = "io.insert-koin:koin-test" }
koin-test-junit4 = { module = "io.insert-koin:koin-test-junit4" }
```

In your module's `build.gradle.kts`:

```kotlin
dependencies {
    implementation(platform(libs.koin.bom))
    implementation(libs.koin.android)
}
```

Without a version catalog:

```kotlin
dependencies {
    implementation(platform("io.insert-koin:koin-bom:4.2.2"))
    implementation("io.insert-koin:koin-android")
    testImplementation("io.insert-koin:koin-test-junit4")
}
```

A version written on one dependency overrides the BOM for that dependency only. Avoid it unless you need a fix from a newer release of one library.

### Without the BOM

You can also put the version on each library. This is what the [Koin samples](https://github.com/InsertKoinIO/koin-getting-started) do, and it works the same in Kotlin Multiplatform source sets:

```toml
[versions]
koin = "4.2.2"

[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-android = { module = "io.insert-koin:koin-android", version.ref = "koin" }
```

Keep a single `koin` version for all Koin libraries: mixing versions is not supported.

## Kotlin/JVM {#kotlin}

```kotlin
dependencies {
    implementation(platform(libs.koin.bom))
    implementation(libs.koin.core)
}
```

Then start Koin in `main`. See [Starting Koin](/docs/reference/koin-core/starting-koin) and the [Kotlin tutorial](/docs/quickstart/kotlin).

## Android {#android}

```kotlin
dependencies {
    implementation(platform(libs.koin.bom))
    implementation(libs.koin.android)
}
```

`koin-android` includes `koin-core` and the ViewModel support. Start Koin in your `Application` class: see [Start Koin on Android](/docs/reference/koin-android/start).

Optional Android libraries:

| Artifact | Adds |
|----------|------|
| `koin-androidx-workmanager` | WorkManager workers: see [WorkManager](/docs/reference/koin-android/workmanager) |
| `koin-androidx-navigation` | ViewModels scoped to a Navigation graph (Fragments) |
| `koin-androidx-startup` | Start Koin with AndroidX App Startup |
| `koin-android-compat` | Java helpers to inject from Java classes |
| `koin-dagger-bridge` | Use Dagger components from Koin during a migration |

## Android with Jetpack Compose {#compose-android}

```kotlin
dependencies {
    implementation(platform(libs.koin.bom))
    implementation(libs.koin.android)
    implementation(libs.koin.compose)
    implementation(libs.koin.compose.viewmodel)
}
```

`koin-androidx-compose` is an Android-only artifact that brings `koin-compose` and `koin-compose-viewmodel` in one dependency. Either setup works.

For navigation, add one of:

| Artifact | Navigation library |
|----------|--------------------|
| `koin-androidx-compose-navigation` | Navigation Compose 2, Android only |
| `koin-compose-viewmodel-navigation` | Navigation Compose 2, multiplatform |
| `koin-compose-navigation3` | Navigation 3: see [Navigation 3](/docs/reference/koin-compose/navigation3) |

See [Koin for Compose](/docs/reference/koin-compose/compose) for the APIs.

## Compose Multiplatform {#compose}

In the shared module, add the Compose libraries to `commonMain`. In multiplatform source sets, use catalog entries that carry the version (see [Without the BOM](#without-the-bom)):

```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.koin.core)
            implementation(libs.koin.compose)
            implementation(libs.koin.compose.viewmodel)
            implementation(libs.koin.compose.viewmodel.navigation) // if you use Navigation Compose
        }
    }
}
```

On Android, `koin-compose` brings `koin-android`, so you don't need to add it. See the [Compose Multiplatform tutorial](/docs/quickstart/cmp).

## Kotlin Multiplatform {#kotlin-multiplatform}

In the shared module's `build.gradle.kts`, with catalog entries that carry the version (see [Without the BOM](#without-the-bom)):

```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.koin.core)
        }
        androidMain.dependencies {
            implementation(libs.koin.android)
        }
        commonTest.dependencies {
            implementation(libs.koin.test)
        }
    }
}
```

`koin-core` supports JVM, Android, Apple targets (iOS, macOS, tvOS, watchOS), Linux, Windows, JS and Wasm (`wasmJs`). Project structure and platform-specific definitions are covered in [Kotlin Multiplatform Setup](/docs/reference/koin-core/kmp-setup).

## Ktor {#ktor}

```kotlin
dependencies {
    implementation(platform(libs.koin.bom))
    implementation(libs.koin.ktor)
    implementation(libs.koin.logger.slf4j)
}
```

Install the Koin plugin in your Ktor application: see [Koin for Ktor](/docs/reference/koin-ktor/ktor).

## Testing {#testing}

```kotlin
dependencies {
    testImplementation(libs.koin.test)
    testImplementation(libs.koin.test.junit4) // or koin-test-junit5
}
```

For Android instrumented tests, add `koin-android-test` to `androidTestImplementation`. See [Injecting in Tests](/docs/reference/koin-test/testing) and [Android Instrumented Testing](/docs/reference/koin-android/instrumented-testing).

## All artifacts

| Artifact | Platforms | Description |
|----------|-----------|-------------|
| `koin-bom` | All | Bill of materials for every artifact below |
| `koin-core` | All | Container, DSL, scopes, Compiler Plugin DSL |
| `koin-core-coroutines` | All | Lazy modules and background loading |
| `koin-core-viewmodel` | All | ViewModel definitions for Android and Compose Multiplatform |
| `koin-annotations` | All | Annotations for the Compiler Plugin (`@Singleton`, `@Module`, `@Named`, ...) |
| `koin-android` | Android | Android context, Activity and Fragment APIs, ViewModel |
| `koin-android-compat` | Android | Java compatibility helpers |
| `koin-androidx-navigation` | Android | Navigation graph scoped ViewModels |
| `koin-androidx-workmanager` | Android | WorkManager integration |
| `koin-androidx-startup` | Android | AndroidX App Startup integration |
| `koin-dagger-bridge` | Android | Access Dagger components from Koin |
| `koin-compose` | All Compose targets | `koinInject()`, `KoinApplication` and Compose context |
| `koin-compose-viewmodel` | All Compose targets | `koinViewModel()` |
| `koin-compose-viewmodel-navigation` | All Compose targets | ViewModels scoped to a Navigation Compose back stack entry |
| `koin-compose-navigation3` | All Compose targets | Navigation 3 integration |
| `koin-androidx-compose` | Android | Bundle of `koin-compose` and `koin-compose-viewmodel` for Android |
| `koin-androidx-compose-navigation` | Android | Navigation Compose 2 for Android |
| `koin-ktor` | JVM, JS, Wasm, iOS, macOS (Ktor server targets) | Ktor server plugin |
| `koin-logger-slf4j` | JVM | SLF4J logger |
| `koin-test` | All | Test API: `KoinTest`, `verify()` |
| `koin-test-coroutines` | JVM | Verification for lazy modules |
| `koin-test-junit4` | JVM | JUnit 4 rules |
| `koin-test-junit5` | JVM | JUnit 5 extensions |
| `koin-android-test` | Android | Instrumented test helpers |

The Koin Compiler Plugin is a Gradle plugin, not a library: it has its own version. See [Compiler Plugin Setup](/docs/setup/compiler-plugin).

## Related

- [Compiler Plugin Setup](/docs/setup/compiler-plugin): add the Compiler Plugin and compile-time checks.
- [Setup](/docs/setup): what to install for each platform.
- [Starting Koin](/docs/reference/koin-core/starting-koin): start the container once dependencies are in place.
- [Tutorials](/docs/quickstart/kotlin): a first app on each platform.
- [Releases](/docs/support/releases): versions and upgrade notes.

---

# Compiler Plugin Setup

Source: https://insert-koin.io/docs/setup/compiler-plugin

This page installs the Koin Compiler Plugin, the Kotlin compiler plugin behind the Compiler Plugin DSL and annotations. It covers single-module, multi-module and Kotlin Multiplatform builds, the main options, and setup problems. To learn what the plugin does, read [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin). Koin libraries themselves are listed in [Gradle Setup](/docs/setup/gradle).

## Requirements

- Kotlin 2.3.20 or later (K2 compiler).
- Koin 4.2.0 or later.
- Gradle 8 or later.

Current versions:

- Koin: [![Maven Central](https://img.shields.io/maven-central/v/io.insert-koin/koin-core?label=latest)](https://mvnrepository.com/artifact/io.insert-koin/koin-core)
- Koin Compiler Plugin: [![Maven Central](https://img.shields.io/maven-central/v/io.insert-koin/koin-compiler-plugin?label=latest)](https://mvnrepository.com/artifact/io.insert-koin/koin-compiler-plugin)

The plugin has its own version, separate from Koin. `koin-annotations` follows the Koin version.

## Install

### 1. Declare the plugin

In `gradle/libs.versions.toml`:

```toml
[versions]
koin = "4.2.2"
koin-plugin = "1.2.1"

[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```

If you use the [Koin BOM](/docs/setup/gradle#koin-bom), drop `version.ref` from the libraries. The plugin is not part of the BOM and keeps its version.

### 2. Plugin repositories

The plugin is published on Maven Central and the Gradle Plugin Portal. In `settings.gradle.kts`:

```kotlin
pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}
```

### 3. Apply the plugin

In the `build.gradle.kts` of each Gradle module that declares Koin definitions:

```kotlin
plugins {
    alias(libs.plugins.koin.compiler)
}

dependencies {
    implementation(libs.koin.core)          // or koin-android, koin-ktor, ...
    implementation(libs.koin.annotations)   // for annotations, and for @Named or @InjectedParam in DSL style
}
```

The Compiler Plugin DSL (`single<T>()`, `factory<T>()`, `viewModel<T>()`) ships with the Koin libraries, in the package `org.koin.plugin.module.dsl`. You need `koin-annotations` only if you use annotations, including parameter annotations in DSL style.

:::tip
`@KoinViewModel` and `@KoinWorker` need their runtime library on the classpath: `koin-core-viewmodel` (included in `koin-android` and `koin-compose-viewmodel`) and `koin-androidx-workmanager`. If one is missing, the build fails with an error that names the artifact.
:::

### 4. Check that it works

Turn on the plugin logs for one build:

```kotlin
koinCompiler {
    userLogs = true
}
```

The build output lists each definition the plugin detected. Turn it off again once you have checked. Then start Koin as described in [Starting Koin](/docs/reference/koin-core/starting-koin), with `startKoin { }` or, for annotations, `startKoin<MyApp>()`.

## Multi-module projects

Apply the plugin in every Gradle module that declares definitions, not only in the app module:

```kotlin
// feature/build.gradle.kts
plugins {
    alias(libs.plugins.koin.compiler)
}

dependencies {
    implementation(libs.koin.core)
    implementation(libs.koin.annotations)
}
```

```kotlin
// app/build.gradle.kts
plugins {
    alias(libs.plugins.koin.compiler)
}

dependencies {
    implementation(project(":feature"))
    implementation(libs.koin.android)
    implementation(libs.koin.annotations)
}
```

Each module compiled with the plugin carries metadata about its definitions. The app module reads it to check the full graph at `startKoin`. A library module without the plugin is invisible to these checks. How to assemble modules across Gradle modules (`includes`, `@Configuration`) is covered in [Modules](/docs/reference/koin-core/modules) and [Multi-Module Android Apps](/docs/reference/koin-android/multi-module).

## Kotlin Multiplatform

Apply the plugin once on the shared module and add the libraries to `commonMain`. There is no per-target configuration:

```kotlin
// shared/build.gradle.kts
plugins {
    alias(libs.plugins.kotlin.multiplatform)
    alias(libs.plugins.koin.compiler)
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.koin.core)
            implementation(libs.koin.annotations)
        }
    }
}
```

See [Kotlin Multiplatform Setup](/docs/reference/koin-core/kmp-setup) for project structure.

## Options

The `koinCompiler` block configures the plugin. The defaults fit most projects:

```kotlin
koinCompiler {
    compileSafety = true      // validate the graph at build time
    skipDefaultValues = true  // use Kotlin default values instead of injecting
    userLogs = false          // log detected definitions
}
```

Every option, including `strictSafety`, `unsafeDslChecks`, `logSeverity` and `debugLogs`, is described in [Compiler Plugin Options](/docs/reference/koin-annotations/options).

## Kotlin version compatibility

Each plugin release is verified on a list of Kotlin versions:

| Kotlin | Koin Compiler Plugin |
|--------|----------------------|
| 2.3.20, 2.4.0, 2.4.10 | 1.2.0+ |
| 2.4.20 | 1.2.1+ |

On a Kotlin version that is not in the list, the plugin prints a warning and the build continues.

:::warning
On Kotlin 2.4.20, plugin 1.2.0 fails with `NoSuchMethodError` during IR generation. Use 1.2.1 or later.
:::

## Troubleshooting

### Plugin not found

Gradle can't resolve `io.insert-koin.compiler.plugin`. Check that `mavenCentral()` and `gradlePluginPortal()` are in `pluginManagement.repositories` in `settings.gradle.kts`.

### NotImplementedError at runtime

`single<T>()`, `factory<T>()` and `create(::T)` are placeholders that the plugin replaces. If the plugin is not applied to the Gradle module that contains them, the code compiles and throws `NotImplementedError` when the module is created. Apply the plugin to that module.

### Wrong imports

The Compiler Plugin DSL and the Constructor DSL have functions with the same names in different packages:

```kotlin
// Compiler Plugin DSL
import org.koin.plugin.module.dsl.*

// Constructor DSL: singleOf, factoryOf, viewModelOf
import org.koin.core.module.dsl.*

// both
import org.koin.dsl.module
```

### Stale results after a refactor

Like other Kotlin IR plugins (the Compose compiler, for example), the Koin Compiler Plugin can produce stale results with incremental compilation. Symptoms:

- A compile safety error that should not appear, or none after you removed a definition.
- `NoSuchMethodError` or `ClassNotFoundException` at runtime after a refactor.

It usually follows these changes:

- Changing an annotation on a class (`@Singleton` to `@Factory`, adding or removing `@Named`).
- Moving classes between packages scanned by `@ComponentScan`.
- Changing module `includes` or `@Configuration` labels.
- Adding or removing definitions in a library module another module depends on.

Run a clean build: `./gradlew clean build`, or in Android Studio, Build > Clean Project then Build > Rebuild Project.

For changes inside `module { }` lambdas, the plugin turns on `strictSafety` for modules that contain an entry point (`startKoin`, `koinApplication`, `@KoinApplication`). It re-runs the full graph check on each build of those modules. See [`strictSafety`](/docs/reference/koin-annotations/options).

### Missing dependency reported across modules

If the plugin reports a missing dependency that a library module does declare:

1. Apply the plugin to the library module too. Without it, the library carries no metadata.
2. Make sure the library is built before the module that uses it. `implementation(project(":lib"))` normally does this.
3. Run a clean build after adding the plugin to a library for the first time.
4. Use plugin 1.2.1 or later. Earlier versions missed definitions two or more `implementation` levels away and merged `@Named` providers across modules. If you turned `compileSafety` off because of false `KOIN-D001` errors, turn it back on.

## Moving to the Compiler Plugin

- **From the Constructor or Classic DSL**: apply the plugin. Your existing `singleOf(::T)` definitions and `get()` calls are checked at build time without changes. You can then replace them with `single<T>()` module by module. See [Choosing your style](/docs/intro/choosing-your-style).
- **From the KSP processor**: remove KSP and `koin-ksp-compiler`, apply the plugin, and replace the generated `.module` extensions with `startKoin<MyApp>()`. Your annotations stay the same. See [Migrating from KSP](/docs/migration/from-ksp-to-compiler-plugin).

## Related

- [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin): what the plugin does and how it works.
- [Compiler Plugin Options](/docs/reference/koin-annotations/options): every Gradle option.
- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): every check and error code.
- [Gradle Setup](/docs/setup/gradle): Koin libraries and the BOM.
- [Starting Koin](/docs/reference/koin-core/starting-koin): typed start APIs such as `startKoin<MyApp>()`.

---

# KSP Processor Setup (Deprecated)

Source: https://insert-koin.io/docs/setup/annotations-ksp

This page documents the Gradle setup of `koin-ksp-compiler`, the KSP processor that used to read Koin annotations. It is kept for projects that still use it. New projects use the [Koin Compiler Plugin](/docs/setup/compiler-plugin).

:::warning
`koin-ksp-compiler` is deprecated and will be removed in a future Koin version. The annotations are not deprecated: `koin-annotations` is part of the main Koin project and is processed by the Koin Compiler Plugin. Only the processor changes. See [Migrating from KSP to the Compiler Plugin](/docs/migration/from-ksp-to-compiler-plugin).
:::

## When to keep the KSP processor

Keep it only for a short time, if:

- **Kotlin version**: your project can't move to Kotlin 2.3.20 or later yet, which the Compiler Plugin requires.
- **Migration in progress**: you need to ship before you can switch the build.

Compared with the Compiler Plugin, the KSP processor generates visible source files, needs a KSP configuration per Kotlin Multiplatform target, and uses generated extensions such as `AppModule().module` to start Koin.

## Gradle setup

```kotlin
// build.gradle.kts
plugins {
    id("com.google.devtools.ksp") version "$ksp_version"
}

dependencies {
    implementation(platform("io.insert-koin:koin-bom:$koin_version"))
    implementation("io.insert-koin:koin-core")
    implementation("io.insert-koin:koin-annotations:$koin_ksp_version")
    ksp("io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
}
```

With KSP, `koin-annotations` and `koin-ksp-compiler` use the Koin Annotations version (`$koin_ksp_version`), not the Koin version. With the Compiler Plugin, `koin-annotations` follows the Koin version.

### Version compatibility

| Koin Annotations | KSP | Kotlin |
|------------------|-----|--------|
| 1.4 | 1.9 | 1.9 |
| 2.0 | 2.0 | 2.0 |
| 2.1, 2.2 | 2.1, 2.2 | 2.1, 2.2 |
| 2.3 | 2.3 | Independent |

## Starting Koin with generated modules

KSP generates a `.module` extension for each `@Module` class:

```kotlin
import org.koin.ksp.generated.*

@Single
class MyComponent

@Module
@ComponentScan
class MyModule

fun main() {
    startKoin {
        modules(MyModule().module)
    }
}
```

## Compile-time check

The KSP processor has its own configuration check, turned on with a KSP argument:

```kotlin
// build.gradle.kts
ksp {
    arg("KOIN_CONFIG_CHECK", "true")
}
```

The Compiler Plugin replaces it with checks of the full graph and of every `get()` call site. See [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety).

## Kotlin Multiplatform

KSP needs one configuration per target:

```kotlin
// shared/build.gradle.kts
plugins {
    id("com.google.devtools.ksp")
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.insert-koin:koin-core:$koin_version")
            implementation("io.insert-koin:koin-annotations:$koin_ksp_version")
        }
    }
}

dependencies {
    add("kspAndroid", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
    add("kspIosX64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
    add("kspIosArm64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
    add("kspIosSimulatorArm64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
}
```

With the Compiler Plugin, you apply the plugin once and add `koin-annotations` to `commonMain`.

## Moving to the Compiler Plugin

The move keeps your annotated classes as they are. You remove KSP and `koin-ksp-compiler`, apply the Compiler Plugin, delete the generated sources, and replace `modules(MyModule().module)` with `startKoin<MyApp>()`. The step-by-step guide is [Migrating from KSP to the Compiler Plugin](/docs/migration/from-ksp-to-compiler-plugin).

If you get stuck, ask on the [Kotlin Slack #koin channel](https://kotlinlang.slack.com/messages/koin/) or open an issue on [InsertKoinIO/koin-annotations](https://github.com/InsertKoinIO/koin-annotations).

## Related

- [Migrating from KSP](/docs/migration/from-ksp-to-compiler-plugin): step-by-step migration.
- [Compiler Plugin Setup](/docs/setup/compiler-plugin): install the replacement.
- [Choosing your style](/docs/intro/choosing-your-style): annotations and the other styles.
- [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): every annotation.

---

# Kotlin

Source: https://insert-koin.io/docs/quickstart/kotlin

In this tutorial you build a Kotlin console app that loads a list of users and prints a greeting. You learn how to declare a Koin module, bind implementations to interfaces, and start Koin. It takes about 10 minutes and needs a JDK 17 and Gradle.

This tutorial uses the Compiler Plugin DSL. For the same app with annotations, see [Kotlin & Annotations](/docs/quickstart/kotlin-annotations). To compare the styles, see [Choosing your style](/docs/intro/choosing-your-style).

## Get the code

The full sample is in [koin-getting-started/kotlin](https://github.com/InsertKoinIO/koin-getting-started/tree/main/kotlin). Clone the repository and run it from the `kotlin` folder:

```bash
./gradlew run
```

## Gradle setup

The sample applies the Koin Compiler Plugin and adds `koin-core`. Versions live in a version catalog:

```toml
# gradle/libs.versions.toml
[versions]
kotlin = "<KOTLIN_VERSION>"
koin = "<KOIN_VERSION>"
koin-plugin = "<KOIN_PLUGIN_VERSION>"

[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-test = { module = "io.insert-koin:koin-test", version.ref = "koin" }
koin-test-junit4 = { module = "io.insert-koin:koin-test-junit4", version.ref = "koin" }

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```

```kotlin
// app/build.gradle.kts
plugins {
    alias(libs.plugins.kotlin.jvm)
    alias(libs.plugins.koin.compiler)
    application
}

dependencies {
    implementation(libs.koin.core)

    testImplementation(libs.koin.test)
    testImplementation(libs.koin.test.junit4)
}
```

The Compiler Plugin needs Kotlin 2.3.20 or later. For current versions and the BOM, see [Gradle setup](/docs/setup/gradle). For plugin options, see [Compiler Plugin setup](/docs/setup/compiler-plugin).

## The application

The app chains three components. `UserApplication` asks `UserService` for a user, and `UserService` reads from `UserRepository`:

```
User -> UserRepository -> UserService -> UserApplication
```

## Let's write the user data

Start with the data class and a default list of users:

```kotlin
data class User(val name: String, val email: String)

val DEFAULT_USER = User("Alice", "alice@example.com")

val DEFAULT_USERS = listOf(
    DEFAULT_USER,
    User("Bob", "bob@example.com"),
    User("Charlie", "charlie@example.com")
)
```

These users are the data that the repository stores.

## Let's write the repository

The repository keeps users in memory and finds one by name:

```kotlin
interface UserRepository {
    fun findUserOrNull(name: String): User?
    fun addUsers(users: List<User>)
}

class UserRepositoryImpl : UserRepository {

    private val _users = arrayListOf<User>()

    override fun findUserOrNull(name: String): User? {
        return _users.firstOrNull { it.name == name }
    }

    override fun addUsers(users: List<User>) {
        _users.addAll(users)
    }
}
```

`UserRepositoryImpl` has no dependency, so Koin can create it with no extra information.

## Let's declare the Koin module

A module is where you declare the components Koin creates (see [Core Concepts](/docs/intro/core-concepts)). Declare `UserRepositoryImpl` as a singleton, available as `UserRepository`:

```kotlin
import org.koin.dsl.bind
import org.koin.dsl.module
import org.koin.plugin.module.dsl.single

val appModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class
}
```

Any component that asks for a `UserRepository` now gets the same `UserRepositoryImpl` instance. `single` and `bind` are described in [Definitions](/docs/reference/koin-core/definitions).

## Let's write the service

`UserService` loads the users and prepares the greeting:

```kotlin
interface UserService {
    fun getUserOrNull(name: String = DEFAULT_USER.name): User?
    fun loadUsers()
    fun prepareHelloMessage(user: User?): String
}

class UserServiceImpl(
    private val userRepository: UserRepository
) : UserService {

    override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)

    override fun loadUsers() {
        userRepository.addUsers(DEFAULT_USERS)
    }

    override fun prepareHelloMessage(user: User?): String {
        return user?.let { "Hello '${user.name}' (${user.email})!" } ?: "User not found"
    }
}
```

Add it to the module:

```kotlin
val appModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class
    single<UserServiceImpl>() bind UserService::class
}
```

`UserServiceImpl` takes a `UserRepository` in its constructor. The Compiler Plugin reads that constructor and passes the `UserRepositoryImpl` instance for you.

## Let's write the application class

`UserApplication` receives `UserService` through its constructor, loads the users and prints the greeting:

```kotlin
class UserApplication(
    private val userService: UserService
) {

    init {
        userService.loadUsers()
    }

    fun sayHello(name: String) {
        val user = userService.getUserOrNull(name)
        val message = userService.prepareHelloMessage(user)
        println(message)
    }
}
```

Declare it in the module too:

```kotlin
val appModule = module {
    single<UserApplication>()
    single<UserRepositoryImpl>() bind UserRepository::class
    single<UserServiceImpl>() bind UserService::class
}
```

All three components are now in the module. The plugin checks at build time that each constructor parameter has a definition.

## Let's start Koin

Start Koin in `main()` with your module, then get `UserApplication` from the container:

```kotlin
import org.koin.core.context.startKoin
import org.koin.mp.KoinPlatform

fun main() {
    startKoin {
        modules(appModule)
    }

    val userApplication = KoinPlatform.getKoin().get<UserApplication>()
    userApplication.sayHello("Alice")
}
```

Run `./gradlew run` and the app prints `Hello 'Alice' (alice@example.com)!`. `startKoin` and its options are covered in [Starting Koin](/docs/reference/koin-core/starting-koin).

## Next steps

- [Core Concepts](/docs/intro/core-concepts): the mental model behind modules, definitions and injection.
- [Definitions](/docs/reference/koin-core/definitions): every definition type and binding option.
- [JUnit Tests](/docs/quickstart/junit-test): test this same app with Koin Test.
- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): what the Compiler Plugin checks in your graph.
- [Tooling](/docs/tooling): IDE plugin and monitoring tools for Koin.

---

# Kotlin & Annotations

Source: https://insert-koin.io/docs/quickstart/kotlin-annotations

In this tutorial you build a Kotlin console app that loads a list of users and prints a greeting. You learn how to annotate classes, scan them into a module, and start Koin from a `@KoinApplication` object. It takes about 10 minutes and needs a JDK 17 and Gradle.

This tutorial uses annotations. For the same app with the Compiler Plugin DSL, see [Kotlin](/docs/quickstart/kotlin). To compare the styles, see [Choosing your style](/docs/intro/choosing-your-style).

## Get the code

The full sample is in [koin-getting-started/kotlin-annotations](https://github.com/InsertKoinIO/koin-getting-started/tree/main/kotlin-annotations). Clone the repository and run it from the `kotlin-annotations` folder:

```bash
./gradlew run
```

## Gradle setup

The sample applies the Koin Compiler Plugin and adds `koin-core` and `koin-annotations`. Versions live in a version catalog:

```toml
# gradle/libs.versions.toml
[versions]
kotlin = "<KOTLIN_VERSION>"
koin = "<KOIN_VERSION>"
koin-plugin = "<KOIN_PLUGIN_VERSION>"

[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }
koin-test = { module = "io.insert-koin:koin-test", version.ref = "koin" }
koin-test-junit4 = { module = "io.insert-koin:koin-test-junit4", version.ref = "koin" }

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```

```kotlin
// app/build.gradle.kts
plugins {
    alias(libs.plugins.kotlin.jvm)
    alias(libs.plugins.koin.compiler)
    application
}

dependencies {
    implementation(libs.koin.core)
    implementation(libs.koin.annotations)

    testImplementation(libs.koin.test)
    testImplementation(libs.koin.test.junit4)
}
```

The Compiler Plugin processes the annotations and needs Kotlin 2.3.20 or later. `koin-annotations` shares the Koin version. For details, see [Gradle setup](/docs/setup/gradle) and [Compiler Plugin setup](/docs/setup/compiler-plugin).

## The application

The app chains three components. `UserApplication` asks `UserService` for a user, and `UserService` reads from `UserRepository`:

```
User -> UserRepository -> UserService -> UserApplication
```

## Let's write the user data

Start with the data class and a default list of users:

```kotlin
data class User(val name: String, val email: String)

val DEFAULT_USER = User("Alice", "alice@example.com")

val DEFAULT_USERS = listOf(
    DEFAULT_USER,
    User("Bob", "bob@example.com"),
    User("Charlie", "charlie@example.com")
)
```

These users are the data that the repository stores.

## Let's write the repository

The repository keeps users in memory. Annotate the implementation with `@Singleton` to declare it as a singleton:

```kotlin
import org.koin.core.annotation.Singleton

interface UserRepository {
    fun findUserOrNull(name: String): User?
    fun addUsers(users: List<User>)
}

@Singleton
class UserRepositoryImpl : UserRepository {

    private val _users = arrayListOf<User>()

    override fun findUserOrNull(name: String): User? {
        return _users.firstOrNull { it.name == name }
    }

    override fun addUsers(users: List<User>) {
        _users.addAll(users)
    }
}
```

Koin binds `UserRepositoryImpl` to its supertypes, so a request for `UserRepository` gets this instance. `@Singleton` comes from `org.koin.core.annotation` and is equivalent to `@Single` (see [Definitions](/docs/reference/koin-core/definitions)).

## Let's write the service

`UserService` loads the users and prepares the greeting. It is a `@Singleton` too:

```kotlin
interface UserService {
    fun getUserOrNull(name: String = DEFAULT_USER.name): User?
    fun loadUsers()
    fun prepareHelloMessage(user: User?): String
}

@Singleton
class UserServiceImpl(
    private val userRepository: UserRepository
) : UserService {

    override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)

    override fun loadUsers() {
        userRepository.addUsers(DEFAULT_USERS)
    }

    override fun prepareHelloMessage(user: User?): String {
        return user?.let { "Hello '${user.name}' (${user.email})!" } ?: "User not found"
    }
}
```

The Compiler Plugin reads the constructor and passes the `UserRepository` instance for you.

## Let's write the application class

`UserApplication` receives `UserService` through its constructor, loads the users and prints the greeting:

```kotlin
@Singleton
class UserApplication(
    private val userService: UserService
) {

    init {
        userService.loadUsers()
    }

    fun sayHello(name: String) {
        val user = userService.getUserOrNull(name)
        val message = userService.prepareHelloMessage(user)
        println(message)
    }
}
```

All three components are now annotated. Next, gather them in a module.

## Let's declare the Koin module

A module groups definitions (see [Core Concepts](/docs/intro/core-concepts)). Declare a module class that scans the sample package:

```kotlin
import org.koin.core.annotation.ComponentScan
import org.koin.core.annotation.Configuration
import org.koin.core.annotation.Module

@Module
@ComponentScan("org.koin.sample")
@Configuration
class AppModule
```

`@ComponentScan` registers every annotated class in `org.koin.sample` and its subpackages. `@Configuration` makes the module discoverable by a `@KoinApplication` entry point. Both are described in [Modules](/docs/reference/koin-core/modules).

## Let's start Koin

Declare a `@KoinApplication` object and start Koin with the typed `startKoin<T>()`:

```kotlin
import org.koin.core.annotation.KoinApplication
import org.koin.mp.KoinPlatform
import org.koin.plugin.module.dsl.startKoin

@KoinApplication
object KoinUserApplication

fun main() {
    startKoin<KoinUserApplication>()

    val userApplication = KoinPlatform.getKoin().get<UserApplication>()
    userApplication.sayHello("Alice")
}
```

`startKoin<KoinUserApplication>()` loads every `@Configuration` module, so you don't call `modules()`. The plugin validates the full graph at build time, and `./gradlew run` prints `Hello 'Alice' (alice@example.com)!`. See [Starting Koin](/docs/reference/koin-core/starting-koin) for the other options.

## Next steps

- [Core Concepts](/docs/intro/core-concepts): the mental model behind modules, definitions and injection.
- [Modules](/docs/reference/koin-core/modules): `@Module`, `@ComponentScan`, `@Configuration` and module includes.
- [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): every annotation and its parameters.
- [Testing](/docs/reference/koin-test/testing): write tests with Koin Test.
- [Tooling](/docs/tooling): IDE plugin and monitoring tools for Koin.

---

# Android

Source: https://insert-koin.io/docs/quickstart/android

In this tutorial you build an Android app that greets a user picked from a list. You learn how to declare a Koin module, inject a presenter in an Activity, and start Koin from your `Application` class. It takes about 10 minutes and needs Android Studio.

This tutorial uses the Compiler Plugin DSL. For the same app with annotations, see [Android & Annotations](/docs/quickstart/android-annotations). To compare the styles, see [Choosing your style](/docs/intro/choosing-your-style). The [Android ViewModel](/docs/quickstart/android-viewmodel) tutorial builds the same app with a ViewModel instead of a presenter.

## Get the code

The full sample is in [koin-getting-started/android](https://github.com/InsertKoinIO/koin-getting-started/tree/main/android). Clone the repository and open the `android` folder in Android Studio.

## Gradle setup

The sample applies the Koin Compiler Plugin and adds `koin-android`. Versions live in a version catalog:

```toml
# gradle/libs.versions.toml
[versions]
# Kotlin, Android Gradle Plugin and AndroidX entries omitted
koin = "<KOIN_VERSION>"
koin-plugin = "<KOIN_PLUGIN_VERSION>"

[libraries]
koin-android = { module = "io.insert-koin:koin-android", version.ref = "koin" }
koin-test-junit4 = { module = "io.insert-koin:koin-test-junit4", version.ref = "koin" }
koin-android-test = { module = "io.insert-koin:koin-android-test", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```

```kotlin
// app/build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.koin.compiler)
}

dependencies {
    implementation(libs.android.appcompat)
    implementation(libs.koin.android)

    testImplementation(libs.koin.test.junit4)
    testImplementation(libs.koin.android.test)
}
```

The Compiler Plugin needs Kotlin 2.3.20 or later. For current versions and the BOM, see [Gradle setup](/docs/setup/gradle). For plugin options, see [Compiler Plugin setup](/docs/setup/compiler-plugin).

## The application

The Activity asks a presenter for a greeting. The presenter uses `UserService`, which reads from `UserRepository`:

```
User -> UserRepository -> UserService -> UserPresenter -> MainActivity
```

## Let's write the user data

Start with the data class and a default list of users:

```kotlin
data class User(val name: String, val email: String)

val DEFAULT_USER = User("Alice", "alice@example.com")

val DEFAULT_USERS = listOf(
    DEFAULT_USER,
    User("Bob", "bob@example.com"),
    User("Charlie", "charlie@example.com")
)
```

These users are the data that the repository stores.

## Let's write the repository

The repository keeps users in memory and finds one by name:

```kotlin
interface UserRepository {
    fun findUserOrNull(name: String): User?
    fun addUsers(users: List<User>)
}

class UserRepositoryImpl : UserRepository {

    private val _users = arrayListOf<User>()

    override fun findUserOrNull(name: String): User? {
        return _users.firstOrNull { it.name == name }
    }

    override fun addUsers(users: List<User>) {
        _users.addAll(users)
    }
}
```

`UserRepositoryImpl` has no dependency, so Koin can create it with no extra information.

## Let's write the service

`UserService` loads the users when it is created and prepares the greeting:

```kotlin
interface UserService {
    fun getUserOrNull(name: String = DEFAULT_USER.name): User?
    fun loadUsers()
    fun prepareHelloMessage(user: User?): String
}

class UserServiceImpl(
    private val userRepository: UserRepository
) : UserService {

    init {
        loadUsers()
    }

    override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)

    override fun loadUsers() {
        userRepository.addUsers(DEFAULT_USERS)
    }

    override fun prepareHelloMessage(user: User?): String {
        return user?.let { "Hello '${user.name}' (${user.email})!" } ?: "User not found"
    }
}
```

`UserServiceImpl` depends on `UserRepository`. Koin passes it through the constructor.

## Let's declare the Koin module

A module is where you declare the components Koin creates (see [Core Concepts](/docs/intro/core-concepts)). Declare both components as singletons, bound to their interfaces:

```kotlin
import org.koin.dsl.bind
import org.koin.dsl.module
import org.koin.plugin.module.dsl.single

val appModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class
    single<UserServiceImpl>() bind UserService::class
}
```

Any component that asks for `UserService` now gets the same `UserServiceImpl` instance. `single` and `bind` are described in [Definitions](/docs/reference/koin-core/definitions).

## Let's write the presenter

The presenter turns a name into a greeting:

```kotlin
class UserPresenter(
    private val userService: UserService
) {

    fun sayHello(name: String): String {
        val user = userService.getUserOrNull(name)
        val message = userService.prepareHelloMessage(user)
        return "[UserPresenter] $message"
    }
}
```

Declare it with `factory`, so each request creates a new instance and Koin keeps no reference to it:

```kotlin
import org.koin.plugin.module.dsl.factory

val appModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class
    single<UserServiceImpl>() bind UserService::class
    factory<UserPresenter>()
}
```

A `factory` presenter cannot outlive the Activity that uses it, which avoids leaking the Activity.

## Let's inject the presenter in the Activity

Use the `by inject()` delegate to get the presenter in `MainActivity`:

```kotlin
import org.koin.android.ext.android.inject

class MainActivity : AppCompatActivity() {

    private val presenter: UserPresenter by inject()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_simple)

        val nameInput = findViewById<EditText>(R.id.nameInput)
        val sayHelloButton = findViewById<Button>(R.id.sayHelloButton)
        val textField = findViewById<TextView>(R.id.text)

        sayHelloButton.setOnClickListener {
            val userName = nameInput.text.toString().trim().ifEmpty { "Alice" }
            textField.text = presenter.sayHello(userName)
        }
    }
}
```

`by inject()` resolves the presenter lazily, the first time you use it. The other Android components that support it are listed in [Android Entry Points](/docs/reference/koin-android/entry-points).

## Let's start Koin

Start Koin in your `Application` class, and register that class in `AndroidManifest.xml`:

```kotlin
import org.koin.android.ext.koin.androidContext
import org.koin.android.ext.koin.androidLogger
import org.koin.core.context.startKoin
import org.koin.core.logger.Level

class MainApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        startKoin {
            androidLogger(Level.DEBUG)
            androidContext(this@MainApplication)
            modules(appModule)
        }
    }
}
```

`androidContext()` makes the Android `Context` available to your definitions, and `androidLogger()` sends Koin logs to Logcat. Run the app, type a name and tap the button to see the greeting. See [Starting Koin on Android](/docs/reference/koin-android/start) for the other options.

## Next steps

- [Core Concepts](/docs/intro/core-concepts): the mental model behind modules, definitions and injection.
- [Android ViewModel](/docs/quickstart/android-viewmodel): the same app with a ViewModel.
- [Android Entry Points](/docs/reference/koin-android/entry-points): inject in Fragments, Services, receivers and more.
- [Instrumented testing](/docs/reference/koin-android/instrumented-testing): test your Android app with Koin.
- [Tooling](/docs/tooling): IDE plugin and monitoring tools for Koin.

---

# Android ViewModel

Source: https://insert-koin.io/docs/quickstart/android-viewmodel

In this tutorial you build an Android app that greets a user picked from a list. You learn how to declare a ViewModel in a Koin module, inject it in an Activity, and start Koin from your `Application` class. It takes about 10 minutes and needs Android Studio.

This tutorial uses the Compiler Plugin DSL. For the same app with annotations, see [Android & Annotations](/docs/quickstart/android-annotations). To compare the styles, see [Choosing your style](/docs/intro/choosing-your-style).

## Get the code

The full sample is in [koin-getting-started/android](https://github.com/InsertKoinIO/koin-getting-started/tree/main/android). Clone the repository and open the `android` folder in Android Studio.

## Gradle setup

The sample applies the Koin Compiler Plugin and adds `koin-android`, which includes the ViewModel support. Versions live in a version catalog:

```toml
# gradle/libs.versions.toml
[versions]
# Kotlin, Android Gradle Plugin and AndroidX entries omitted
koin = "<KOIN_VERSION>"
koin-plugin = "<KOIN_PLUGIN_VERSION>"

[libraries]
koin-android = { module = "io.insert-koin:koin-android", version.ref = "koin" }
koin-test-junit4 = { module = "io.insert-koin:koin-test-junit4", version.ref = "koin" }
koin-android-test = { module = "io.insert-koin:koin-android-test", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```

```kotlin
// app/build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.koin.compiler)
}

dependencies {
    implementation(libs.android.appcompat)
    implementation(libs.koin.android)

    testImplementation(libs.koin.test.junit4)
    testImplementation(libs.koin.android.test)
}
```

The Compiler Plugin needs Kotlin 2.3.20 or later. For current versions and the BOM, see [Gradle setup](/docs/setup/gradle). For plugin options, see [Compiler Plugin setup](/docs/setup/compiler-plugin).

## The application

The Activity asks a ViewModel for a greeting. The ViewModel uses `UserService`, which reads from `UserRepository`:

```
User -> UserRepository -> UserService -> UserViewModel -> MainActivity
```

## Let's write the user data

Start with the data class and a default list of users:

```kotlin
data class User(val name: String, val email: String)

val DEFAULT_USER = User("Alice", "alice@example.com")

val DEFAULT_USERS = listOf(
    DEFAULT_USER,
    User("Bob", "bob@example.com"),
    User("Charlie", "charlie@example.com")
)
```

These users are the data that the repository stores.

## Let's write the repository

The repository keeps users in memory and finds one by name:

```kotlin
interface UserRepository {
    fun findUserOrNull(name: String): User?
    fun addUsers(users: List<User>)
}

class UserRepositoryImpl : UserRepository {

    private val _users = arrayListOf<User>()

    override fun findUserOrNull(name: String): User? {
        return _users.firstOrNull { it.name == name }
    }

    override fun addUsers(users: List<User>) {
        _users.addAll(users)
    }
}
```

`UserRepositoryImpl` has no dependency, so Koin can create it with no extra information.

## Let's write the service

`UserService` loads the users when it is created and prepares the greeting:

```kotlin
interface UserService {
    fun getUserOrNull(name: String = DEFAULT_USER.name): User?
    fun loadUsers()
    fun prepareHelloMessage(user: User?): String
}

class UserServiceImpl(
    private val userRepository: UserRepository
) : UserService {

    init {
        loadUsers()
    }

    override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)

    override fun loadUsers() {
        userRepository.addUsers(DEFAULT_USERS)
    }

    override fun prepareHelloMessage(user: User?): String {
        return user?.let { "Hello '${user.name}' (${user.email})!" } ?: "User not found"
    }
}
```

`UserServiceImpl` depends on `UserRepository`. Koin passes it through the constructor.

## Let's declare the Koin module

A module is where you declare the components Koin creates (see [Core Concepts](/docs/intro/core-concepts)). Declare both components as singletons, bound to their interfaces:

```kotlin
import org.koin.dsl.bind
import org.koin.dsl.module
import org.koin.plugin.module.dsl.single

val appModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class
    single<UserServiceImpl>() bind UserService::class
}
```

Any component that asks for `UserService` now gets the same `UserServiceImpl` instance. `single` and `bind` are described in [Definitions](/docs/reference/koin-core/definitions).

## Let's write the ViewModel

The ViewModel turns a name into a greeting:

```kotlin
class UserViewModel(
    private val userService: UserService
) : ViewModel() {

    fun sayHello(name: String): String {
        val user = userService.getUserOrNull(name)
        val message = userService.prepareHelloMessage(user)
        return "[UserViewModel] $message"
    }
}
```

Declare it with `viewModel`:

```kotlin
import org.koin.plugin.module.dsl.viewModel

val appModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class
    single<UserServiceImpl>() bind UserService::class
    viewModel<UserViewModel>()
}
```

The Android ViewModel machinery now owns the instance: it survives configuration changes and is cleared with its owner. See [ViewModel](/docs/reference/koin-core/viewmodel) for parameters and `SavedStateHandle`.

## Let's inject the ViewModel in the Activity

Use the `by viewModel()` delegate in `MainActivity`:

```kotlin
import org.koin.androidx.viewmodel.ext.android.viewModel

class MainActivity : AppCompatActivity() {

    private val viewModel: UserViewModel by viewModel()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_simple)

        val nameInput = findViewById<EditText>(R.id.nameInput)
        val sayHelloButton = findViewById<Button>(R.id.sayHelloButton)
        val textField = findViewById<TextView>(R.id.text)

        sayHelloButton.setOnClickListener {
            val userName = nameInput.text.toString().trim().ifEmpty { "Alice" }
            textField.text = viewModel.sayHello(userName)
        }
    }
}
```

`by viewModel()` creates the ViewModel factory for you and binds the instance to the Activity lifecycle. The other delegates, such as `activityViewModel()` for Fragments, are in [Android ViewModel](/docs/reference/koin-android/viewmodel).

## Let's start Koin

Start Koin in your `Application` class, and register that class in `AndroidManifest.xml`:

```kotlin
import org.koin.android.ext.koin.androidContext
import org.koin.android.ext.koin.androidLogger
import org.koin.core.context.startKoin
import org.koin.core.logger.Level

class MainApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        startKoin {
            androidLogger(Level.DEBUG)
            androidContext(this@MainApplication)
            modules(appModule)
        }
    }
}
```

`androidContext()` makes the Android `Context` available to your definitions, and `androidLogger()` sends Koin logs to Logcat. Run the app, type a name and tap the button to see the greeting. See [Starting Koin on Android](/docs/reference/koin-android/start) for the other options.

## Next steps

- [Core Concepts](/docs/intro/core-concepts): the mental model behind modules, definitions and injection.
- [Android ViewModel](/docs/reference/koin-android/viewmodel): all ViewModel delegates, shared ViewModels and navigation graphs.
- [Android Jetpack Compose](/docs/quickstart/android-compose): the same app with a Compose UI.
- [Instrumented testing](/docs/reference/koin-android/instrumented-testing): test your Android app with Koin.
- [Tooling](/docs/tooling): IDE plugin and monitoring tools for Koin.

---

# Android Jetpack Compose

Source: https://insert-koin.io/docs/quickstart/android-compose

In this tutorial you build an Android app with a Jetpack Compose UI that greets a user picked from a list. You learn how to declare a ViewModel in a Koin module, inject it in a composable with `koinViewModel()`, and start Koin from your `Application` class. It takes about 10 minutes and needs Android Studio.

This tutorial uses the Compiler Plugin DSL. For an Android app with annotations, see [Android & Annotations](/docs/quickstart/android-annotations). To compare the styles, see [Choosing your style](/docs/intro/choosing-your-style).

## Get the code

The full sample is in [koin-getting-started/android-compose](https://github.com/InsertKoinIO/koin-getting-started/tree/main/android-compose). Clone the repository and open the `android-compose` folder in Android Studio.

## Gradle setup

The sample applies the Koin Compiler Plugin and adds `koin-android` and `koin-androidx-compose`. Versions live in a version catalog:

```toml
# gradle/libs.versions.toml
[versions]
# Kotlin, Android Gradle Plugin, AndroidX and Compose entries omitted
koin = "<KOIN_VERSION>"
koin-plugin = "<KOIN_PLUGIN_VERSION>"

[libraries]
koin-android = { module = "io.insert-koin:koin-android", version.ref = "koin" }
koin-androidx-compose = { module = "io.insert-koin:koin-androidx-compose", version.ref = "koin" }
koin-test-junit4 = { module = "io.insert-koin:koin-test-junit4", version.ref = "koin" }
koin-android-test = { module = "io.insert-koin:koin-android-test", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```

```kotlin
// app/build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.koin.compiler)
}

android {
    buildFeatures {
        compose = true
    }
}

dependencies {
    implementation(libs.koin.android)
    implementation(libs.koin.androidx.compose)

    // Compose BOM, ui, material3, activity-compose, lifecycle-viewmodel-compose
    implementation(platform(libs.compose.bom))
    ...

    testImplementation(libs.koin.test.junit4)
    testImplementation(libs.koin.android.test)
}
```

The Compiler Plugin needs Kotlin 2.3.20 or later. For current versions and the BOM, see [Gradle setup](/docs/setup/gradle). For plugin options, see [Compiler Plugin setup](/docs/setup/compiler-plugin).

## The application

The main screen asks a ViewModel for a greeting. The ViewModel uses `UserService`, which reads from `UserRepository`:

```
User -> UserRepository -> UserService -> UserViewModel -> MainScreen
```

## Let's write the user data

Start with the data class and a default list of users:

```kotlin
data class User(val name: String, val email: String)

val DEFAULT_USER = User("Alice", "alice@example.com")

val DEFAULT_USERS = listOf(
    DEFAULT_USER,
    User("Bob", "bob@example.com"),
    User("Charlie", "charlie@example.com")
)
```

These users are the data that the repository stores.

## Let's write the repository

The repository keeps users in memory and finds one by name:

```kotlin
interface UserRepository {
    fun findUserOrNull(name: String): User?
    fun addUsers(users: List<User>)
}

class UserRepositoryImpl : UserRepository {

    private val _users = arrayListOf<User>()

    override fun findUserOrNull(name: String): User? {
        return _users.firstOrNull { it.name == name }
    }

    override fun addUsers(users: List<User>) {
        _users.addAll(users)
    }
}
```

`UserRepositoryImpl` has no dependency, so Koin can create it with no extra information.

## Let's write the service

`UserService` loads the users when it is created and prepares the greeting:

```kotlin
interface UserService {
    fun getUserOrNull(name: String = DEFAULT_USER.name): User?
    fun loadUsers()
    fun prepareHelloMessage(user: User?): String
}

class UserServiceImpl(
    private val userRepository: UserRepository
) : UserService {

    init {
        loadUsers()
    }

    override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)

    override fun loadUsers() {
        userRepository.addUsers(DEFAULT_USERS)
    }

    override fun prepareHelloMessage(user: User?): String {
        return user?.let { "Hello '${user.name}' (${user.email})!" } ?: "User not found"
    }
}
```

`UserServiceImpl` depends on `UserRepository`. Koin passes it through the constructor.

## Let's write the ViewModel

The ViewModel turns a name into a greeting:

```kotlin
class UserViewModel(
    private val userService: UserService
) : ViewModel() {

    fun sayHello(name: String): String {
        val user = userService.getUserOrNull(name)
        val message = userService.prepareHelloMessage(user)
        return "[UserViewModel] $message"
    }
}
```

It receives `UserService` through its constructor, like the other components.

## Let's declare the Koin module

A module is where you declare the components Koin creates (see [Core Concepts](/docs/intro/core-concepts)). Declare the repository and the service as singletons bound to their interfaces, and the ViewModel with `viewModel`:

```kotlin
import org.koin.dsl.bind
import org.koin.dsl.module
import org.koin.plugin.module.dsl.single
import org.koin.plugin.module.dsl.viewModel

val appModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class
    single<UserServiceImpl>() bind UserService::class
    viewModel<UserViewModel>()
}
```

The Compiler Plugin reads each constructor and checks at build time that every dependency is declared. Definition types are described in [Definitions](/docs/reference/koin-core/definitions).

## Let's inject the ViewModel in a composable

Set the Compose content in a `ComponentActivity`, and get the ViewModel with `koinViewModel()` as a default parameter of `MainScreen`:

```kotlin
import org.koin.androidx.compose.koinViewModel

class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MaterialTheme {
                MainScreen()
            }
        }
    }
}

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun MainScreen(
    viewModel: UserViewModel = koinViewModel()
) {
    var nameInput by remember { mutableStateOf("") }
    var greetingMessage by remember { mutableStateOf("") }

    Scaffold(
        topBar = { TopAppBar(title = { Text("Koin Sample") }) }
    ) { paddingValues ->
        Column(
            modifier = Modifier
                .fillMaxSize()
                .padding(paddingValues)
                .padding(16.dp),
            verticalArrangement = Arrangement.spacedBy(16.dp),
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            OutlinedTextField(
                value = nameInput,
                onValueChange = { nameInput = it },
                label = { Text("Enter name") },
                modifier = Modifier.fillMaxWidth()
            )

            Button(
                onClick = {
                    val userName = nameInput.trim().ifEmpty { "Alice" }
                    greetingMessage = viewModel.sayHello(userName)
                },
                modifier = Modifier.fillMaxWidth()
            ) {
                Text("Say Hello")
            }

            if (greetingMessage.isNotEmpty()) {
                Text(
                    text = greetingMessage,
                    style = MaterialTheme.typography.bodyLarge,
                    textAlign = TextAlign.Center,
                    modifier = Modifier.fillMaxWidth()
                )
            }
        }
    }
}
```

`koinViewModel()` gets the ViewModel from Koin and ties it to the nearest `ViewModelStoreOwner`, here the Activity. As a default parameter, it lets you pass another instance in previews and tests. The other Compose APIs, such as `koinInject()`, are in [Compose ViewModel](/docs/reference/koin-compose/compose-viewmodel) and [Koin for Compose](/docs/reference/koin-compose/compose).

## Let's start Koin

Start Koin in your `Application` class, and register that class in `AndroidManifest.xml`:

```kotlin
import org.koin.android.ext.koin.androidContext
import org.koin.core.context.startKoin

class MainApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        startKoin {
            androidContext(this@MainApplication)
            modules(appModule)
        }
    }
}
```

`androidContext()` makes the Android `Context` available to your definitions. Run the app, type a name and tap the button to see the greeting. See [Starting Koin on Android](/docs/reference/koin-android/start) for the other options.

## Next steps

- [Core Concepts](/docs/intro/core-concepts): the mental model behind modules, definitions and injection.
- [Koin for Compose](/docs/reference/koin-compose/compose): `koinInject()`, `KoinApplication` and Compose setup.
- [Compose Multiplatform](/docs/quickstart/cmp): share the Compose UI and Koin modules with iOS.
- [Compose testing](/docs/reference/koin-compose/compose-testing): test composables that use Koin.
- [Tooling](/docs/tooling): IDE plugin and monitoring tools for Koin.

---

# Android & Annotations

Source: https://insert-koin.io/docs/quickstart/android-annotations

In this tutorial you build an Android app that greets a user picked from a list. You learn how to annotate classes, scan them into a module, give a ViewModel its own scoped dependency, and start Koin from a `@KoinApplication` class. It takes about 10 minutes and needs Android Studio.

This tutorial uses annotations. For the same app with the Compiler Plugin DSL, see [Android](/docs/quickstart/android) and [Android ViewModel](/docs/quickstart/android-viewmodel). To compare the styles, see [Choosing your style](/docs/intro/choosing-your-style).

## Get the code

The full sample is in [koin-getting-started/android-annotations](https://github.com/InsertKoinIO/koin-getting-started/tree/main/android-annotations). Clone the repository and open the `android-annotations` folder in Android Studio.

## Gradle setup

The sample applies the Koin Compiler Plugin and adds `koin-android` and `koin-annotations`. Versions live in a version catalog:

```toml
# gradle/libs.versions.toml
[versions]
# Kotlin, Android Gradle Plugin and AndroidX entries omitted
koin = "<KOIN_VERSION>"
koin-plugin = "<KOIN_PLUGIN_VERSION>"

[libraries]
koin-android = { module = "io.insert-koin:koin-android", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }
koin-test-junit4 = { module = "io.insert-koin:koin-test-junit4", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```

```kotlin
// app/build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.koin.compiler)
}

dependencies {
    implementation(libs.android.appcompat)
    implementation(libs.koin.android)
    implementation(libs.koin.annotations)

    testImplementation(libs.koin.test.junit4)
}
```

The Compiler Plugin processes the annotations and needs Kotlin 2.3.20 or later. `koin-annotations` shares the Koin version. Compile-time safety is on by default. For details, see [Gradle setup](/docs/setup/gradle) and [Compiler Plugin setup](/docs/setup/compiler-plugin).

## The application

The Activity asks a ViewModel for a greeting. The ViewModel uses `UserService`, which reads from `UserRepository`, and owns a `UserPresenter` scoped to its lifecycle:

```
User -> UserRepository -> UserService -> UserViewModel (+ UserPresenter) -> MainActivity
```

## Let's write the user data

Start with the data class and a default list of users:

```kotlin
data class User(val name: String, val email: String)

val DEFAULT_USER = User("Alice", "alice@example.com")

val DEFAULT_USERS = listOf(
    DEFAULT_USER,
    User("Bob", "bob@example.com"),
    User("Charlie", "charlie@example.com")
)
```

These users are the data that the repository stores.

## Let's write the repository

The repository keeps users in memory. Annotate the implementation with `@Singleton`:

```kotlin
import org.koin.core.annotation.Singleton

interface UserRepository {
    fun findUserOrNull(name: String): User?
    fun addUsers(users: List<User>)
}

@Singleton
class UserRepositoryImpl : UserRepository {

    private val _users = arrayListOf<User>()

    override fun findUserOrNull(name: String): User? {
        return _users.firstOrNull { it.name == name }
    }

    override fun addUsers(users: List<User>) {
        _users.addAll(users)
    }
}
```

Koin binds `UserRepositoryImpl` to its supertypes, so a request for `UserRepository` gets this instance. `@Singleton` is equivalent to `@Single` (see [Definitions](/docs/reference/koin-core/definitions)).

## Let's write the service

`UserService` loads the users when it is created and prepares the greeting:

```kotlin
interface UserService {
    fun getUserOrNull(name: String = DEFAULT_USER.name): User?
    fun loadUsers()
    fun prepareHelloMessage(user: User?): String
}

@Singleton
class UserServiceImpl(
    private val userRepository: UserRepository
) : UserService {

    init {
        loadUsers()
    }

    override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)

    override fun loadUsers() {
        userRepository.addUsers(DEFAULT_USERS)
    }

    override fun prepareHelloMessage(user: User?): String {
        return user?.let { "Hello '${user.name}' (${user.email})!" } ?: "User not found"
    }
}
```

The Compiler Plugin reads the constructor and passes the `UserRepository` instance for you.

## Let's write the presenter and the ViewModel

The presenter formats a greeting. Annotate it with `@ViewModelScope`, so each ViewModel gets its own instance:

```kotlin
import org.koin.core.annotation.ViewModelScope

@ViewModelScope
class UserPresenter(
    private val userService: UserService
) {

    fun sayHello(name: String): String {
        val user = userService.getUserOrNull(name)
        val message = userService.prepareHelloMessage(user)
        return "[UserPresenter] $message"
    }
}
```

The ViewModel is annotated with `@KoinViewModel`, and with `@ViewModelScope` so it can receive the scoped presenter:

```kotlin
import org.koin.core.annotation.KoinViewModel
import org.koin.core.annotation.ViewModelScope

@ViewModelScope
@KoinViewModel
class UserViewModel(
    private val userService: UserService,
    private val userPresenter: UserPresenter
) : ViewModel() {

    fun sayHello(name: String): String {
        val user = userService.getUserOrNull(name)
        val message = userService.prepareHelloMessage(user)
        return "[UserViewModel] $message"
    }
}
```

The presenter lives as long as the ViewModel and is released when the ViewModel is cleared. ViewModel scopes are explained in [ViewModel](/docs/reference/koin-core/viewmodel), and scopes in general in [Scopes](/docs/reference/koin-core/scopes).

## Let's declare the Koin module

A module groups definitions (see [Core Concepts](/docs/intro/core-concepts)). Declare a module class that scans the sample package:

```kotlin
import org.koin.core.annotation.ComponentScan
import org.koin.core.annotation.Configuration
import org.koin.core.annotation.Module

@Module
@ComponentScan("org.koin.sample")
@Configuration
class AppModule
```

`@ComponentScan` registers every annotated class in `org.koin.sample` and its subpackages. `@Configuration` makes the module discoverable by a `@KoinApplication` entry point. Both are described in [Modules](/docs/reference/koin-core/modules).

## Let's inject the ViewModel in the Activity

Use the `by viewModel()` delegate in `MainActivity`:

```kotlin
import org.koin.androidx.viewmodel.ext.android.viewModel

class MainActivity : AppCompatActivity() {

    private val viewModel: UserViewModel by viewModel()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_simple)

        val nameInput = findViewById<EditText>(R.id.nameInput)
        val sayHelloButton = findViewById<Button>(R.id.sayHelloButton)
        val textField = findViewById<TextView>(R.id.text)

        sayHelloButton.setOnClickListener {
            val userName = nameInput.text.toString().trim().ifEmpty { "Alice" }
            textField.text = viewModel.sayHello(userName)
        }
    }
}
```

`by viewModel()` creates the ViewModel factory for you and binds the instance to the Activity lifecycle. The other delegates are in [Android ViewModel](/docs/reference/koin-android/viewmodel).

## Let's start Koin

Annotate your `Application` class with `@KoinApplication` and start Koin with the typed `startKoin<T>()`. Register the class in `AndroidManifest.xml`:

```kotlin
import org.koin.android.ext.koin.androidContext
import org.koin.android.ext.koin.androidLogger
import org.koin.core.annotation.KoinApplication
import org.koin.core.annotation.KoinViewModelScopeApi
import org.koin.core.logger.Level
import org.koin.core.option.viewModelScopeFactory
import org.koin.plugin.module.dsl.startKoin

@OptIn(KoinViewModelScopeApi::class)
@KoinApplication
class MainApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        startKoin<MainApplication> {
            androidContext(this@MainApplication)
            androidLogger(level = Level.DEBUG)
            options(viewModelScopeFactory())
        }
    }
}
```

`startKoin<MainApplication>` loads every `@Configuration` module, so you don't call `modules()`. `viewModelScopeFactory()` tells Koin to create a scope for each ViewModel, which `@ViewModelScope` needs. It is an opt-in API (`@KoinViewModelScopeApi`). See [Starting Koin on Android](/docs/reference/koin-android/start) for the other options.

## Let's check the graph at build time

Build the project. The Compiler Plugin validates the full graph: a missing dependency, a qualifier mismatch or a `by viewModel()` call on an undeclared ViewModel fails the build with the file and line.

Run the app, type a name and tap the button to see the greeting. What the plugin checks is listed in [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety).

## Next steps

- [Core Concepts](/docs/intro/core-concepts): the mental model behind modules, definitions and injection.
- [Android scopes](/docs/reference/koin-android/scope): Activity, Fragment and ViewModel scopes on Android.
- [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): every annotation and its parameters.
- [Instrumented testing](/docs/reference/koin-android/instrumented-testing): test your Android app with Koin.
- [Tooling](/docs/tooling): IDE plugin and monitoring tools for Koin.

---

# Compose Multiplatform

Source: https://insert-koin.io/docs/quickstart/cmp

In this tutorial you build a Compose Multiplatform app for Android and iOS that lists art objects from The Metropolitan Museum of Art and shows their details. You learn how to share Koin modules in `commonMain`, provide platform-specific definitions, inject ViewModels in composables, and start Koin on both platforms. It takes about 20 minutes and needs Android Studio, plus Xcode for iOS.

This tutorial uses the Compiler Plugin DSL. For the same app with annotations, see [Compose Multiplatform & Annotations](/docs/quickstart/compose-multiplatform-annotations). To compare the styles, see [Choosing your style](/docs/intro/choosing-your-style).

## Get the code

The full sample is in [koin-getting-started/compose](https://github.com/InsertKoinIO/koin-getting-started/tree/main/compose). Clone the repository and open the `compose` folder in Android Studio. The shared code is in the `composeApp` Gradle module, and the iOS app is in `iosApp`.

## Gradle setup

The sample applies the Koin Compiler Plugin and adds `koin-core` and `koin-compose-viewmodel-navigation` to `commonMain`. Versions live in a version catalog:

```toml
# gradle/libs.versions.toml
[versions]
# Kotlin, Compose Multiplatform, Ktor, navigation and Coil entries omitted
koin = "<KOIN_VERSION>"
koin-plugin = "<KOIN_PLUGIN_VERSION>"

[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-compose-viewmodel-navigation = { module = "io.insert-koin:koin-compose-viewmodel-navigation", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```

```kotlin
// composeApp/build.gradle.kts
plugins {
    alias(libs.plugins.kotlin.multiplatform)
    alias(libs.plugins.android.application)
    alias(libs.plugins.compose.multiplatform)
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.koin.compiler)
    alias(libs.plugins.kotlin.serialization)
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.koin.core)
            implementation(libs.koin.compose.viewmodel.navigation)
            ...
        }
    }
}
```

The Compiler Plugin needs Kotlin 2.3.20 or later and runs on every target. For current versions, see [Gradle setup](/docs/setup/gradle). For the multiplatform project layout, see [KMP setup](/docs/reference/koin-core/kmp-setup).

## The application

The app fetches art objects from a remote API, caches them in memory, and shows them on a list screen and a detail screen:

```
MuseumApi -> MuseumStorage -> MuseumRepository -> ListViewModel / DetailViewModel -> Compose UI
```

It uses Ktor for HTTP, Kotlin Flow for data streams and Navigation Compose for routing. All the code in this tutorial is in `commonMain` unless the heading says otherwise.

## Let's write the data layer

The `MuseumObject` data class maps the API response:

```kotlin
@Serializable
data class MuseumObject(
    val objectID: Int,
    val title: String,
    val artistDisplayName: String,
    val medium: String,
    val dimensions: String,
    val objectURL: String,
    val objectDate: String,
    val primaryImage: String,
    val primaryImageSmall: String,
    val repository: String,
    val department: String,
    val creditLine: String,
)
```

`MuseumApi` fetches the list with a Ktor `HttpClient`:

```kotlin
interface MuseumApi {
    suspend fun getData(): List<MuseumObject>
}

class KtorMuseumApi(private val client: HttpClient) : MuseumApi {
    companion object {
        private const val API_URL =
            "https://raw.githubusercontent.com/Kotlin/KMP-App-Template/main/list.json"
    }

    override suspend fun getData(): List<MuseumObject> {
        return try {
            client.get(API_URL).body()
        } catch (e: Exception) {
            if (e is CancellationException) throw e
            e.printStackTrace()
            emptyList()
        }
    }
}
```

`MuseumStorage` caches the objects in a `MutableStateFlow`:

```kotlin
interface MuseumStorage {
    suspend fun saveObjects(newObjects: List<MuseumObject>)
    fun getObjectById(objectId: Int): Flow<MuseumObject?>
    fun getObjects(): Flow<List<MuseumObject>>
}

class InMemoryMuseumStorage : MuseumStorage {
    private val storedObjects = MutableStateFlow(emptyList<MuseumObject>())

    override suspend fun saveObjects(newObjects: List<MuseumObject>) {
        storedObjects.value = newObjects
    }

    override fun getObjectById(objectId: Int): Flow<MuseumObject?> {
        return storedObjects.map { objects ->
            objects.find { it.objectID == objectId }
        }
    }

    override fun getObjects(): Flow<List<MuseumObject>> = storedObjects
}
```

`MuseumRepository` refreshes the storage from the API when it is created:

```kotlin
class MuseumRepository(
    private val museumApi: MuseumApi,
    private val museumStorage: MuseumStorage,
) {
    private val scope = CoroutineScope(SupervisorJob())

    init {
        initialize()
    }

    fun initialize() {
        scope.launch {
            refresh()
        }
    }

    suspend fun refresh() {
        museumStorage.saveObjects(museumApi.getData())
    }

    fun getObjects(): Flow<List<MuseumObject>> = museumStorage.getObjects()

    fun getObjectById(objectId: Int): Flow<MuseumObject?> = museumStorage.getObjectById(objectId)
}
```

Each class takes its dependencies in its constructor, so Koin can wire all of them.

## Let's declare the data module

A module is where you declare the components Koin creates (see [Core Concepts](/docs/intro/core-concepts)). Declare the data layer in `dataModule`:

```kotlin
import org.koin.core.module.dsl.createdAtStart
import org.koin.core.module.dsl.withOptions
import org.koin.dsl.bind
import org.koin.dsl.module
import org.koin.plugin.module.dsl.create
import org.koin.plugin.module.dsl.single

val dataModule = module {
    single { create(::buildClient) }
    single<KtorMuseumApi>() bind MuseumApi::class
    single<InMemoryMuseumStorage>() bind MuseumStorage::class
    single<MuseumRepository>() withOptions { createdAtStart() }
}

private fun buildClient(): HttpClient {
    val json = Json { ignoreUnknownKeys = true }
    return HttpClient {
        install(ContentNegotiation) {
            json(json, contentType = ContentType.Any)
        }
    }
}
```

`create(::buildClient)` lets Koin call a builder function for a class you don't own, here `HttpClient`. `createdAtStart()` creates `MuseumRepository` when Koin starts, so the data fetch begins right away. Both are described in [Definitions](/docs/reference/koin-core/definitions).

## Let's write the ViewModels

The list screen and the detail screen each get a ViewModel:

```kotlin
class ListViewModel(museumRepository: MuseumRepository) : ViewModel() {
    val objects: StateFlow<List<MuseumObject>> =
        museumRepository.getObjects()
            .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
}

class DetailViewModel(private val museumRepository: MuseumRepository) : ViewModel() {
    fun getObject(objectId: Int): Flow<MuseumObject?> =
        museumRepository.getObjectById(objectId)
}
```

Declare them in `viewModelModule`:

```kotlin
import org.koin.plugin.module.dsl.viewModel

val viewModelModule = module {
    viewModel<ListViewModel>()
    viewModel<DetailViewModel>()
}
```

Koin creates each ViewModel through the multiplatform ViewModel API, so the same declaration works on Android and iOS. See [ViewModel](/docs/reference/koin-core/viewmodel).

## Let's add platform-specific definitions

The sample shows two ways to provide a different implementation per platform. The first is an `expect` class, declared once in a shared module:

```kotlin
// commonMain
expect class NativeComponent() {
    fun getInfo(): String
}

val nativeComponentModule = module {
    single<NativeComponent>()
}
```

```kotlin
// androidMain
actual class NativeComponent actual constructor() {
    actual fun getInfo(): String = "Android OS"
}
```

```kotlin
// nativeMain
actual class NativeComponent actual constructor() {
    actual fun getInfo(): String = "iOS"
}
```

The second is an `expect` module function. Each platform returns its own module, binding its implementation of a shared interface:

```kotlin
// commonMain
interface PlatformComponent {
    fun getInfo(): String
}

expect fun platformModule(): Module
```

```kotlin
// androidMain
class AndroidComponent() : PlatformComponent {
    override fun getInfo(): String = "Android OS"
}

actual fun platformModule(): Module = module {
    single<AndroidComponent>() bind PlatformComponent::class
}
```

```kotlin
// iosMain
class IOSComponent() : PlatformComponent {
    override fun getInfo(): String = "iOS OS"
}

actual fun platformModule(): Module = module {
    single<IOSComponent>() bind PlatformComponent::class
}
```

Shared code asks for `NativeComponent` or `PlatformComponent` and gets the right implementation on each platform. These patterns are covered in [KMP shared modules](/docs/reference/koin-core/kmp-shared-modules).

## Let's assemble the modules

Gather all modules in `appModule` with `includes()`:

```kotlin
val appModule = module {
    includes(dataModule, viewModelModule, nativeComponentModule, platformModule())
}
```

You now load a single module at start, and it brings the others. See [Modules](/docs/reference/koin-core/modules).

## Let's inject the ViewModels in Compose

Each screen gets its ViewModel with `koinViewModel()` as a default parameter:

```kotlin
import org.koin.compose.viewmodel.koinViewModel

@Composable
fun ListScreen(
    viewModel: ListViewModel = koinViewModel(),
    navigateToDetails: (objectId: Int) -> Unit
) {
    val objects by viewModel.objects.collectAsStateWithLifecycle()
    ...
}

@Composable
fun DetailScreen(
    objectId: Int,
    viewModel: DetailViewModel = koinViewModel(),
    navigateBack: () -> Unit,
) {
    val obj by viewModel.getObject(objectId).collectAsStateWithLifecycle(initialValue = null)
    ...
}
```

The `App` composable sets up navigation between the two screens:

```kotlin
@Serializable
object ListDestination

@Serializable
data class DetailDestination(val objectId: Int)

@Composable
fun App() {
    MaterialTheme(
        colorScheme = if (isSystemInDarkTheme()) darkColorScheme() else lightColorScheme()
    ) {
        Surface {
            val navController: NavHostController = rememberNavController()
            NavHost(navController = navController, startDestination = ListDestination) {
                composable<ListDestination> {
                    ListScreen(navigateToDetails = { objectId ->
                        navController.navigate(DetailDestination(objectId))
                    })
                }
                composable<DetailDestination> { backStackEntry ->
                    DetailScreen(
                        objectId = backStackEntry.toRoute<DetailDestination>().objectId,
                        navigateBack = { navController.popBackStack() }
                    )
                }
            }
        }
    }
}
```

Inside a `NavHost` destination, `koinViewModel()` ties the ViewModel to that navigation entry, so each screen keeps its own instance. See [Compose ViewModel](/docs/reference/koin-compose/compose-viewmodel).

## Let's start Koin

Write a shared `initKoin()` function that both platforms call. It accepts an optional configuration for platform-specific setup:

```kotlin
import org.koin.core.context.startKoin
import org.koin.dsl.KoinAppDeclaration
import org.koin.dsl.includes

fun initKoin(configuration: KoinAppDeclaration? = null) {
    startKoin {
        includes(configuration)
        modules(appModule)
        printLogger(Level.DEBUG)
    }
}
```

On Android, call it from your `Application` class and pass the Android context:

```kotlin
// androidMain
class MuseumApp : Application() {
    override fun onCreate() {
        super.onCreate()
        initKoin {
            androidContext(this@MuseumApp)
        }
    }
}
```

On iOS, call it from the SwiftUI app entry point. Kotlin exports `initKoin()` as `doInitKoin()`:

```swift
// iosApp
@main
struct iOSApp: App {
    init() {
        KoinKt.doInitKoin()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

The iOS view controller hosts the same `App` composable:

```kotlin
// iosMain
fun MainViewController() = ComposeUIViewController { App() }
```

Run the Android app from Android Studio, or the iOS app from Xcode, and the list of art objects appears. See [Starting Koin](/docs/reference/koin-core/starting-koin) for the other start options.

## Next steps

- [Core Concepts](/docs/intro/core-concepts): the mental model behind modules, definitions and injection.
- [KMP setup](/docs/reference/koin-core/kmp-setup): project layout and Koin dependencies for Kotlin Multiplatform.
- [Koin for Compose](/docs/reference/koin-compose/compose): `KoinApplication`, `koinInject()` and Compose setup.
- [Compose testing](/docs/reference/koin-compose/compose-testing): test composables that use Koin.
- [Tooling](/docs/tooling): IDE plugin and monitoring tools for Koin.

---

# Compose Multiplatform & Annotations

Source: https://insert-koin.io/docs/quickstart/compose-multiplatform-annotations

In this tutorial you build a Compose Multiplatform app for Android and iOS that lists art objects from The Metropolitan Museum of Art and shows their details. You learn how to annotate classes across two Gradle modules, provide platform-specific definitions, inject ViewModels in composables, and start Koin from your root composable. It takes about 20 minutes and needs Android Studio, plus Xcode for iOS.

This tutorial uses annotations. For the same app with the Compiler Plugin DSL, see [Compose Multiplatform](/docs/quickstart/cmp). To compare the styles, see [Choosing your style](/docs/intro/choosing-your-style).

## Get the code

The full sample is in [koin-getting-started/compose-annotations](https://github.com/InsertKoinIO/koin-getting-started/tree/main/compose-annotations). Clone the repository and open the `compose-annotations` folder in Android Studio. It has two Gradle modules: `data` for the data layer and `composeApp` for the UI. The iOS app is in `iosApp`.

## Gradle setup

Both Gradle modules apply the Koin Compiler Plugin. Versions live in a version catalog:

```toml
# gradle/libs.versions.toml
[versions]
# Kotlin, Compose Multiplatform, Ktor, navigation and Coil entries omitted
koin = "<KOIN_VERSION>"
koin-plugin = "<KOIN_PLUGIN_VERSION>"

[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }
koin-compose-viewmodel = { module = "io.insert-koin:koin-compose-viewmodel", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```

```kotlin
// data/build.gradle.kts
plugins {
    alias(libs.plugins.kotlin.multiplatform)
    alias(libs.plugins.android.library)
    alias(libs.plugins.koin.compiler)
    alias(libs.plugins.kotlin.serialization)
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.koin.core)
            api(libs.koin.annotations)
            ...
        }
    }
}
```

```kotlin
// composeApp/build.gradle.kts
plugins {
    alias(libs.plugins.kotlin.multiplatform)
    alias(libs.plugins.android.application)
    alias(libs.plugins.compose.multiplatform)
    alias(libs.plugins.koin.compiler)
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.kotlin.serialization)
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            api(project(":data"))
            implementation(libs.koin.core)
            implementation(libs.koin.compose.viewmodel)
            implementation(libs.koin.annotations)
            ...
        }
    }
}
```

The Compiler Plugin processes the annotations on every target, with no per-target setup. It needs Kotlin 2.3.20 or later, and `koin-annotations` shares the Koin version. For details, see [Gradle setup](/docs/setup/gradle) and [Compiler Plugin setup](/docs/setup/compiler-plugin).

## The application

The app fetches art objects from a remote API, caches them in memory, and shows them on a list screen and a detail screen:

```
MuseumApi -> MuseumStorage -> MuseumRepository -> ListViewModel / DetailViewModel -> Compose UI
```

It uses Ktor for HTTP, Kotlin Flow for data streams and Navigation Compose for routing. Code is in `commonMain` unless the heading or a comment says otherwise.

## Let's write the data layer

This code is in the `data` Gradle module. The `MuseumObject` data class maps the API response:

```kotlin
@Serializable
data class MuseumObject(
    val objectID: Int,
    val title: String,
    val artistDisplayName: String,
    val medium: String,
    val dimensions: String,
    val objectURL: String,
    val objectDate: String,
    val primaryImage: String,
    val primaryImageSmall: String,
    val repository: String,
    val department: String,
    val creditLine: String,
)
```

`KtorMuseumApi` fetches the list with a Ktor `HttpClient`. Annotate it with `@Singleton`:

```kotlin
import org.koin.core.annotation.Singleton

interface MuseumApi {
    suspend fun getData(): List<MuseumObject>
}

@Singleton
class KtorMuseumApi(private val client: HttpClient) : MuseumApi {
    companion object {
        private const val API_URL =
            "https://raw.githubusercontent.com/Kotlin/KMP-App-Template/main/list.json"
    }

    override suspend fun getData(): List<MuseumObject> {
        return try {
            client.get(API_URL).body()
        } catch (e: Exception) {
            if (e is CancellationException) throw e
            e.printStackTrace()
            emptyList()
        }
    }
}
```

`InMemoryMuseumStorage` caches the objects in a `MutableStateFlow`:

```kotlin
interface MuseumStorage {
    suspend fun saveObjects(newObjects: List<MuseumObject>)
    fun getObjectById(objectId: Int): Flow<MuseumObject?>
    fun getObjects(): Flow<List<MuseumObject>>
}

@Singleton
class InMemoryMuseumStorage : MuseumStorage {
    private val storedObjects = MutableStateFlow(emptyList<MuseumObject>())

    override suspend fun saveObjects(newObjects: List<MuseumObject>) {
        storedObjects.value = newObjects
    }

    override fun getObjectById(objectId: Int): Flow<MuseumObject?> {
        return storedObjects.map { objects ->
            objects.find { it.objectID == objectId }
        }
    }

    override fun getObjects(): Flow<List<MuseumObject>> = storedObjects
}
```

`MuseumRepository` refreshes the storage from the API when it is created:

```kotlin
@Singleton
class MuseumRepository(
    private val museumApi: MuseumApi,
    private val museumStorage: MuseumStorage,
) {
    private val scope = CoroutineScope(SupervisorJob())

    init {
        initialize()
    }

    fun initialize() {
        scope.launch {
            refresh()
        }
    }

    suspend fun refresh() {
        museumStorage.saveObjects(museumApi.getData())
    }

    fun getObjects(): Flow<List<MuseumObject>> = museumStorage.getObjects()

    fun getObjectById(objectId: Int): Flow<MuseumObject?> = museumStorage.getObjectById(objectId)
}
```

Koin binds each class to its supertypes, so `KtorMuseumApi` answers requests for `MuseumApi`. See [Definitions](/docs/reference/koin-core/definitions).

## Let's declare the data module

`HttpClient` is a class you don't own, so provide it from a function in the module class:

```kotlin
import org.koin.core.annotation.ComponentScan
import org.koin.core.annotation.Configuration
import org.koin.core.annotation.Module
import org.koin.core.annotation.Singleton

@Module
@Configuration
@ComponentScan("com.jetbrains.kmpapp.data")
class DataModule {

    @Singleton
    fun providesHttpClient(): HttpClient {
        val json = Json { ignoreUnknownKeys = true }
        return HttpClient {
            install(ContentNegotiation) {
                json(json, contentType = ContentType.Any)
            }
        }
    }
}
```

`@ComponentScan` registers the annotated classes of the data package. `@Configuration` makes `DataModule` discoverable by the app entry point, even though it lives in another Gradle module. See [Modules](/docs/reference/koin-core/modules).

## Let's write the ViewModels

This code and the rest of the tutorial are in the `composeApp` Gradle module. Annotate each ViewModel with `@KoinViewModel`:

```kotlin
import org.koin.core.annotation.KoinViewModel

@KoinViewModel
class ListViewModel(museumRepository: MuseumRepository) : ViewModel() {
    val objects: StateFlow<List<MuseumObject>> =
        museumRepository.getObjects()
            .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
}

@KoinViewModel
class DetailViewModel(private val museumRepository: MuseumRepository) : ViewModel() {
    fun getObject(objectId: Int): Flow<MuseumObject?> =
        museumRepository.getObjectById(objectId)
}
```

Scan them with a module class in the `screens` package:

```kotlin
@ComponentScan
@Module
class ViewModelModule
```

`@ComponentScan` with no argument scans the package of the module class and its subpackages. See [ViewModel](/docs/reference/koin-core/viewmodel).

## Let's add platform-specific definitions

The sample shows two ways to provide a different implementation per platform. The first is an annotated `expect` class, scanned by a shared module:

```kotlin
// commonMain
@Singleton
expect class NativeComponent() {
    fun getInfo(): String
}

@Module
@ComponentScan
class NativeComponentModule
```

```kotlin
// androidMain
@Singleton
actual class NativeComponent actual constructor() {
    actual fun getInfo(): String = "Android NativeComponent"
}
```

```kotlin
// nativeMain
@Singleton
actual class NativeComponent actual constructor() {
    actual fun getInfo(): String = "iOS NativeComponent"
}
```

The second is an `expect` module class. Each platform's `actual` module scans its own implementation of a shared interface:

```kotlin
// commonMain
interface PlatformComponent {
    fun getInfo(): String
}

@Module
expect class PlatformComponentModule
```

```kotlin
// androidMain
@Module
@ComponentScan
actual class PlatformComponentModule

@Singleton
class AndroidPlatformComponent : PlatformComponent {
    override fun getInfo(): String = "Android PlatformComponent"
}
```

```kotlin
// iosMain
@Module
@ComponentScan
actual class PlatformComponentModule

@Singleton
class IOSPlatformComponent : PlatformComponent {
    override fun getInfo(): String = "iOS PlatformComponent"
}
```

Platform classes can also take platform dependencies. On Android, `AndroidContextWrapper` receives the Android `Context` from Koin:

```kotlin
// commonMain
interface ContextWrapper {
    fun getContextInfo(): String
}

@Singleton
class NativeContextComponent(val ctx: ContextWrapper) {
    fun getInfo(): String = "NativeContextComponent with ctx: ${ctx.getContextInfo()}"
}
```

```kotlin
// androidMain
@Singleton
class AndroidContextWrapper(val context: Context) : ContextWrapper {
    override fun getContextInfo(): String = "Android Context: $context"
}
```

```kotlin
// nativeMain
@Singleton
class IOSContextWrapper : ContextWrapper {
    override fun getContextInfo(): String = "iOS Context"
}
```

Shared code asks for the interface and gets the right implementation on each platform. These patterns are covered in [KMP shared modules](/docs/reference/koin-core/kmp-shared-modules).

## Let's assemble the modules

Declare the app module with its includes, and a `@KoinApplication` object as the entry point:

```kotlin
import org.koin.core.annotation.Configuration
import org.koin.core.annotation.KoinApplication
import org.koin.core.annotation.Module

@Module(includes = [ViewModelModule::class, NativeComponentModule::class, PlatformComponentModule::class])
@Configuration
class AppModule

@KoinApplication
object KoinApp
```

`KoinApp` collects every `@Configuration` module: `AppModule` with its includes, and `DataModule` from the `data` Gradle module. The Compiler Plugin validates the full graph at build time.

## Let's start Koin and inject the ViewModels

Start Koin from the root composable with `KoinApplication` and `koinConfiguration<KoinApp>()`:

```kotlin
import org.koin.compose.KoinApplication
import org.koin.plugin.module.dsl.koinConfiguration

@Serializable
object ListDestination

@Serializable
data class DetailDestination(val objectId: Int)

@Composable
fun App() {
    KoinApplication(configuration = koinConfiguration<KoinApp>()) {
        MaterialTheme(
            colorScheme = if (isSystemInDarkTheme()) darkColorScheme() else lightColorScheme()
        ) {
            Surface {
                val navController: NavHostController = rememberNavController()
                NavHost(navController = navController, startDestination = ListDestination) {
                    composable<ListDestination> {
                        ListScreen(navigateToDetails = { objectId ->
                            navController.navigate(DetailDestination(objectId))
                        })
                    }
                    composable<DetailDestination> { backStackEntry ->
                        DetailScreen(
                            objectId = backStackEntry.toRoute<DetailDestination>().objectId,
                            navigateBack = { navController.popBackStack() }
                        )
                    }
                }
            }
        }
    }
}
```

Each screen gets its ViewModel with `koinViewModel()`:

```kotlin
import org.koin.compose.viewmodel.koinViewModel

@Composable
fun ListScreen(navigateToDetails: (objectId: Int) -> Unit) {
    val viewModel = koinViewModel<ListViewModel>()
    val objects by viewModel.objects.collectAsStateWithLifecycle()
    ...
}

@Composable
fun DetailScreen(objectId: Int, navigateBack: () -> Unit) {
    val viewModel = koinViewModel<DetailViewModel>()
    val obj by viewModel.getObject(objectId).collectAsStateWithLifecycle(initialValue = null)
    ...
}
```

`KoinApplication` starts Koin once for the whole app. On Android it also sets the Android context and logger, which is how `AndroidContextWrapper` gets its `Context`. Both platforms host the same `App` composable, so there is no separate start code in `Application` or in the iOS app:

```kotlin
// iosMain
fun MainViewController() = ComposeUIViewController { App() }
```

Run the Android app from Android Studio, or the iOS app from Xcode, and the list of art objects appears. Outside Compose, use `startKoin<KoinApp>()` from `org.koin.plugin.module.dsl` instead. See [Koin for Compose](/docs/reference/koin-compose/compose) and [Compose ViewModel](/docs/reference/koin-compose/compose-viewmodel).

## Next steps

- [Core Concepts](/docs/intro/core-concepts): the mental model behind modules, definitions and injection.
- [KMP shared modules](/docs/reference/koin-core/kmp-shared-modules): share and split Koin modules across platforms.
- [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): every annotation and its parameters.
- [Compose testing](/docs/reference/koin-compose/compose-testing): test composables that use Koin.
- [Tooling](/docs/tooling): IDE plugin and monitoring tools for Koin.

---

# Ktor

Source: https://insert-koin.io/docs/quickstart/ktor

In this tutorial you build a Ktor web app with a `/hello` endpoint that greets a user picked from a list. You learn how to declare a Koin module, install Koin as a Ktor plugin, and inject a service in your application. It takes about 10 minutes and needs a JDK 17 and Gradle.

This tutorial uses the Compiler Plugin DSL. For the same app with annotations, see [Ktor & Annotations](/docs/quickstart/ktor-annotations). To compare the styles, see [Choosing your style](/docs/intro/choosing-your-style).

## Get the code

The full sample is in [koin-getting-started/ktor](https://github.com/InsertKoinIO/koin-getting-started/tree/main/ktor). Clone the repository and run it from the `ktor` folder:

```bash
./gradlew run
```

## Gradle setup

The sample applies the Koin Compiler Plugin and adds `koin-ktor` and `koin-logger-slf4j`. Versions live in a version catalog:

```toml
# gradle/libs.versions.toml
[versions]
# Kotlin, Ktor and Logback entries omitted
koin = "<KOIN_VERSION>"
koin-plugin = "<KOIN_PLUGIN_VERSION>"

[libraries]
koin-ktor = { module = "io.insert-koin:koin-ktor", version.ref = "koin" }
koin-logger-slf4j = { module = "io.insert-koin:koin-logger-slf4j", version.ref = "koin" }
koin-test = { module = "io.insert-koin:koin-test", version.ref = "koin" }
koin-test-junit4 = { module = "io.insert-koin:koin-test-junit4", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```

```kotlin
// app/build.gradle.kts
plugins {
    alias(libs.plugins.kotlin.jvm)
    alias(libs.plugins.koin.compiler)
    application
}

dependencies {
    implementation(libs.ktor.server)
    implementation(libs.logback)
    implementation(libs.koin.ktor)
    implementation(libs.koin.logger.slf4j)

    testImplementation(libs.ktor.test)
    testImplementation(libs.koin.test)
    testImplementation(libs.koin.test.junit4)
}
```

The Compiler Plugin needs Kotlin 2.3.20 or later. For current versions and the BOM, see [Gradle setup](/docs/setup/gradle). For plugin options, see [Compiler Plugin setup](/docs/setup/compiler-plugin).

## The application

The `/hello` route asks `UserService` for a user, and `UserService` reads from `UserRepository`:

```
User -> UserRepository -> UserService -> /hello route
```

## Let's write the user data

Start with the data class and a default list of users:

```kotlin
data class User(val name: String, val email: String)

val DEFAULT_USER = User("Alice", "alice@example.com")

val DEFAULT_USERS = listOf(
    DEFAULT_USER,
    User("Bob", "bob@example.com"),
    User("Charlie", "charlie@example.com")
)
```

These users are the data that the repository stores.

## Let's write the repository

The repository keeps users in memory and finds one by name:

```kotlin
interface UserRepository {
    fun findUserOrNull(name: String): User?
    fun addUsers(users: List<User>)
}

class UserRepositoryImpl : UserRepository {

    private val _users = arrayListOf<User>()

    override fun findUserOrNull(name: String): User? {
        return _users.firstOrNull { it.name == name }
    }

    override fun addUsers(users: List<User>) {
        _users.addAll(users)
    }
}
```

`UserRepositoryImpl` has no dependency, so Koin can create it with no extra information.

## Let's write the service

`UserService` loads the users and prepares the greeting:

```kotlin
interface UserService {
    fun getUserOrNull(name: String = DEFAULT_USER.name): User?
    fun loadUsers()
    fun prepareHelloMessage(user: User?): String
}

class UserServiceImpl(
    private val userRepository: UserRepository
) : UserService {

    override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)

    override fun loadUsers() {
        userRepository.addUsers(DEFAULT_USERS)
    }

    override fun prepareHelloMessage(user: User?): String {
        return user?.let { "Hello '${user.name}' (${user.email})!" } ?: "User not found"
    }
}
```

`UserServiceImpl` depends on `UserRepository`. Koin passes it through the constructor.

## Let's declare the Koin module

A module is where you declare the components Koin creates (see [Core Concepts](/docs/intro/core-concepts)). Declare both components as singletons, bound to their interfaces:

```kotlin
import org.koin.dsl.bind
import org.koin.dsl.module
import org.koin.plugin.module.dsl.single

val appModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class
    single<UserServiceImpl>() bind UserService::class
}
```

Any component that asks for `UserService` now gets the same `UserServiceImpl` instance. `single` and `bind` are described in [Definitions](/docs/reference/koin-core/definitions).

## Let's install Koin and write the route

Install the `Koin` plugin in your Ktor application with your module, then inject `UserService` and use it in the `/hello` route:

```kotlin
import org.koin.ktor.ext.inject
import org.koin.ktor.plugin.Koin

fun Application.main() {
    install(Koin) {
        modules(appModule)
    }

    val service by inject<UserService>()
    service.loadUsers()

    routing {
        get("/hello") {
            val userName = call.queryParameters["name"] ?: "Alice"
            val user = service.getUserOrNull(userName)
            val message = service.prepareHelloMessage(user)
            call.respondText(message)
        }
    }
}
```

`install(Koin)` starts Koin with the Ktor application, and `inject()` is available on `Application`, `Route` and `ApplicationCall`. To send Koin logs to SLF4J, add `slf4jLogger()` inside `install(Koin)`. See [Koin for Ktor](/docs/reference/koin-ktor/ktor) for the Ktor-specific APIs.

## Let's start the server

Start an embedded Netty server that runs your application module:

```kotlin
fun main(args: Array<String>) {
    embeddedServer(Netty, port = 8080) {
        main()
    }.start(wait = true)
}
```

Run `./gradlew run`, then open these URLs:

- `http://localhost:8080/hello`: greets Alice, the default user.
- `http://localhost:8080/hello?name=Bob`: greets Bob.

## Next steps

- [Core Concepts](/docs/intro/core-concepts): the mental model behind modules, definitions and injection.
- [Koin for Ktor](/docs/reference/koin-ktor/ktor): install options, injection in routes and Ktor events.
- [Request Scopes](/docs/reference/koin-ktor/ktor-scopes): instances that live for one HTTP request.
- [Ktor testing](/docs/reference/koin-ktor/ktor-testing): test your routes with `testApplication` and Koin.
- [Tooling](/docs/tooling): IDE plugin and monitoring tools for Koin.

---

# Ktor & Annotations

Source: https://insert-koin.io/docs/quickstart/ktor-annotations

In this tutorial you build a Ktor web app with a `/hello` endpoint that greets a user picked from a list. You learn how to annotate classes, scan them into a module, and load them in the Koin Ktor plugin from a `@KoinApplication` object. It takes about 10 minutes and needs a JDK 17 and Gradle.

This tutorial uses annotations. For the same app with the Compiler Plugin DSL, see [Ktor](/docs/quickstart/ktor). To compare the styles, see [Choosing your style](/docs/intro/choosing-your-style).

## Get the code

The full sample is in [koin-getting-started/ktor-annotations](https://github.com/InsertKoinIO/koin-getting-started/tree/main/ktor-annotations). Clone the repository and run the `app` module from the `ktor-annotations` folder.

## Gradle setup

The sample applies the Koin Compiler Plugin and adds `koin-ktor`, `koin-annotations` and `koin-logger-slf4j`. Versions live in a version catalog:

```toml
# gradle/libs.versions.toml
[versions]
# Kotlin, Ktor and Logback entries omitted
koin = "<KOIN_VERSION>"
koin-plugin = "<KOIN_PLUGIN_VERSION>"

[libraries]
koin-ktor = { module = "io.insert-koin:koin-ktor", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }
koin-logger-slf4j = { module = "io.insert-koin:koin-logger-slf4j", version.ref = "koin" }
koin-test = { module = "io.insert-koin:koin-test", version.ref = "koin" }
koin-test-junit4 = { module = "io.insert-koin:koin-test-junit4", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```

```kotlin
// app/build.gradle.kts
plugins {
    alias(libs.plugins.kotlin.jvm)
    alias(libs.plugins.koin.compiler)
    application
}

dependencies {
    implementation(libs.ktor.server)
    implementation(libs.logback)
    implementation(libs.koin.ktor)
    implementation(libs.koin.annotations)
    implementation(libs.koin.logger.slf4j)

    testImplementation(libs.ktor.test)
    testImplementation(libs.koin.test)
    testImplementation(libs.koin.test.junit4)
}
```

The Compiler Plugin processes the annotations and needs Kotlin 2.3.20 or later. `koin-annotations` shares the Koin version. For details, see [Gradle setup](/docs/setup/gradle) and [Compiler Plugin setup](/docs/setup/compiler-plugin).

## The application

The `/hello` route asks `UserService` for a user, and `UserService` reads from `UserRepository`:

```
User -> UserRepository -> UserService -> /hello route
```

## Let's write the user data

Start with the data class and a default list of users:

```kotlin
data class User(val name: String, val email: String)

val DEFAULT_USER = User("Alice", "alice@example.com")

val DEFAULT_USERS = listOf(
    DEFAULT_USER,
    User("Bob", "bob@example.com"),
    User("Charlie", "charlie@example.com")
)
```

These users are the data that the repository stores.

## Let's write the repository

The repository keeps users in memory. Annotate the implementation with `@Singleton`:

```kotlin
import org.koin.core.annotation.Singleton

interface UserRepository {
    fun findUserOrNull(name: String): User?
    fun addUsers(users: List<User>)
}

@Singleton
class UserRepositoryImpl : UserRepository {

    private val _users = arrayListOf<User>()

    override fun findUserOrNull(name: String): User? {
        return _users.firstOrNull { it.name == name }
    }

    override fun addUsers(users: List<User>) {
        _users.addAll(users)
    }
}
```

Koin binds `UserRepositoryImpl` to its supertypes, so a request for `UserRepository` gets this instance. `@Singleton` comes from `org.koin.core.annotation` and is equivalent to `@Single` (see [Definitions](/docs/reference/koin-core/definitions)).

## Let's write the service

`UserService` loads the users and prepares the greeting. It is a `@Singleton` too:

```kotlin
interface UserService {
    fun getUserOrNull(name: String = DEFAULT_USER.name): User?
    fun loadUsers()
    fun prepareHelloMessage(user: User?): String
}

@Singleton
class UserServiceImpl(
    private val userRepository: UserRepository
) : UserService {

    override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)

    override fun loadUsers() {
        userRepository.addUsers(DEFAULT_USERS)
    }

    override fun prepareHelloMessage(user: User?): String {
        return user?.let { "Hello '${user.name}' (${user.email})!" } ?: "User not found"
    }
}
```

The Compiler Plugin reads the constructor and passes the `UserRepository` instance for you.

## Let's declare the Koin module

A module groups definitions (see [Core Concepts](/docs/intro/core-concepts)). Declare a module class that scans the sample package:

```kotlin
import org.koin.core.annotation.ComponentScan
import org.koin.core.annotation.Configuration
import org.koin.core.annotation.Module

@Module
@ComponentScan("org.koin.sample")
@Configuration
class AppModule
```

`@ComponentScan` registers every annotated class in `org.koin.sample` and its subpackages. `@Configuration` makes the module discoverable by a `@KoinApplication` entry point. Both are described in [Modules](/docs/reference/koin-core/modules).

## Let's install Koin and write the route

Declare a `@KoinApplication` object. Install the `Koin` plugin and load the configuration with `withConfiguration<T>()`, then inject `UserService` in the `/hello` route:

```kotlin
import org.koin.core.annotation.KoinApplication
import org.koin.ktor.ext.inject
import org.koin.ktor.plugin.Koin
import org.koin.logger.slf4jLogger
import org.koin.plugin.module.dsl.withConfiguration

@KoinApplication
object KoinUserApplication

fun Application.main() {
    install(Koin) {
        slf4jLogger()
        withConfiguration<KoinUserApplication>()
    }

    val service by inject<UserService>()
    service.loadUsers()

    routing {
        get("/hello") {
            val userName = call.queryParameters["name"] ?: "Alice"
            val user = service.getUserOrNull(userName)
            val message = service.prepareHelloMessage(user)
            call.respondText(message)
        }
    }
}
```

`withConfiguration<KoinUserApplication>()` loads every `@Configuration` module, so you don't call `modules()`, and the plugin validates the full graph at build time. `slf4jLogger()` sends Koin logs to SLF4J. See [Koin for Ktor](/docs/reference/koin-ktor/ktor) for the Ktor-specific APIs.

## Let's start the server

Start an embedded Netty server that runs your application module:

```kotlin
fun main(args: Array<String>) {
    embeddedServer(Netty, port = 8080) {
        main()
    }.start(wait = true)
}
```

Run the app, then open these URLs:

- `http://localhost:8080/hello`: greets Alice, the default user.
- `http://localhost:8080/hello?name=Bob`: greets Bob.

## Next steps

- [Core Concepts](/docs/intro/core-concepts): the mental model behind modules, definitions and injection.
- [Koin for Ktor](/docs/reference/koin-ktor/ktor): install options, injection in routes and Ktor events.
- [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): every annotation and its parameters.
- [Ktor testing](/docs/reference/koin-ktor/ktor-testing): test your routes with `testApplication` and Koin.
- [Tooling](/docs/tooling): IDE plugin and monitoring tools for Koin.

---

# JUnit Tests

Source: https://insert-koin.io/docs/quickstart/junit-test

In this tutorial you write JUnit 4 tests for the app from the [Kotlin tutorial](/docs/quickstart/kotlin). You learn how to start Koin for each test with `KoinTestRule`, check a module with `verify()`, and replace a dependency with a Mockito mock. It takes about 10 minutes. Do the Kotlin tutorial first, or start from its sample.

This tutorial follows the Compiler Plugin DSL app. All the testing APIs are described in [Unit Testing](/docs/reference/koin-test/testing).

## Get the code

The tests are in the [koin-getting-started/kotlin](https://github.com/InsertKoinIO/koin-getting-started/tree/main/kotlin) sample, under `app/src/test`. Clone the repository and run them from the `kotlin` folder:

```bash
./gradlew test
```

## Gradle setup

The sample adds `koin-test`, `koin-test-junit4` and Mockito as test dependencies:

```toml
# gradle/libs.versions.toml
[versions]
koin = "<KOIN_VERSION>"
mockito = "<MOCKITO_VERSION>"

[libraries]
koin-test = { module = "io.insert-koin:koin-test", version.ref = "koin" }
koin-test-junit4 = { module = "io.insert-koin:koin-test-junit4", version.ref = "koin" }
mockito = { module = "org.mockito:mockito-inline", version.ref = "mockito" }
```

```kotlin
// app/build.gradle.kts
dependencies {
    testImplementation(libs.koin.test)
    testImplementation(libs.koin.test.junit4)
    testImplementation(libs.mockito)
}
```

`koin-test` does not depend on a mocking library, so you add the one you use. For JUnit 5, use `koin-test-junit5` instead (see [Unit Testing](/docs/reference/koin-test/testing)).

## The module under test

The tests load the module from the Kotlin tutorial:

```kotlin
val appModule = module {
    single<UserApplication>()
    single<UserRepositoryImpl>() bind UserRepository::class
    single<UserServiceImpl>() bind UserService::class
}
```

Each test starts Koin with this module, so it runs against the same graph as the app.

## Let's verify the module

`verify()` checks that every constructor parameter in the module has a definition, without creating any instance:

```kotlin
import org.koin.test.AutoCloseKoinTest
import org.koin.test.verify.verify

class ModuleVerificationTest : AutoCloseKoinTest() {

    @Test
    fun verifyModules() {
        appModule.verify()
    }
}
```

The test fails on a missing or invalid definition. The Compiler Plugin already runs this check at build time, so `verify()` matters most for modules the plugin does not cover. See [Verifying your Configuration](/docs/reference/koin-test/verify) to decide whether you need it.

## Let's start Koin in a test

Implement `KoinTest` and add a `KoinTestRule`. The rule starts Koin before each test and stops it after:

```kotlin
import org.koin.test.KoinTest
import org.koin.test.KoinTestRule

class HelloMockTest : KoinTest {

    @get:Rule
    val koinTestRule = KoinTestRule.create {
        modules(appModule)
    }
}
```

`KoinTest` gives the test class `get()` and `by inject()`, for example `val userService: UserService by inject()`. Starting a fresh container per test keeps instances from leaking between tests.

## Let's mock a dependency

Add a `MockProviderRule` to tell Koin how to build mocks, then replace `UserRepository` with `declareMock`:

```kotlin
import org.koin.test.mock.MockProviderRule
import org.koin.test.mock.declareMock
import org.mockito.ArgumentMatchers.anyString
import org.mockito.BDDMockito.given
import org.mockito.Mockito
import org.mockito.Mockito.times

class HelloMockTest : KoinTest {

    @get:Rule
    val koinTestRule = KoinTestRule.create {
        modules(appModule)
    }

    @get:Rule
    val mockProvider = MockProviderRule.create { clazz -> Mockito.mock(clazz.java) }

    @Test
    fun `mock test`() {
        val service = declareMock<UserRepository> {
            given(findUserOrNull(anyString())).willReturn(User("Mock", "mock@example.com"))
        }

        getKoin().get<UserApplication>().sayHello("Mock")
        Mockito.verify(service, times(1)).findUserOrNull(anyString())
    }
}
```

`declareMock` replaces the `UserRepository` definition for this test only. `UserApplication` and `UserService` are real, so the test checks that the call goes through `UserService` down to the repository once.

## Next steps

- [Unit Testing](/docs/reference/koin-test/testing): every testing API, JUnit 5 and overriding definitions.
- [Verifying your Configuration](/docs/reference/koin-test/verify): `verify()` options and when the Compiler Plugin replaces it.
- [Instrumented testing](/docs/reference/koin-android/instrumented-testing): test Android apps that use Koin.
- [Ktor testing](/docs/reference/koin-ktor/ktor-testing): test Ktor routes with Koin.
- [Tooling](/docs/tooling): IDE plugin and monitoring tools for Koin.

---

# Starting Koin

Source: https://insert-koin.io/docs/reference/koin-core/starting-koin

This page covers how to start the Koin container, the options you can pass at start, typed startup with `@KoinApplication`, logging, properties, and how to load or unload modules later. It assumes you know what a module is (see [Modules](/docs/reference/koin-core/modules)).

Code samples come in three tabs: Compiler Plugin DSL, Annotations, Constructor / Classic DSL. Pick yours, the choice applies to every page.

## Start Koin

**Compiler Plugin DSL**
```kotlin
import org.koin.core.context.startKoin

fun main() {
    startKoin {
        printLogger()
        modules(appModule)
    }
}
```

**Annotations**
```kotlin
import org.koin.plugin.module.dsl.startKoin

@KoinApplication(modules = [AppModule::class])
class MyApp

fun main() {
    startKoin<MyApp> {
        printLogger()
    }
}
```

The Koin Compiler Plugin replaces `startKoin<MyApp>()` with a `startKoin { }` call that loads the modules listed in `@KoinApplication`, plus the `@Configuration` modules it discovers. See [Typed startup with @KoinApplication](#typed-startup-with-koinapplication).

**Constructor / Classic DSL**
```kotlin
import org.koin.core.context.startKoin

fun main() {
    startKoin {
        printLogger()
        modules(appModule)
    }
}
```

`startKoin` creates the container and registers it in `GlobalContext`, the default context for your process. Once it returns, every `get()`, `by inject()` or platform API (`by viewModel()`, `koinInject()`) resolves from this container.

You can call `startKoin` only once per process. A second call throws `KoinApplicationAlreadyStartedException`. To add modules after start, use [`loadKoinModules`](#load-and-unload-modules-at-runtime).

## Start options

Everything inside the `startKoin { }` block configures the container:

```kotlin
startKoin {
    printLogger(Level.DEBUG)
    properties(mapOf("server_url" to "https://api.example.com"))
    allowOverride(false)
    modules(coreModule, networkModule)
    lazyModules(analyticsModule)
}
```

| Option | What it does |
|--------|--------------|
| `modules(...)` | Loads modules immediately. Takes one module, several, or a `List<Module>` |
| `lazyModules(...)` | Loads modules in the background. Needs `koin-core-coroutines`, see [Lazy Modules](/docs/reference/koin-core/lazy-modules) |
| `printLogger(level)` | Logs to the console. See [Logging](#logging) |
| `logger(logger)` | Uses your own `Logger` implementation |
| `properties(map)` | Adds properties from a map. See [Properties](#properties) |
| `fileProperties(file)` | Loads properties from a classpath file, `/koin.properties` by default (JVM only) |
| `environmentProperties()` | Loads system properties and environment variables (JVM only) |
| `allowOverride(false)` | Fails when two definitions declare the same type without `.override()`. See [Overriding a definition](/docs/reference/koin-core/definitions#overriding-a-definition) |
| `strictOverride()` | Same as `allowOverride(false)` |
| `createEagerInstances()` | Creates the `createdAtStart` definitions now. `startKoin` and `koinApplication` already do it at the end of the block, so you need it only with `koinApplication(createEagerInstances = false)` |

The `startKoin` block runs on the calling thread. Every module you load there, and every `createdAtStart` definition, adds to startup time.

## Typed startup with @KoinApplication

With the [Koin Compiler Plugin](/docs/setup/compiler-plugin), an application class annotated with `@KoinApplication` describes which modules to load. You start Koin from that class with a typed call:

```kotlin
@Module
@ComponentScan("com.myapp.data")
class DataModule

@Module(includes = [DataModule::class])
class AppModule

@KoinApplication(modules = [AppModule::class])
class MyApp
```

| Call | Result |
|------|--------|
| `startKoin<MyApp>()` | Starts Koin in `GlobalContext` with the modules of `MyApp` |
| `startKoin<MyApp> { ... }` | Same, with a configuration block (logger, properties, extra DSL modules) |
| `koinApplication<MyApp>()` | Creates an isolated `KoinApplication`, not registered globally |
| `koinConfiguration<MyApp>()` | Creates a `KoinConfiguration`, for APIs that start Koin for you (Compose `KoinApplication`, Ktor) |
| `withConfiguration<MyApp>()` | Adds the modules of `MyApp` to an existing `KoinApplication`, for example inside Ktor's `install(Koin) { }` |

These functions are imported from `org.koin.plugin.module.dsl`. They are compiler stubs: without the Compiler Plugin applied, they throw at runtime with a message telling you the plugin is missing.

`@KoinApplication` takes two parameters:

- `modules`: the `@Module` classes to load explicitly.
- `configurations`: the configuration labels to discover. See [Configuration labels](#configuration-labels).

Each `@Module` class brings its `includes` and its `@ComponentScan` definitions. The configuration block of `startKoin<MyApp> { }` is a normal `startKoin` block, so you can mix annotated modules with DSL modules:

```kotlin
startKoin<MyApp> {
    printLogger()
    modules(legacyDslModule)
}
```

### Loading @Module classes without @KoinApplication

Inside a plain `startKoin { }` or `koinApplication { }` block, you can load `@Module` classes directly:

```kotlin
import org.koin.plugin.module.dsl.module
import org.koin.plugin.module.dsl.modules

startKoin {
    module<NetworkModule>()
    modules(DataModule::class, CacheModule::class)
}
```

This helps in tests, when you want only some modules. `module<T>()` and `modules(vararg KClass)` are compiler stubs too, and they don't work inside `startKoin<T> { }`, which the plugin already rewrites.

:::note
With the Compiler Plugin, there is no `AppModule().module` extension to call. Load annotated modules with `@KoinApplication` and `startKoin<T>()`, or with `module<T>()` as shown above.
:::

### Configuration labels

A `@Module` tagged with `@Configuration` is discovered automatically by `@KoinApplication`, including from other Gradle modules on the classpath (see [Auto-discovery with @Configuration](/docs/reference/koin-core/modules#auto-discovery-with-configuration)). Labels let you pick which of these modules to load:

```kotlin
@Module
@Configuration
class CoreModule

@Module
@Configuration("prod")
class ProdDatabaseModule

@Module
@Configuration("test")
class TestDatabaseModule

@Module
@Configuration("default", "test")
class LoggingModule
```

```kotlin
@KoinApplication
class MyApp // loads CoreModule and LoggingModule

@KoinApplication(configurations = ["default", "prod"])
class ProdApp // loads CoreModule, LoggingModule and ProdDatabaseModule

@KoinApplication(configurations = ["test"])
class TestApp // loads TestDatabaseModule and LoggingModule
```

The rules:

- `@Configuration` with no value is the `"default"` label. `@Configuration("default")` is the same.
- `@KoinApplication` with no `configurations` loads the `"default"` label only.
- When you list labels, only those labels load. Add `"default"` to the list if you still want the default modules.
- A module can carry several labels.

## Isolated instance with koinApplication

`koinApplication { }` creates a container that is not registered in `GlobalContext`:

```kotlin
val koinApp = koinApplication {
    modules(sdkModule)
}

val service = koinApp.koin.get<SdkService>()
```

Global APIs (`KoinComponent`, `by inject()` in an Activity) don't see this container. Use it for libraries and SDKs that must not share the host app's container, or for tests that need their own instance. The full pattern is in [Context Isolation](/docs/reference/koin-core/context-isolation).

`koinConfiguration { }` builds a configuration without starting anything. You pass it to APIs that start Koin themselves, such as Compose `KoinApplication` and the Ktor plugin.

## Starting on each platform

- Android: start Koin in `Application.onCreate()` with `androidContext()` and `androidLogger()`. See [Starting Koin on Android](/docs/reference/koin-android/start).
- Compose: start Koin from a composable with `KoinApplication` or `KoinMultiplatformApplication`. See [Koin for Compose](/docs/reference/koin-compose/compose).
- Ktor: install the `Koin` plugin in your `Application` module. See [Koin for Ktor](/docs/reference/koin-ktor/ktor).
- Kotlin Multiplatform: share an `initKoin()` function in `commonMain` and call it from each platform. See [KMP Setup](/docs/reference/koin-core/kmp-setup).

## Load and unload modules at runtime

After start, you can add and remove modules in the global container:

```kotlin
import org.koin.core.context.loadKoinModules
import org.koin.core.context.unloadKoinModules

if (premiumEnabled) {
    loadKoinModules(premiumModule)
}

// later
unloadKoinModules(premiumModule)
```

Both functions take one module or a `List<Module>`. `unloadKoinModules` removes the definitions of the module and drops their instances, so a later `get()` for these types fails.

The Compiler Plugin can't verify a graph assembled at runtime: it can't know when, or if, the module is loaded. Types that other definitions need from a runtime-loaded module must be marked `@Provided`, and the plugin reports the module itself as not loaded at start. See [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety). If you load modules later only to speed up startup, [Lazy Modules](/docs/reference/koin-core/lazy-modules) is usually a better fit.

## Stop Koin

```kotlin
import org.koin.core.context.stopKoin

stopKoin()
```

`stopKoin()` closes the global container: it releases every instance, calls the `onClose` callbacks of your definitions, and clears `GlobalContext`. You can then call `startKoin` again. For an isolated container, call `close()` on the `KoinApplication`:

```kotlin
koinApp.close()
```

In tests, stop Koin after each test so the next one starts clean. [Testing](/docs/reference/koin-test/testing) shows the JUnit rules that do it for you.

## Logging

Koin logs nothing by default (`EmptyLogger`). Turn logging on in the start block:

```kotlin
startKoin {
    printLogger(Level.DEBUG)
    modules(appModule)
}
```

`Level` is `DEBUG`, `INFO`, `WARNING`, `ERROR` or `NONE`. The default level of each logger is `INFO`.

| Logger | Start option | Platform | Artifact |
|--------|--------------|----------|----------|
| `EmptyLogger` | (default) | All | `koin-core` |
| `PrintLogger` | `printLogger()` | All | `koin-core` |
| `AndroidLogger` | `androidLogger()` | Android (Logcat) | `koin-android` |
| `SLF4JLogger` | `slf4jLogger()` | JVM | `koin-logger-slf4j` |

At `DEBUG` level, Koin logs each module load and each resolution with its duration. This is useful to find a slow definition, and too verbose for production.

To send logs somewhere else, extend `Logger` and pass it with `logger()`:

```kotlin
import org.koin.core.logger.Level
import org.koin.core.logger.Logger
import org.koin.core.logger.MESSAGE

class AppLogger : Logger(Level.INFO) {
    override fun display(level: Level, msg: MESSAGE) {
        MyLogSystem.log(level.name, msg)
    }
}

startKoin {
    logger(AppLogger())
}
```

## Properties

Properties are key-value pairs stored in the container. Use them for configuration values such as URLs or keys.

### Loading properties

```kotlin
startKoin {
    properties(mapOf("server_url" to "https://api.example.com"))
    fileProperties()          // JVM: reads /koin.properties from the classpath
    environmentProperties()   // JVM: system properties and environment variables
}
```

On Android, `androidFileProperties()` reads `koin.properties` from the `assets` folder. You can also set and read properties at runtime on the `Koin` instance:

```kotlin
val koin = KoinPlatform.getKoin()
koin.setProperty("session_token", token)
val token: String? = koin.getProperty("session_token")
```

Values loaded from a file or the environment are `String`. Convert them yourself (`getProperty<String>("timeout").toInt()`).

### Injecting properties

**Compiler Plugin DSL**
Annotate the constructor parameter with `@Property` (from `koin-annotations`):

```kotlin
class ApiClient(@Property("server_url") val url: String)

val networkModule = module {
    single<ApiClient>()
}
```

**Annotations**
```kotlin
@Singleton
class ApiClient(@Property("server_url") val url: String)
```

To give a property a default value, annotate a top-level value with `@PropertyValue` and the same key:

```kotlin
@PropertyValue("server_url")
val defaultServerUrl = "https://api.example.com"
```

The generated code reads `getProperty("server_url", defaultServerUrl)`, so `ApiClient` gets the default when nobody set the property.

**Constructor / Classic DSL**
```kotlin
val networkModule = module {
    single { ApiClient(url = getProperty("server_url")) }

    // with a default value
    single { ApiClient(url = getProperty("server_url", "https://api.example.com")) }
}
```

`getProperty(key)` throws if the property is missing. `getPropertyOrNull(key)` returns `null` instead.

Read properties in one configuration class and inject that class, instead of calling `getProperty` in many places. Keys then live in one file.

## Limits

- `startKoin` runs once per process. Call `stopKoin()` before starting again.
- `fileProperties()` and `environmentProperties()` exist on the JVM only. On other platforms, pass a map with `properties()`.
- Typed startup (`startKoin<T>()`, `module<T>()`) needs the Compiler Plugin. The KSP processor is deprecated, see [Migrating from KSP](/docs/migration/from-ksp-to-compiler-plugin).
- Modules loaded with `loadKoinModules` after start are not part of the compile-time graph check.

## Related

- [Modules](/docs/reference/koin-core/modules): organize definitions, `includes()`, `@Module` and `@Configuration`.
- [Definitions](/docs/reference/koin-core/definitions): declare what Koin creates, eager creation and overrides.
- [Lazy Modules](/docs/reference/koin-core/lazy-modules): load modules in the background to shorten startup.
- [Context Isolation](/docs/reference/koin-core/context-isolation): run Koin in an isolated container for SDKs.
- [Compiler Plugin Setup](/docs/setup/compiler-plugin): install the plugin needed for `startKoin<T>()`.
- [Starting Koin on Android](/docs/reference/koin-android/start): `androidContext()`, `androidLogger()` and AndroidX Startup.

---

# Modules

Source: https://insert-koin.io/docs/reference/koin-core/modules

A module groups related definitions, by feature or by layer. This page covers how to declare modules, compose them, scan packages for annotated classes, discover modules across Gradle modules, and in which order modules load. For the definitions inside a module, see [Definitions](/docs/reference/koin-core/definitions).

## Declare a module

**Compiler Plugin DSL**
```kotlin
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*

val networkModule = module {
    single<ApiClient>()
    single<TokenManager>()
}

val dataModule = module {
    single<Database>()
    single<UserRepository>()
}
```

**Annotations**
```kotlin
@Module
@ComponentScan("com.myapp.network")
class NetworkModule

@Module
@ComponentScan("com.myapp.data")
class DataModule
```

A `@Module` class gathers the annotated classes found by `@ComponentScan`, and the provider functions declared inside it (see [Classes you don't own](/docs/reference/koin-core/definitions#classes-you-dont-own)).

**Constructor / Classic DSL**
```kotlin
import org.koin.dsl.module
import org.koin.core.module.dsl.*

val networkModule = module {
    singleOf(::ApiClient)
    singleOf(::TokenManager)
}

val dataModule = module {
    singleOf(::Database)
    singleOf(::UserRepository)
}
```

A definition can depend on a definition from another module. Koin resolves across every loaded module, so `UserRepository` in `dataModule` can use `ApiClient` from `networkModule` without any import between modules. Both modules must be loaded, see [Starting Koin](/docs/reference/koin-core/starting-koin).

## Module composition with `includes()`

A module can include other modules. Loading the parent loads the whole tree:

**Compiler Plugin DSL**
```kotlin
val networkModule = module {
    single<ApiClient>()
}

val storageModule = module {
    single<Database>()
}

val dataModule = module {
    includes(networkModule, storageModule)
    single<UserRepository>()
}

startKoin {
    modules(dataModule)
}
```

**Annotations**
```kotlin
@Module
class NetworkModule

@Module
class StorageModule

@Module(includes = [NetworkModule::class, StorageModule::class])
@ComponentScan("com.myapp.data")
class DataModule

@KoinApplication(modules = [DataModule::class])
class MyApp
```

**Constructor / Classic DSL**
```kotlin
val networkModule = module {
    singleOf(::ApiClient)
}

val storageModule = module {
    singleOf(::Database)
}

val dataModule = module {
    includes(networkModule, storageModule)
    singleOf(::UserRepository)
}

startKoin {
    modules(dataModule)
}
```

Prefer a tree of `includes()` with one root module over a long flat list in `startKoin`. The structure of your modules then follows the structure of your code, and the start call stays short.

Koin flattens the tree and loads each module once, even if several parents include it:

```kotlin
val commonModule = module {
    single<Logger>()
}

val featureAModule = module {
    includes(commonModule)
    single<FeatureA>()
}

val featureBModule = module {
    includes(commonModule)
    single<FeatureB>()
}

val appModule = module {
    includes(featureAModule, featureBModule) // commonModule loads once
}
```

### Visibility in multi-module projects

In a Gradle multi-module project, expose one public module per feature and keep the others `private` or `internal`:

```kotlin
// Gradle module "feature-user"
private val userDataModule = module {
    single<UserDao>()
    single<UserCache>()
}

val userFeatureModule = module {
    includes(userDataModule)
    viewModel<UserViewModel>()
}
```

The app module loads `userFeatureModule` and never sees the internal modules. For a full layout of an Android app split in Gradle modules, see [Multi-Module Apps](/docs/reference/koin-android/multi-module).

## Scan packages with @ComponentScan

`@ComponentScan` is for annotations only. It collects every annotated class and top-level function in a package and its subpackages:

```kotlin
@Module
@ComponentScan
class AppModule // scans the package of AppModule

@Module
@ComponentScan("com.myapp.features")
class FeatureModule

@Module
@ComponentScan("com.myapp.data", "com.myapp.network")
class InfraModule
```

With no value, it scans the package of the annotated class. The scan crosses Gradle modules: classes from another Gradle module in the same package are found too.

With the DSL styles, you list each definition in the module yourself. To mix both, include a DSL module in your start block next to the annotated ones (see [Typed startup with @KoinApplication](/docs/reference/koin-core/starting-koin#typed-startup-with-koinapplication)).

## Auto-discovery with @Configuration

`@Configuration` marks a `@Module` so that `@KoinApplication` finds it without listing it. The module can live in any Gradle module on the classpath:

```kotlin
// Gradle module "feature-user"
@Module
@Configuration
@ComponentScan("com.myapp.feature.user")
class UserFeatureModule

// Gradle module "app"
@KoinApplication
class MyApp

fun main() {
    startKoin<MyApp>() // loads UserFeatureModule
}
```

Adding a feature then means adding the Gradle dependency: no change to the app's module list. The cost is that the list of loaded modules is no longer written in one place. If you want it explicit, list the modules in `@KoinApplication(modules = [...])` instead.

`@Configuration` takes labels, so you can load different modules per environment or flavor. The rules are on [Configuration labels](/docs/reference/koin-core/starting-koin#configuration-labels).

`@Configuration` is annotations only and needs `@KoinApplication` with typed startup (`startKoin<MyApp>()`).

## Load order and overrides

When two loaded modules declare the same type, the module loaded last wins. In a DSL start block, this is the order of `modules(...)`:

```kotlin
startKoin {
    modules(productionModule, debugModule) // debugModule's ApiService wins
}
```

With `@KoinApplication`, the Compiler Plugin builds the module list in this order:

1. The `@Configuration` modules it discovers, from your code and from your dependencies.
2. The modules listed in `@KoinApplication(modules = [...])`, in declaration order.

So the modules of your app override the defaults of a library:

```kotlin
// In a library
@Module
@Configuration
class CoreModule {
    @Singleton
    fun feature(): Feature = DefaultFeature()
}

// In the app
@Module
class AppModule {
    @Singleton
    fun feature(): Feature = AppFeature()
}

@KoinApplication(modules = [AppModule::class])
class MyApp // get<Feature>() returns AppFeature
```

Inside the explicit list, `modules = [A::class, B::class, C::class]` loads A, then B, then C, and each module's `includes` stay grouped with it. A module that is both listed and discovered by `@Configuration` loads once, at its position in the explicit list. To control the order between several `@Configuration` modules, list them explicitly.

To make accidental overrides fail at start, use `allowOverride(false)`. The rules for overriding a single definition are in [Overriding a definition](/docs/reference/koin-core/definitions#overriding-a-definition).

## Eager modules

Mark a whole module to create all its `single` definitions when Koin starts:

**Compiler Plugin DSL**
```kotlin
val coreModule = module(createdAtStart = true) {
    single<ConfigManager>()
    single<CrashReporter>()
}
```

**Annotations**
```kotlin
@Module(createdAtStart = true)
@ComponentScan("com.myapp.core")
class CoreModule
```

**Constructor / Classic DSL**
```kotlin
val coreModule = module(createdAtStart = true) {
    singleOf(::ConfigManager)
    singleOf(::CrashReporter)
}
```

Each eager definition adds to startup time. See [Eager creation](/docs/reference/koin-core/definitions#eager-creation) for the per-definition flag and its cost.

## Parameterized modules

A DSL module is a value, so a function can build it from arguments:

**Compiler Plugin DSL**
```kotlin
fun loggingModule(debug: Boolean) = module {
    if (debug) {
        single<DebugLogger>() bind Logger::class
    } else {
        single<ReleaseLogger>() bind Logger::class
    }
}

startKoin {
    modules(loggingModule(debug = BuildConfig.DEBUG))
}
```

**Annotations**
A `@Module` class takes no arguments. Use a DSL module for this case, or one `@Module` per variant selected with [configuration labels](/docs/reference/koin-core/starting-koin#configuration-labels).

**Constructor / Classic DSL**
```kotlin
fun loggingModule(debug: Boolean) = module {
    single<Logger> {
        if (debug) DebugLogger() else ReleaseLogger()
    }
}

startKoin {
    modules(loggingModule(debug = BuildConfig.DEBUG))
}
```

The same idea swaps implementations: keep `repositoryModule` fixed, and load either `localDatasourceModule` or `remoteDatasourceModule` next to it, each declaring a `Datasource`. Conditional module lists are resolved at runtime, so the Compiler Plugin can't verify every combination at build time.

## Related

- [Definitions](/docs/reference/koin-core/definitions): what goes inside a module.
- [Starting Koin](/docs/reference/koin-core/starting-koin): load modules, typed startup and configuration labels.
- [Lazy Modules](/docs/reference/koin-core/lazy-modules): load modules in the background.
- [KMP Shared Modules](/docs/reference/koin-core/kmp-shared-modules): share modules between platforms.
- [Multi-Module Apps](/docs/reference/koin-android/multi-module): organize modules across Gradle modules on Android.
- [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): every parameter of `@Module`, `@ComponentScan` and `@Configuration`.

---

# Definitions

Source: https://insert-koin.io/docs/reference/koin-core/definitions

A definition tells Koin how to create one type and how long to keep the instance. This page covers the definition types, interface binding, how constructor parameters are resolved, and definitions for classes you don't own. It assumes you know what a module is (see [Core Concepts](/docs/intro/core-concepts)).

Code samples come in three tabs: Compiler Plugin DSL, Annotations, Constructor / Classic DSL. Pick yours, the choice applies to every page. If you are not sure which style to use, read [Choosing your style](/docs/intro/choosing-your-style).

## Definition types

| Type | Instance | Typical use |
|------|----------|-------------|
| `single` | One instance, kept for the lifetime of the Koin container | Repositories, API clients, databases |
| `factory` | A new instance each time it is requested | Presenters, use cases, short-lived objects |
| `scoped` | One instance per scope, released when the scope closes | Objects bound to an Activity, a session, a request |
| `viewModel` | Managed by the ViewModel lifecycle | ViewModels (Android and Compose Multiplatform) |
| `worker` | Created by WorkManager | Android `ListenableWorker` |

Declaring them:

**Compiler Plugin DSL**
```kotlin
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*

val appModule = module {
    single<Database>()
    single<UserRepository>()
    factory<UserPresenter>()
    viewModel<UserViewModel>()
}
```

**Annotations**
```kotlin
@Singleton
class Database

@Singleton
class UserRepository(private val database: Database)

@Factory
class UserPresenter(private val repository: UserRepository)

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

`@Singleton` and `@Single` are equivalent. Prefer `@Singleton`, the JSR-330 name.

**Constructor / Classic DSL**
```kotlin
import org.koin.dsl.module
import org.koin.core.module.dsl.*

val appModule = module {
    singleOf(::Database)
    singleOf(::UserRepository)
    factoryOf(::UserPresenter)
    viewModelOf(::UserViewModel)
}
```

You can also write the constructor call yourself, with `get()` for each dependency:

```kotlin
val appModule = module {
    single { Database() }
    single { UserRepository(get()) }
    factory { UserPresenter(get()) }
    viewModel { UserViewModel(get()) }
}
```

With the Compiler Plugin DSL and annotations, you never write `get()`. The [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin) reads the constructor and generates the calls for you, then checks at build time that every dependency is declared.

`single` and `factory` are explained above. `scoped` needs a scope declaration: see [Scopes](/docs/reference/koin-core/scopes). `viewModel` has its own page: see [ViewModel](/docs/reference/koin-core/viewmodel). `worker` is covered in [WorkManager](/docs/reference/koin-android/workmanager).

### Single or factory?

Use `single` when the object has no per-caller state and is costly to create (a database, an HTTP client). Use `factory` when each caller needs its own instance, or the object holds state that must not be shared. If an instance should live longer than a factory but shorter than the app, you need a [scope](/docs/reference/koin-core/scopes).

## Interface binding

Most of the time, consumers depend on an interface, not on the implementation. Bind the implementation to the interface:

**Compiler Plugin DSL**
```kotlin
val dataModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class

    // several types at once
    single<MyServiceImpl>() binds arrayOf(ServiceA::class, ServiceB::class)
}
```

**Annotations**
```kotlin
@Singleton
class UserRepositoryImpl(private val database: Database) : UserRepository
```

Binding is automatic: Koin binds the class to all its supertypes. To bind only some of them, list them:

```kotlin
@Singleton(binds = [UserRepository::class])
class UserRepositoryImpl(private val database: Database) : UserRepository, Closeable
```

**Constructor / Classic DSL**
```kotlin
val dataModule = module {
    singleOf(::UserRepositoryImpl) bind UserRepository::class

    // or declare the interface type directly
    single<UserRepository> { UserRepositoryImpl(get()) }
}
```

A consumer then asks for `UserRepository` and gets the `UserRepositoryImpl` instance. When two definitions bind the same type, you need a [qualifier](/docs/reference/koin-core/qualifiers) to tell them apart.

## Constructor parameters

Koin resolves each constructor parameter from the container. The parameter type decides how:

| Parameter | Resolved as | Detail |
|-----------|-------------|--------|
| `repository: UserRepository` | The `UserRepository` definition. Fails if it is missing | |
| `logger: Logger?` | The definition if it exists, `null` otherwise | |
| `heavy: Lazy<HeavyService>` | Created on first access of `heavy.value` | [Injection](/docs/reference/koin-core/injection) |
| `loggers: List<Logger>` | All definitions bound to `Logger` | [Advanced Patterns](/docs/reference/koin-core/advanced-patterns#collections-of-dependencies) |
| `@Named("local") db: Database` | The definition with that qualifier | [Qualifiers](/docs/reference/koin-core/qualifiers) |
| `@InjectedParam userId: String` | A value passed by the caller at resolution time | [Injected Parameters](/docs/reference/koin-core/injection-parameters) |
| `@Property("api_url") url: String` | A Koin property | [Starting Koin](/docs/reference/koin-core/starting-koin#properties) |

With the Compiler Plugin DSL and annotations, this works from the constructor signature alone:

**Compiler Plugin DSL**
```kotlin
class SyncService(
    private val repository: UserRepository,
    private val analytics: Analytics?,
    private val uploader: Lazy<Uploader>,
)

val appModule = module {
    single<SyncService>()
}
```

**Annotations**
```kotlin
@Singleton
class SyncService(
    private val repository: UserRepository,
    private val analytics: Analytics?,
    private val uploader: Lazy<Uploader>,
)
```

**Constructor / Classic DSL**
`singleOf(::SyncService)` resolves every parameter with `get()`. For nullable, lazy or list parameters, write the call yourself with the matching function:

```kotlin
val appModule = module {
    single {
        SyncService(
            repository = get(),
            analytics = getOrNull(),
            uploader = inject(),
        )
    }
}
```

`getAll()` returns a `List`, `getProperty("key")` reads a property, and `params.get()` reads an injected parameter.

## Classes you don't own

Classes from libraries (Room, Retrofit, OkHttp) can't be annotated and often come from a builder. Declare them with a function whose parameters Koin resolves:

**Compiler Plugin DSL**
```kotlin
import org.koin.plugin.module.dsl.create

fun database(context: Context): AppDatabase =
    Room.databaseBuilder(context, AppDatabase::class.java, "app-db").build()

fun topicDao(db: AppDatabase): TopicDao = db.topicDao()

val databaseModule = module {
    single { create(::database) }
    single { create(::topicDao) }
}
```

`create(::function)` resolves the function parameters like a constructor, with the same compile-time checks. Qualifier annotations on the function and its parameters work too.

**Annotations**
Annotate a top-level function. `@ComponentScan` finds it like a class:

```kotlin
@Singleton
fun database(context: Context): AppDatabase =
    Room.databaseBuilder(context, AppDatabase::class.java, "app-db").build()

@Singleton
fun topicDao(db: AppDatabase): TopicDao = db.topicDao()
```

Or group provider functions in a `@Module` class:

```kotlin
@Module
class DatabaseModule {

    @Singleton
    fun database(context: Context): AppDatabase =
        Room.databaseBuilder(context, AppDatabase::class.java, "app-db").build()

    @Singleton
    fun topicDao(db: AppDatabase): TopicDao = db.topicDao()
}
```

**Constructor / Classic DSL**
```kotlin
val databaseModule = module {
    single {
        Room.databaseBuilder(androidContext(), AppDatabase::class.java, "app-db").build()
    }
    single { get<AppDatabase>().topicDao() }
}
```

For complete Retrofit, Room and serialization setups on Android, see [Android Library Integration](/docs/reference/koin-android/binding-patterns).

## Eager creation

Koin creates a `single` the first time someone asks for it. To create it when Koin starts instead, mark it `createdAtStart`:

**Compiler Plugin DSL**
```kotlin
val appModule = module {
    single<ConfigManager>() withOptions {
        createdAtStart()
    }
}
```

**Annotations**
```kotlin
@Singleton(createdAtStart = true)
class ConfigManager
```

**Constructor / Classic DSL**
```kotlin
val appModule = module {
    single(createdAtStart = true) { ConfigManager() }
}
```

Eager creation runs on the thread that starts Koin. On Android this is the main thread during `Application.onCreate()`, so every eager definition adds to app startup time. Keep it for objects that must exist before the first screen. To move work off startup, see [Lazy Modules](/docs/reference/koin-core/lazy-modules).

## Release callback

`onClose` runs when the instance is released: when Koin stops for a `single`, or when its scope closes for a `scoped`.

**Compiler Plugin DSL**
```kotlin
val appModule = module {
    single<Database>() onClose { it?.close() }
}
```

**Annotations**
Annotations have no `onClose` parameter. Declare this definition in a DSL module.

**Constructor / Classic DSL**
```kotlin
val appModule = module {
    single { Database() } onClose { it?.close() }
}
```

`onClose` is never called for a `factory`: Koin does not keep factory instances.

## Overriding a definition

When two modules declare the same type, the module loaded last wins:

```kotlin
val prodModule = module {
    single<ApiService> { ProductionApi() }
}

val testModule = module {
    single<ApiService> { FakeApi() }
}

startKoin {
    modules(prodModule, testModule) // ApiService resolves to FakeApi
}
```

This is useful in tests, and a source of bugs when it happens by accident. To make overrides explicit, disable them globally and mark the ones you want:

```kotlin
val testModule = module {
    single<ApiService> { FakeApi() }.override()
}

startKoin {
    allowOverride(false)
    modules(prodModule, testModule)
}
```

With `allowOverride(false)`, an unmarked duplicate fails at start.

## Related

- [Modules](/docs/reference/koin-core/modules): group definitions and compose modules with `includes()`.
- [Qualifiers](/docs/reference/koin-core/qualifiers): several definitions of the same type.
- [Injection](/docs/reference/koin-core/injection): retrieve instances outside of constructors.
- [Scopes](/docs/reference/koin-core/scopes): instances bound to a lifecycle.
- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): what the Compiler Plugin checks in your definitions.
- [DSL Reference](/docs/reference/koin-core/dsl) and [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): every keyword and annotation.

---

# Qualifiers

Source: https://insert-koin.io/docs/reference/koin-core/qualifiers

A qualifier gives a definition a name, so you can declare several definitions of the same type and ask for a specific one. This page covers string, type and enum qualifiers, custom qualifier annotations, and common mistakes. It assumes you know how to declare a definition (see [Definitions](/docs/reference/koin-core/definitions)).

## When you need a qualifier

Koin finds a definition by its type. If two definitions provide the same type, for example two `Database` instances, a plain request for `Database` can't choose between them. A qualifier tells them apart.

If the two objects have different roles, consider giving them different types instead (`LocalDatabase` and `RemoteDatabase` as their own interfaces). A type mismatch is caught by the compiler, a wrong qualifier string is not.

## Named qualifiers

Declare each definition with a name, then ask for the name where you inject it:

**Compiler Plugin DSL**
```kotlin
import org.koin.core.annotation.Named
import org.koin.core.qualifier.named
import org.koin.plugin.module.dsl.*

class UserRepository(
    @Named("local") private val localDb: Database,
    @Named("remote") private val remoteDb: Database,
)

val dataModule = module {
    single<Database>(named("local")) { create(::LocalDatabase) }
    single<Database>(named("remote")) { create(::RemoteDatabase) }
    single<UserRepository>()
}
```

`single<UserRepository>()` reads `@Named` on the constructor parameters and resolves the qualified definitions. You can also put `@Named("local")` on the `LocalDatabase` class itself: `single<LocalDatabase>()` then registers it with that name. The `@Named` annotation comes from the `koin-annotations` artifact.

**Annotations**
```kotlin
import org.koin.core.annotation.Named
import org.koin.core.annotation.Singleton

@Singleton
@Named("local")
class LocalDatabase : Database

@Singleton
@Named("remote")
class RemoteDatabase : Database

@Singleton
class UserRepository(
    @Named("local") private val localDb: Database,
    @Named("remote") private val remoteDb: Database,
)
```

`@Named` works on classes, provider functions and parameters.

**Constructor / Classic DSL**
```kotlin
import org.koin.core.qualifier.named

val dataModule = module {
    single<Database>(named("local")) { LocalDatabase() }
    single<Database>(named("remote")) { RemoteDatabase() }
    single {
        UserRepository(
            localDb = get(named("local")),
            remoteDb = get(named("remote")),
        )
    }
}
```

`singleOf(::UserRepository)` resolves parameters by type only, so it can't pass the qualifiers. Write the constructor call with `get(named(...))`, as shown.

Outside of a definition, pass the qualifier to `get()` or `inject()`:

```kotlin
val localDb: Database by inject(named("local"))
val remoteDb: Database = get(named("remote"))
```

The same qualifier argument exists on every injection API, such as `koinInject(named("local"))` in Compose. See [Injection](/docs/reference/koin-core/injection).

## Type qualifiers

A type can serve as the qualifier. Typos become compile errors, and renaming the type in your IDE updates every use:

**Compiler Plugin DSL**
```kotlin
import org.koin.core.annotation.Qualifier

object LocalDb
object RemoteDb

class UserRepository(
    @Qualifier(LocalDb::class) private val localDb: Database,
    @Qualifier(RemoteDb::class) private val remoteDb: Database,
)

val dataModule = module {
    single<Database>(named<LocalDb>()) { create(::LocalDatabase) }
    single<Database>(named<RemoteDb>()) { create(::RemoteDatabase) }
    single<UserRepository>()
}
```

**Annotations**
```kotlin
object LocalDb
object RemoteDb

@Singleton
@Qualifier(LocalDb::class)
class LocalDatabase : Database

@Singleton
@Qualifier(RemoteDb::class)
class RemoteDatabase : Database

@Singleton
class UserRepository(
    @Qualifier(LocalDb::class) private val localDb: Database,
    @Qualifier(RemoteDb::class) private val remoteDb: Database,
)
```

`@Qualifier(name = "local")` is the string form, equivalent to `@Named("local")`.

**Constructor / Classic DSL**
```kotlin
object LocalDb
object RemoteDb

val dataModule = module {
    single<Database>(named<LocalDb>()) { LocalDatabase() }
    single<Database>(named<RemoteDb>()) { RemoteDatabase() }
    single { UserRepository(get(named<LocalDb>()), get(named<RemoteDb>())) }
}
```

At the call site: `get<Database>(named<LocalDb>())`. `qualifier<LocalDb>()` is an alias of `named<LocalDb>()`.

## Enum qualifiers

An enum entry can be a qualifier too:

```kotlin
enum class DbType { LOCAL, REMOTE }

val dataModule = module {
    single<Database>(named(DbType.LOCAL)) { LocalDatabase() }
    single<Database>(named(DbType.REMOTE)) { RemoteDatabase() }
}

val localDb: Database = get(named(DbType.LOCAL))
```

`named(DbType.LOCAL)` is a string qualifier made from the lowercase entry name. It is the same qualifier as `named("local")`.

## Custom qualifier annotations

With annotations, you can create your own qualifier annotation. Annotate it with `@Qualifier` (or `@Named`), then use it like `@Named`:

```kotlin
import org.koin.core.annotation.Qualifier

@Qualifier
annotation class BaseUrl

@Qualifier
annotation class AuthUrl

@Singleton
@BaseUrl
fun baseUrl(): String = "https://api.example.com"

@Singleton
@AuthUrl
fun authUrl(): String = "https://auth.example.com"

@Singleton
class ApiClient(
    @BaseUrl private val baseUrl: String,
    @AuthUrl private val authUrl: String,
)
```

An annotation with no parameter becomes a type qualifier on the annotation class. From code, retrieve it with `get<String>(named<BaseUrl>())`.

A custom qualifier can take a parameter, to define a family of qualifiers with one annotation:

```kotlin
enum class AppDispatchers { Default, IO }

@Qualifier
annotation class Dispatcher(val dispatcher: AppDispatchers)

@Module
class DispatchersModule {

    @Singleton
    @Dispatcher(AppDispatchers.IO)
    fun ioDispatcher(): CoroutineDispatcher = Dispatchers.IO

    @Singleton
    @Dispatcher(AppDispatchers.Default)
    fun defaultDispatcher(): CoroutineDispatcher = Dispatchers.Default

    @Singleton
    fun applicationScope(
        @Dispatcher(AppDispatchers.Default) dispatcher: CoroutineDispatcher,
    ): CoroutineScope = CoroutineScope(SupervisorJob() + dispatcher)
}
```

The parameter value becomes the qualifier:

- String parameter: `@ApiName("users")` is the string qualifier `"users"`, the same as `@Named("users")`.
- Enum parameter: `@Dispatcher(AppDispatchers.IO)` is the string qualifier made of the enum's full class name and the entry, `named("com.myapp.AppDispatchers.IO")`. It is not the same as `named(AppDispatchers.IO)`, which uses the lowercase entry name.

The Compiler Plugin checks custom qualifiers at build time: a provider and an injection point with different qualifiers is a build error. Custom qualifier annotations also work with the Compiler Plugin DSL, on constructor parameters and on the class passed to `single<T>()`.

Custom qualifier annotations are not available in the Constructor or Classic DSL. Use `named()` there.

## JSR-330 qualifiers

`jakarta.inject.Named`, `javax.inject.Named` and annotations marked with `jakarta.inject.Qualifier` work like their Koin equivalents. See [JSR-330 Support](/docs/reference/koin-android/jsr330).

## Common mistakes

- Missing qualifier at the injection point: `get<Database>()` fails with `NoDefinitionFoundException` when every `Database` definition has a qualifier. A definition with a qualifier is only found with that qualifier.
- Different spelling: `named("encrypted")` and `named("encrypted_client")` are two different qualifiers. Use type or enum qualifiers, or keep the strings in constants, to avoid this.
- Qualifiers on every definition: if the types are already different, a qualifier adds nothing. Use one only when two definitions share a type.

With the Compiler Plugin, the first two mistakes are build errors. When a qualified parameter has no match but an unqualified definition of the same type exists, the error message points to it.

## Related

- [Definitions](/docs/reference/koin-core/definitions): declare definitions and bind them to interfaces.
- [Injection](/docs/reference/koin-core/injection): pass a qualifier to `get()` and `inject()`.
- [Injected Parameters](/docs/reference/koin-core/injection-parameters): pass values at resolution time instead of declaring variants.
- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): what the Compiler Plugin checks about qualifiers.
- [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): parameters of `@Named` and `@Qualifier`.

---

# Injection

Source: https://insert-koin.io/docs/reference/koin-core/injection

Most of your classes receive their dependencies through their constructor, and Koin fills them (see [Constructor parameters](/docs/reference/koin-core/definitions#constructor-parameters)). Some code can't: an Android `Activity`, a `main()` function, a class created by a framework. This page covers the functions that retrieve instances from Koin in that code: `get()`, `inject()`, their nullable variants, and `getAll()`.

## Constructor injection first

Use the functions on this page only where Koin can't create the class:

```kotlin
// Koin creates this class: dependencies come through the constructor
class UserService(
    private val repository: UserRepository,
    private val validator: UserValidator,
)

// Android creates this class: retrieve dependencies with inject()
class UserActivity : AppCompatActivity() {
    private val userService: UserService by inject()
}
```

A class with constructor parameters can be tested by passing fakes, with no Koin container. A class that calls `get()` needs a running container in its tests. Never call `get()` in a default parameter value (`class UserService(val repository: UserRepository = get())`): declare the class in a module instead.

## Lazy and eager retrieval

Retrieval code is the same in every style:

```kotlin
class UserActivity : AppCompatActivity() {

    // lazy: resolved on first access of the property
    private val userService: UserService by inject()

    // eager: resolved now, when the property is initialized
    private val analytics: Analytics = get()
}
```

| Function | Returns | Resolved |
|----------|---------|----------|
| `by inject<T>()` | `Lazy<T>` used as a property delegate | On first access |
| `get<T>()` | `T` | Immediately |

Use `by inject()` for properties. The class can be created before Koin has everything ready (an `Activity` field is initialized before `onCreate()`), and an instance that is never used is never created. Use `get()` inside a function body, when you need the value now.

`inject()` takes a `mode` parameter, a Kotlin `LazyThreadSafetyMode`. The default is `SYNCHRONIZED` on the JVM.

## Where get() and inject() are available

You can call `get()` and `by inject()` from:

- Android classes: `Activity`, `Fragment`, `Service` and other `ComponentCallbacks`, with no extra interface. See [Android Entry Points](/docs/reference/koin-android/entry-points).
- Any class that implements `KoinComponent`. See [KoinComponent](/docs/reference/koin-core/koin-component).
- A `Koin` instance: `KoinPlatform.getKoin().get<UserService>()` uses the global container, `koinApp.koin.get<UserService>()` an isolated one.
- Inside a definition (Classic DSL): `get()`, `inject()`, `getOrNull()`, `injectOrNull()` and `getAll()` resolve from the current scope.

Platform APIs follow the same rules with their own names:

- Compose: `koinInject()` and `koinViewModel()`. See [Koin for Compose](/docs/reference/koin-compose/compose).
- Android ViewModel: `by viewModel()` and `by activityViewModel()`. See [Android ViewModel](/docs/reference/koin-android/viewmodel).
- Ktor: `by inject()` in `Application`, `Route` and `ApplicationCall`. See [Koin for Ktor](/docs/reference/koin-ktor/ktor).

## Optional dependencies

When a definition may be missing, use the nullable variants. They return `null` instead of throwing `NoDefinitionFoundException`:

```kotlin
val koin = KoinPlatform.getKoin()

val tracker: Tracker? = koin.getOrNull()
val crashReporter: CrashReporter? by koin.injectOrNull()
```

`getOrNull()` and `injectOrNull()` exist on `Koin`, on `Scope` and inside definitions. The `KoinComponent` interface provides `get()` and `inject()` only: call `getKoin().getOrNull<T>()` there.

For a constructor parameter, declare it nullable (`tracker: Tracker?`) and Koin passes `null` when no definition exists. See [Constructor parameters](/docs/reference/koin-core/definitions#constructor-parameters).

If Koin itself may not be started, for example in a library, `KoinPlatform.getKoinOrNull()` returns `null` instead of throwing.

## All instances of a type

`getAll<T>()` returns every instance bound to the type `T`, across all definitions:

```kotlin
val koin = KoinPlatform.getKoin()

val interceptors: List<Interceptor> = koin.getAll()
```

The list contains each definition whose main type or bound type is `T`, with or without qualifier. It is empty when there is none. For a constructor parameter, a `List<Interceptor>` parameter does the same. Collection patterns are covered in [Advanced Patterns](/docs/reference/koin-core/advanced-patterns).

## Qualifiers and parameters at the call site

Every retrieval function takes a qualifier and a parameter block:

```kotlin
val localDb: Database by inject(named("local"))

val presenter: UserPresenter = get { parametersOf(userId) }

val detail: DetailPresenter = get(named("compact")) { parametersOf(itemId) }
```

- Qualifier: picks one definition among several of the same type. See [Qualifiers](/docs/reference/koin-core/qualifiers).
- Parameters: values only the caller knows, passed to the definition. See [Injected Parameters](/docs/reference/koin-core/injection-parameters).

With `by inject()`, the parameter block runs on first access, so it can read properties that are set after construction.

## When resolution fails

`get()` throws `NoDefinitionFoundException` when no definition matches the type and qualifier. With `by inject()`, the exception comes on first access of the property, not where you declared it. With the Compiler Plugin, `get()` and `inject()` calls are also checked at build time against the graph of your start call.

For common errors and how to read Koin's messages, see [Troubleshooting](/docs/reference/koin-core/troubleshooting).

## Related

- [Definitions](/docs/reference/koin-core/definitions): constructor injection and how parameters are resolved.
- [KoinComponent](/docs/reference/koin-core/koin-component): give any class access to `get()` and `inject()`.
- [Android Entry Points](/docs/reference/koin-android/entry-points): inject in Activity, Fragment, Service, Receiver and View.
- [Koin for Compose](/docs/reference/koin-compose/compose): `koinInject()` and other Compose APIs.
- [Scopes](/docs/reference/koin-core/scopes): retrieve instances from a scope instead of the root container.

---

# Injected Parameters

Source: https://insert-koin.io/docs/reference/koin-core/injection-parameters

Some objects need a value that only the caller knows, such as a user ID or the current screen. Injected parameters let the caller pass these values when it asks Koin for an instance. This page covers how to declare a parameter in a definition, how to pass it, and how Koin matches values to parameters. It assumes you know how to declare a definition (see [Definitions](/docs/reference/koin-core/definitions)).

## Declare and pass a parameter

Mark which constructor parameters come from the caller. The other parameters are resolved from the container as usual:

**Compiler Plugin DSL**
```kotlin
import org.koin.core.annotation.InjectedParam

class UserPresenter(
    @InjectedParam val userId: String,
    val repository: UserRepository,
)

val appModule = module {
    single<UserRepository>()
    factory<UserPresenter>()
}
```

`@InjectedParam` comes from the `koin-annotations` artifact. It tells the Compiler Plugin that `userId` is not a definition, so the build-time check doesn't report it as missing.

**Annotations**
```kotlin
@Factory
class UserPresenter(
    @InjectedParam val userId: String,
    val repository: UserRepository,
)
```

`@InjectedParam` works on provider function parameters too.

**Constructor / Classic DSL**
The definition lambda receives the parameters as `params`:

```kotlin
val appModule = module {
    singleOf(::UserRepository)
    factory { params -> UserPresenter(userId = params.get(), repository = get()) }
}
```

The caller passes the values with `parametersOf()`, in the same order as the parameters:

```kotlin
import org.koin.core.parameter.parametersOf

val presenter: UserPresenter = get { parametersOf("user-42") }

// or lazily
val presenter: UserPresenter by inject { parametersOf("user-42") }
```

The parameter block is a lambda, so the values are read when the instance is created. With `by inject()`, this is on first access.

Injected parameters are meant for `factory` definitions. A `single` is created once: the values passed the first time are used, and later values are ignored.

Each platform API takes the same block: `koinInject { parametersOf(userId) }` in Compose (see [Koin for Compose](/docs/reference/koin-compose/compose)), and `by viewModel { parametersOf(userId) }` or `koinViewModel { parametersOf(userId) }` for a ViewModel (see [ViewModel](/docs/reference/koin-core/viewmodel)).

## Several parameters

**Compiler Plugin DSL**
```kotlin
class OrderPresenter(
    @InjectedParam val userId: String,
    @InjectedParam val orderId: Long,
    val repository: OrderRepository,
)

val appModule = module {
    factory<OrderPresenter>()
}
```

**Annotations**
```kotlin
@Factory
class OrderPresenter(
    @InjectedParam val userId: String,
    @InjectedParam val orderId: Long,
    val repository: OrderRepository,
)
```

**Constructor / Classic DSL**
Destructure the parameters in the lambda:

```kotlin
val appModule = module {
    factory { (userId: String, orderId: Long) ->
        OrderPresenter(userId, orderId, get())
    }
}
```

Or read them by index, with `params[i]` or `params.get<T>(i)`:

```kotlin
val appModule = module {
    factory { params -> OrderPresenter(params[0], params[1], get()) }
}
```

Destructuring is limited to five values, and the declared types are not checked against what the caller passes. If the order is wrong, the cast fails at runtime.

```kotlin
val presenter: OrderPresenter = get { parametersOf("user-42", 1001L) }
```

## How Koin matches values

`params.get<T>()` and the generated code look up each value with these rules:

- Koin first looks at the value at the current position. If it has the requested type, Koin returns it and moves to the next position.
- Otherwise, Koin returns the first value of the requested type, wherever it is.
- `params.getOrNull<T>()` returns `null` when no value of that type was passed. `get<T>()` throws `DefinitionParameterException`.

In practice, pass the values in constructor order: `parametersOf("user-42", 1001L)` fills `userId` then `orderId`, and two `String` parameters receive two `String` values in order.

If you need one behavior only, build the parameters with another function:

| Function | Matching |
|----------|----------|
| `parametersOf(...)` | Position first, then type (default, rules above) |
| `parameterArrayOf(...)` | Position only. The value at the current position must have the requested type |
| `parameterSetOf(...)` | Type only. Every `get<T>()` returns the first value of that type |

```kotlin
val byIndex = parameterArrayOf(1, 2, 3)
byIndex.get<Int>() // 1
byIndex.get<Int>() // 2

val byType = parameterSetOf("a_string", 42)
byType.get<Int>()    // 42
byType.get<Int>()    // 42
```

## Values resolved from parameters

When Koin creates an instance with parameters, a plain `get()` inside the definition checks the passed values before the container. A parameter that is not marked can still receive a passed value:

```kotlin
val appModule = module {
    factory { UserPresenter(userId = get(), repository = get()) }
}

get<UserPresenter> { parametersOf("user-42") } // userId = "user-42"
```

This also works for dependencies further down: if `UserPresenter` needs a `Tracker` that needs the screen name, a value passed for the presenter can reach the `Tracker` definition.

Prefer `@InjectedParam` or `params.get()` anyway: they say where the value comes from, and the Compiler Plugin can check the rest of the graph.

:::warning
If a passed value has the same type as the requested definition, Koin returns that value directly and never runs the definition. `get<String> { parametersOf("x") }` returns `"x"`. Wrap such parameters in their own type (a value class, for example) when they would collide with the definition's type.
:::

A qualified request, such as `get(named("local"))`, never takes a value from the parameters. Parameters carry no qualifier.

## Related

- [Injection](/docs/reference/koin-core/injection): `get()` and `inject()`, where you pass the parameters.
- [Definitions](/docs/reference/koin-core/definitions#constructor-parameters): how the other constructor parameters are resolved.
- [ViewModel](/docs/reference/koin-core/viewmodel): parameters and `SavedStateHandle` for ViewModels.
- [Qualifiers](/docs/reference/koin-core/qualifiers): choose between definitions instead of passing values.
- [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): `@InjectedParam` and other parameter annotations.

---

# KoinComponent

Source: https://insert-koin.io/docs/reference/koin-core/koin-component

`KoinComponent` is an interface that gives a class access to the Koin container, so it can call `get()` and `by inject()`. This page covers when you need it, how to use it, and why constructor injection is preferred. For the retrieval functions themselves, see [Injection](/docs/reference/koin-core/injection).

## When to use KoinComponent

Use `KoinComponent` for a class that Koin does not create and that has no Koin extension of its own:

- Entry points: a `main()` class, a CLI command, a class created by a framework or by reflection.
- Android classes without Koin extensions: `BroadcastReceiver`, `ContentProvider`, custom `View`. See [Android Entry Points](/docs/reference/koin-android/entry-points).
- Callbacks and listeners whose constructor you don't control.
- Legacy code you can't move to constructor injection yet.

You don't need it for:

- Classes declared in a module: repositories, services, use cases, ViewModels. Koin passes their dependencies through the constructor.
- `Activity`, `Fragment` and `Service`: Koin Android provides `by inject()` and `by viewModel()` on them directly.
- Composables: use `koinInject()`, see [Koin for Compose](/docs/reference/koin-compose/compose).

## Use KoinComponent

Implement the interface, then call `get()` or `by inject()`:

```kotlin
import org.koin.core.component.KoinComponent
import org.koin.core.component.get
import org.koin.core.component.inject

class SyncCommand : KoinComponent {

    // lazy: resolved on first access
    private val syncService: SyncService by inject()

    // eager: resolved when SyncCommand is created
    private val logger: Logger = get()

    fun run() {
        logger.info("Starting sync")
        syncService.sync()
    }
}

fun main() {
    startKoin {
        modules(appModule)
    }
    SyncCommand().run()
}
```

The code is the same in every style: `KoinComponent` only retrieves instances, the definitions can be declared with any style.

`get()` and `inject()` are extension functions: import them from `org.koin.core.component`. They take a qualifier and a parameter block, like every retrieval function (see [Injection](/docs/reference/koin-core/injection#qualifiers-and-parameters-at-the-call-site)).

`KoinComponent` itself has one function, `getKoin()`, which returns the `Koin` instance. Use it for everything else:

```kotlin
class FeatureLoader : KoinComponent {

    fun optionalTracker(): Tracker? = getKoin().getOrNull()

    fun apiUrl(): String = getKoin().getProperty("server_url", "https://api.example.com")

    fun allPlugins(): List<Plugin> = getKoin().getAll()
}
```

Nullable retrieval and `getAll()` are covered in [Injection](/docs/reference/koin-core/injection). Properties are covered in [Starting Koin](/docs/reference/koin-core/starting-koin#properties).

### Custom Android View

A custom `View` is created by the layout inflater, so Koin can't pass constructor parameters. `KoinComponent` fits here:

```kotlin
class ChartView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
) : View(context, attrs), KoinComponent {

    private val formatter: ChartFormatter by inject()

    fun setData(points: List<DataPoint>) {
        val formatted = formatter.format(points)
        // draw
    }
}
```

Use `by inject()` in a `View`: the layout editor creates views without a running Koin container, and an eager `get()` would fail there.

## Which container KoinComponent uses

By default, `getKoin()` returns the global container started with `startKoin`. If `startKoin` has not been called yet, `get()` throws `IllegalStateException` ("KoinApplication has not been started").

A library or SDK that runs its own isolated container overrides `getKoin()` to return it:

```kotlin
object SdkKoinContext {
    val koinApp = koinApplication { modules(sdkModule) }
}

abstract class SdkComponent : KoinComponent {
    override fun getKoin(): Koin = SdkKoinContext.koinApp.koin
}

class SdkClient : SdkComponent() {
    private val api: SdkApi by inject() // resolved from the SDK container
}
```

The full pattern is in [Context Isolation](/docs/reference/koin-core/context-isolation).

For a class that owns a scope, implement `KoinScopeComponent` instead: `get()` and `inject()` then resolve from that scope. See [Scopes](/docs/reference/koin-core/scopes).

## Why constructor injection is preferred

Compare the two versions of the same class:

**Compiler Plugin DSL**
```kotlin
// depends on Koin, dependencies are hidden in the body
class UserService : KoinComponent {
    private val repository: UserRepository by inject()
}

// plain Kotlin class, dependencies are visible in the constructor
class UserService(private val repository: UserRepository)

val appModule = module {
    single<UserRepository>()
    single<UserService>()
}
```

**Annotations**
```kotlin
// depends on Koin, dependencies are hidden in the body
class UserService : KoinComponent {
    private val repository: UserRepository by inject()
}

// plain Kotlin class, dependencies are visible in the constructor
@Singleton
class UserService(private val repository: UserRepository)
```

**Constructor / Classic DSL**
```kotlin
// depends on Koin, dependencies are hidden in the body
class UserService : KoinComponent {
    private val repository: UserRepository by inject()
}

// plain Kotlin class, dependencies are visible in the constructor
class UserService(private val repository: UserRepository)

val appModule = module {
    singleOf(::UserRepository)
    singleOf(::UserService)
}
```

The constructor version is better in four ways:

- Visible dependencies: the constructor lists what the class needs. With `KoinComponent`, you have to read the body.
- Tests without Koin: you create `UserService(FakeUserRepository())` directly. The `KoinComponent` version needs a running container with a fake definition.
- Build-time checks: the Compiler Plugin verifies constructor dependencies of declared classes against the graph.
- No framework coupling: the class compiles and runs without Koin, which matters for shared code and libraries.

Keep `KoinComponent` at the edges. One entry point retrieves the top object, and everything below it uses constructor injection:

```kotlin
class SyncCommand : KoinComponent {
    private val syncService: SyncService by inject()
}

class SyncService(private val repository: UserRepository, private val api: ApiClient)
class UserRepository(private val database: Database)
```

## Testing a KoinComponent

A class that implements `KoinComponent` reads from the global container, so the test must start Koin with the definitions it needs, and stop it afterward:

```kotlin
class SyncCommandTest : KoinTest {

    @get:Rule
    val koinTestRule = KoinTestRule.create {
        modules(module {
            single<SyncService> { FakeSyncService() }
            single<Logger> { TestLogger() }
        })
    }

    @Test
    fun `run calls sync`() {
        SyncCommand().run()
        // assert on FakeSyncService
    }
}
```

`KoinTestRule` starts Koin before each test and stops it after. Rules, mocking and module verification are covered in [Testing](/docs/reference/koin-test/testing).

## Related

- [Injection](/docs/reference/koin-core/injection): `get()`, `inject()`, nullable retrieval and `getAll()`.
- [Android Entry Points](/docs/reference/koin-android/entry-points): which Android classes need `KoinComponent` and which don't.
- [Context Isolation](/docs/reference/koin-core/context-isolation): point `KoinComponent` to an isolated container.
- [Scopes](/docs/reference/koin-core/scopes): `KoinScopeComponent` for classes that own a scope.
- [Testing](/docs/reference/koin-test/testing): test classes that use Koin.

---

# Scopes

Source: https://insert-koin.io/docs/reference/koin-core/scopes

A scope is a container for instances that live longer than a `factory` but shorter than a `single`. This page covers declaring scopes and scoped definitions, creating and closing scope instances, linking scopes, and scope archetypes. It assumes you know [definitions](/docs/reference/koin-core/definitions).

Platform APIs build on this page: [Android Scopes](/docs/reference/koin-android/scope) (`ScopeActivity`, `AndroidScopeComponent`, `activityScope()`), [Scopes in Compose](/docs/reference/koin-compose/compose-scopes) and [Ktor Request Scopes](/docs/reference/koin-ktor/ktor-scopes).

## How scopes work

A scope has two parts:

- **Scope declaration**: a section in a module, identified by a qualifier (a type or a name). It lists the definitions that belong to the scope.
- **Scope instance**: created at runtime from a declaration, with a unique scope id. Each scope instance holds its own copy of every `scoped` definition, until you close it.

| Definition | Instance |
|------------|----------|
| `single` | One for the whole container |
| `factory` | A new one on each request |
| `scoped` | One per scope instance, released when the scope instance closes |

Use a scope when several objects must share the same instance for a bounded time (a login session, a checkout flow, a screen), and that instance must be dropped afterwards.

## Declaring a scope

**Compiler Plugin DSL**
```kotlin
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*

val sessionModule = module {
    // scope identified by a type
    scope<UserSession> {
        scoped<SessionData>()
        scoped<CartRepository>()
        factory<CheckoutPresenter>()
    }

    // scope identified by a name
    scope(named("checkout")) {
        scoped<CheckoutNavigator>()
    }
}
```

**Annotations**
Tag the class with `@Scope` to say which scope it belongs to, and with `@Scoped` to declare it as a scoped definition. You need both:

```kotlin
@Scope(UserSession::class)
@Scoped
class SessionData

@Scope(UserSession::class)
@Scoped
class CartRepository(private val sessionData: SessionData)

// scope identified by a name
@Scope(name = "checkout")
@Scoped
class CheckoutNavigator
```

`@Scope(UserSession::class)` is the same as `scope<UserSession> { }`, and `@Scope(name = "checkout")` the same as `scope(named("checkout")) { }`. Both annotations also work on functions in a `@Module` class.

**Constructor / Classic DSL**
```kotlin
import org.koin.dsl.module
import org.koin.core.module.dsl.*

val sessionModule = module {
    scope<UserSession> {
        scopedOf(::SessionData)
        scopedOf(::CartRepository)
        factoryOf(::CheckoutPresenter)
    }

    scope(named("checkout")) {
        scoped { CheckoutNavigator() }
    }
}
```

A `factory` inside a scope section creates a new instance on each request, but can depend on the scoped instances of that scope.

Use a type as scope qualifier when the scope is tied to one class (`UserSession`, `MainActivity`). Use a name when no class fits. `scope(named<MyQualifier>())` takes a type qualifier.

## Creating and closing a scope

Create a scope instance from the `Koin` instance, with an id and the scope qualifier. This happens where the lifecycle starts and ends, typically at an entry point (login and logout screens, a request handler):

```kotlin
val koin = KoinPlatform.getKoin()

// on login
val scope = koin.createScope<UserSession>(userId)
val cart: CartRepository = scope.get()

// on logout
koin.getScopeOrNull(userId)?.close()
```

The scoped classes themselves (`CartRepository`, `SessionData`) use constructor injection like any other definition.

| Function | Behavior |
|----------|----------|
| `createScope<T>(scopeId)` | Creates a scope instance for the type qualifier `T` |
| `createScope(scopeId, qualifier)` | Creates a scope instance for any qualifier, for example `named("checkout")` |
| `getOrCreateScope(scopeId, qualifier)` | Returns the open scope with this id, or creates it |
| `getScope(scopeId)` | Returns the open scope. Throws `ScopeNotCreatedException` ("No scope found for id '...'") if there is none |
| `getScopeOrNull(scopeId)` | Returns the open scope, or `null` |
| `deleteScope(scopeId)` | Removes the scope instance from the registry |

The scope id must be unique among open scopes. Two scope instances of the same declaration hold different instances:

```kotlin
val first = getKoin().createScope<UserSession>("user_1")
val second = getKoin().createScope<UserSession>("user_2")

first.get<SessionData>() !== second.get<SessionData>() // true
```

When you call `scope.close()`:

1. Koin calls the `onClose` callback of each scoped instance, then releases them.
2. The scope is removed from the registry.
3. Any later `get()` on it throws `ClosedScopeException` ("Scope '...' is closed"). Check `scope.closed` if you are not sure.

```kotlin
val sessionModule = module {
    scope<UserSession> {
        scoped<SessionData>() onClose { it?.clear() }
    }
}
```

To run code when the scope itself closes, register a `ScopeCallback` with `scope.registerCallback()`.

:::warning
A scope you create by hand stays open until you close it. Every instance it holds stays in memory. Close it at the end of its lifecycle (logout, end of flow). On Android, `activityScope()` and `fragmentScope()` close the scope for you: see [Android Scopes](/docs/reference/koin-android/scope).
:::

## Scope components

A class that owns a scope lifecycle can implement `KoinScopeComponent`. Its `get()` and `inject()` calls then resolve from its scope. This is an advanced pattern for the scope owner only: the definitions inside the scope still receive their dependencies through the constructor.

```kotlin
class UserSession : KoinScopeComponent {
    override val scope: Scope by lazy { createScope(this) }

    // resolved from the UserSession scope
    val cart: CartRepository by inject()

    fun close() {
        scope.close()
    }
}
```

`createScope(this)` uses the class type as scope qualifier, an id built from the class name and hash code, and `this` as scope source. `newScope()` and `getOrCreateScope()` are lazy delegates for the same purpose: `override val scope by newScope()`.

## Resolution inside a scope

From a scope instance, Koin looks for a definition in this order:

1. The definitions of the scope (or of its archetype, see below).
2. The scope source.
3. The linked scopes, in order. The root scope, with all `single` and `factory` definitions, is always linked last.

So a scoped class can depend on singletons and on other scoped classes of the same scope:

**Compiler Plugin DSL**
```kotlin
class CartRepository(
    private val api: ApiService,        // single, from the root scope
    private val sessionData: SessionData // scoped, from the same scope
)

val sessionModule = module {
    single<ApiService>()
    scope<UserSession> {
        scoped<SessionData>()
        scoped<CartRepository>()
    }
}
```

**Annotations**
```kotlin
@Singleton
class ApiService

@Scope(UserSession::class)
@Scoped
class SessionData

@Scope(UserSession::class)
@Scoped
class CartRepository(
    private val api: ApiService,         // single, from the root scope
    private val sessionData: SessionData // scoped, from the same scope
)
```

**Constructor / Classic DSL**
```kotlin
val sessionModule = module {
    singleOf(::ApiService)
    scope<UserSession> {
        scopedOf(::SessionData)
        scopedOf(::CartRepository)
    }
}
```

The reverse does not work: a `single` cannot depend on a `scoped` definition, and `get<SessionData>()` from the root scope fails with `NoDefinitionFoundException`. Resolve scoped instances from their scope instance.

### Scope source

The scope source is the object that created the scope, passed as `source` in `createScope(scopeId, qualifier, source)`. A scoped definition can ask for it by type, like any other dependency:

```kotlin
class SessionLogger(private val session: UserSession)

val sessionModule = module {
    scope<UserSession> {
        scoped<SessionLogger>() // receives the UserSession that created the scope
    }
}
```

The source is only resolved for unqualified requests, and it is released when the scope closes.

### Injecting the scope

A scoped definition can receive the `Scope` itself as a constructor parameter, to resolve more instances later or to close it.

### Instances created outside Koin

`scope.declare(instance)` adds an object you already have to one scope instance, without a definition in a module:

```kotlin
val scope = getKoin().createScope<UserSession>(userId)
scope.declare(UserProfile(userId, name))
```

## Resolving from another scope

### Linking scopes

`linkTo` adds another scope to the resolution chain. The linked scope is searched after the current one:

```kotlin
val sessionScope = getKoin().createScope<UserSession>(userId)
val checkoutScope = getKoin().createScope("checkout_$userId", named("checkout"))

checkoutScope.linkTo(sessionScope)

// resolved from checkoutScope first, then sessionScope, then root
val cart: CartRepository = checkoutScope.get()
```

`unlink(scope)` removes the link. The root scope cannot be linked to anything.

### Pointing at a scope id

With annotations, `@ScopeId` resolves one constructor parameter from the scope instance with a given id, or a given type:

```kotlin
@Factory
class OrderSummary(
    @ScopeId(name = "checkout_main") val navigator: CheckoutNavigator
)

@Factory
class CartBadge(
    @ScopeId(UserSession::class) val cart: CartRepository
)
```

`@ScopeId(name = "checkout_main")` is the same as `getScope("checkout_main").get<CheckoutNavigator>()` in the DSL. With a type, the scope id is the fully qualified class name (`"com.example.UserSession"`). The scope instance with this id must exist when the definition is resolved, or `getScope()` throws `ScopeNotCreatedException`.

## Scope archetypes

A scope declared with a type (`scope<MainActivity>`) only applies to that type. A **scope archetype** is a generic scope declaration shared by every component of a kind: every ViewModel, every Activity, every Fragment. You declare the definitions once, and each component gets its own scope instance.

**Compiler Plugin DSL**
```kotlin
val appModule = module {
    viewModelScope {
        scoped<UserCache>()
        viewModel<UserViewModel>()
    }

    // Android only, koin-android
    activityScope {
        scoped<ActivityPresenter>()
    }
    fragmentScope {
        scoped<FragmentPresenter>()
    }
}
```

**Annotations**
An archetype annotation replaces `@Scope` and `@Scoped`:

```kotlin
import org.koin.core.annotation.ViewModelScope
import org.koin.android.annotation.ActivityScope
import org.koin.android.annotation.FragmentScope

@ViewModelScope
class UserCache(private val api: ApiService)

@ActivityScope
class ActivityPresenter

@FragmentScope
class FragmentPresenter
```

Archetype annotations also work on functions in a `@Module` class.

**Constructor / Classic DSL**
```kotlin
val appModule = module {
    viewModelScope {
        scopedOf(::UserCache)
        viewModelOf(::UserViewModel)
    }

    // Android only, koin-android
    activityScope {
        scopedOf(::ActivityPresenter)
    }
    fragmentScope {
        scopedOf(::FragmentPresenter)
    }
}
```

| Archetype | DSL | Annotation | Closed when | Platform |
|-----------|-----|------------|-------------|----------|
| ViewModel | `viewModelScope { }` | `@ViewModelScope` | The ViewModel is cleared | All (`koin-core-viewmodel`) |
| Activity | `activityScope { }` | `@ActivityScope` | The Activity is destroyed | Android |
| Activity retained | `activityRetainedScope { }` | `@ActivityRetainedScope` | The Activity finishes (survives configuration changes) | Android |
| Fragment | `fragmentScope { }` | `@FragmentScope` | The Fragment is destroyed | Android |

The archetype only declares the definitions. The component opens its scope instance at runtime: for Android, with the `activityScope()` and `fragmentScope()` delegates described in [Android Scopes](/docs/reference/koin-android/scope).

The ViewModel archetype needs the `viewModelScopeFactory()` option at start, so Koin creates a scope for each ViewModel. It is marked `@KoinViewModelScopeApi` and `@KoinExperimentalAPI`:

```kotlin
startKoin {
    options(viewModelScopeFactory())
    modules(appModule)
}
```

ViewModels that take scoped dependencies in their constructor must be declared inside `viewModelScope { }`. Details on ViewModels are in [ViewModel](/docs/reference/koin-core/viewmodel).

:::tip
A scope that is never closed keeps its instances alive. To see open scopes and leaked instances in real user sessions, see [Production Monitoring](/docs/tooling/production-monitoring).
:::

## Limits

- **Manual lifecycle**: outside the archetypes and platform helpers, you create and close scopes yourself. Koin does not detect a forgotten `close()`.
- **No access from the root**: `single` definitions and the root scope cannot see `scoped` definitions.
- **Closed is final**: a closed scope instance cannot be reopened. Create a new one with a new id.
- **Unique ids**: creating a scope with the id of an open scope fails. Use `getOrCreateScope` if the scope may already exist.

## Related

- [Android Scopes](/docs/reference/koin-android/scope): `ScopeActivity`, `AndroidScopeComponent`, `activityScope()` and `fragmentScope()`.
- [Scopes in Compose](/docs/reference/koin-compose/compose-scopes): `KoinScope`, `rememberKoinScope` and navigation scopes.
- [Ktor Request Scopes](/docs/reference/koin-ktor/ktor-scopes): one scope per HTTP request.
- [ViewModel](/docs/reference/koin-core/viewmodel): ViewModel declaration and the ViewModel scope.
- [Definitions](/docs/reference/koin-core/definitions): `single`, `factory`, `scoped` and `onClose`.
- [DSL Reference](/docs/reference/koin-core/dsl): every scope DSL keyword.

---

# ViewModel

Source: https://insert-koin.io/docs/reference/koin-core/viewmodel

This page covers how to declare a ViewModel in a Koin module, on every platform that supports AndroidX ViewModel (Android, iOS, desktop, web). It assumes you know [definitions](/docs/reference/koin-core/definitions). To retrieve a ViewModel, see the platform pages: [Android ViewModel](/docs/reference/koin-android/viewmodel) for `by viewModel()` in an Activity or Fragment, and [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel) for `koinViewModel()`.

## Dependencies

The declaration DSL is in `koin-core-viewmodel`, a multiplatform artifact:

```kotlin
// build.gradle.kts, commonMain
implementation("io.insert-koin:koin-core-viewmodel")
```

The injection APIs come with the platform artifacts: `io.insert-koin:koin-android` (it includes `koin-core-viewmodel`) and `io.insert-koin:koin-compose-viewmodel`. Versions come from the BOM: see [Gradle Setup](/docs/setup/gradle).

## Declaring a ViewModel

**Compiler Plugin DSL**
```kotlin
import org.koin.dsl.module
import org.koin.plugin.module.dsl.viewModel

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

val appModule = module {
    viewModel<UserViewModel>()
}
```

**Annotations**
```kotlin
import org.koin.core.annotation.KoinViewModel

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

With the Compiler Plugin, `@KoinViewModel` is in `org.koin.core.annotation` and works in common code. The KSP processor used `org.koin.android.annotation.KoinViewModel`.

**Constructor / Classic DSL**
```kotlin
import org.koin.dsl.module
import org.koin.core.module.dsl.viewModelOf
import org.koin.core.module.dsl.viewModel

val appModule = module {
    viewModelOf(::UserViewModel)

    // or with the constructor call written out
    viewModel { UserViewModel(get()) }
}
```

A `viewModel` definition creates a new instance on each request, like a `factory`. The platform `ViewModelStore` (Activity, Fragment, navigation entry) keeps the instance, so the same owner gets the same ViewModel back, across configuration changes on Android. Do not declare a ViewModel as `single`: it would be shared by every screen and never cleared.

## Passing parameters

A ViewModel often needs a value known only at runtime, such as an item id. Mark the constructor parameter as an injected parameter:

**Compiler Plugin DSL**
```kotlin
class DetailViewModel(
    @InjectedParam val itemId: String,
    private val repository: DetailRepository,
) : ViewModel()

val appModule = module {
    viewModel<DetailViewModel>()
}
```

**Annotations**
```kotlin
@KoinViewModel
class DetailViewModel(
    @InjectedParam val itemId: String,
    private val repository: DetailRepository,
) : ViewModel()
```

**Constructor / Classic DSL**
```kotlin
val appModule = module {
    viewModel { params ->
        DetailViewModel(itemId = params.get(), repository = get())
    }
}
```

`viewModelOf(::DetailViewModel)` also works: it reads parameters by type from the values passed by the caller.

The caller passes the value with `parametersOf`, whatever the declaration style:

```kotlin
// Android
val viewModel: DetailViewModel by viewModel { parametersOf("item_123") }

// Compose
val viewModel = koinViewModel<DetailViewModel> { parametersOf("item_123") }
```

Parameters are read once, when the ViewModel is created. If the same owner asks again with another value, it gets the existing instance. More on parameters in [Injected Parameters](/docs/reference/koin-core/injection-parameters).

## SavedStateHandle

Add a `SavedStateHandle` parameter to the constructor. Koin creates it from the ViewModel `CreationExtras`, with no declaration:

**Compiler Plugin DSL**
```kotlin
class ProfileViewModel(
    private val handle: SavedStateHandle,
    private val repository: UserRepository,
) : ViewModel() {
    val userId: String? = handle["userId"]
}

val appModule = module {
    viewModel<ProfileViewModel>()
}
```

**Annotations**
```kotlin
@KoinViewModel
class ProfileViewModel(
    private val handle: SavedStateHandle,
    private val repository: UserRepository,
) : ViewModel() {
    val userId: String? = handle["userId"]
}
```

**Constructor / Classic DSL**
```kotlin
val appModule = module {
    viewModelOf(::ProfileViewModel)

    // or: get() resolves the SavedStateHandle
    viewModel { ProfileViewModel(get(), get()) }
}
```

On Android, navigation arguments and Activity extras are in the `SavedStateHandle`. Inject it in the constructor only. If the ViewModel owner has no `SavedStateRegistryOwner`, Koin fails with "Koin could not create a SavedStateHandle: the ViewModel's CreationExtras has no SavedStateRegistryOwner."

## ViewModel scope

A ViewModel can own a [scope](/docs/reference/koin-core/scopes): dependencies created with it and released when it is cleared. Declare them with the `viewModelScope` archetype:

**Compiler Plugin DSL**
```kotlin
val appModule = module {
    viewModelScope {
        scoped<UserCache>()
        viewModel<UserViewModel>()
    }
}
```

**Annotations**
```kotlin
@ViewModelScope
class UserCache

@KoinViewModel
@ViewModelScope
class UserViewModel(private val cache: UserCache) : ViewModel()
```

**Constructor / Classic DSL**
```kotlin
val appModule = module {
    viewModelScope {
        scopedOf(::UserCache)
        viewModelOf(::UserViewModel)
    }
}
```

Enable the option at start, or the ViewModel gets no scope:

```kotlin
startKoin {
    options(viewModelScopeFactory())
    modules(appModule)
}
```

`viewModelScope` and `viewModelScopeFactory()` require opting in to `@KoinViewModelScopeApi` and `@KoinExperimentalAPI`. A ViewModel that takes scoped dependencies in its constructor must be declared inside `viewModelScope { }`. Each ViewModel instance gets its own `UserCache`, closed when the ViewModel is cleared.

## Limits

- **One instance per owner**: injected parameters are ignored once the ViewModel exists for that owner. Use a different key or owner to get a second instance.
- **No `single` ViewModel**: a singleton ViewModel is never cleared and leaks its dependencies.
- **Experimental ViewModel scope**: `viewModelScope` is marked experimental and may change.

## Related

- [Android ViewModel](/docs/reference/koin-android/viewmodel): `by viewModel()`, `activityViewModel()`, navigation graph ViewModels.
- [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel): `koinViewModel()` and navigation ViewModels.
- [Injected Parameters](/docs/reference/koin-core/injection-parameters): `parametersOf` and `@InjectedParam`.
- [Scopes](/docs/reference/koin-core/scopes): scope archetypes and scope lifecycle.
- [Definitions](/docs/reference/koin-core/definitions): the other definition types.

---

# Advanced Patterns

Source: https://insert-koin.io/docs/reference/koin-core/advanced-patterns

This page covers patterns beyond one class per definition: collections of implementations, generic types, providers for runtime objects, and decorators. It assumes you know [definitions](/docs/reference/koin-core/definitions) and [qualifiers](/docs/reference/koin-core/qualifiers). For classes from libraries (Retrofit, Room, OkHttp), see [Classes you don't own](/docs/reference/koin-core/definitions#classes-you-dont-own).

## Collections of dependencies

To inject every implementation of an interface, bind each one to the interface and ask for a `List`:

**Compiler Plugin DSL**
```kotlin
interface PaymentProcessor {
    fun process(amount: Double): Boolean
}

class CreditCardProcessor : PaymentProcessor { ... }
class PayPalProcessor : PaymentProcessor { ... }

class PaymentManager(private val processors: List<PaymentProcessor>)

val paymentModule = module {
    single<CreditCardProcessor>() bind PaymentProcessor::class
    single<PayPalProcessor>() bind PaymentProcessor::class
    single<PaymentManager>()
}
```

**Annotations**
```kotlin
interface PaymentProcessor {
    fun process(amount: Double): Boolean
}

// bound to PaymentProcessor automatically
@Singleton
class CreditCardProcessor : PaymentProcessor { ... }

@Singleton
class PayPalProcessor : PaymentProcessor { ... }

@Singleton
class PaymentManager(private val processors: List<PaymentProcessor>)
```

**Constructor / Classic DSL**
```kotlin
val paymentModule = module {
    singleOf(::CreditCardProcessor) bind PaymentProcessor::class
    singleOf(::PayPalProcessor) bind PaymentProcessor::class
    single { PaymentManager(getAll()) }
}
```

A `List<T>` parameter resolves with `getAll<T>()`: every definition whose type, or one of its bound types, is `T`, with or without a qualifier. Outside a constructor, call `getAll<PaymentProcessor>()` on a `Scope` or on `getKoin()`.

Behavior to know:

- **Empty list**: if nothing is bound to `T`, the list is empty. No error, and the Compiler Plugin does not report a missing dependency for a `List<T>` parameter.
- **No order**: do not rely on the order of the list. If order matters, sort it, for example by a `priority` property on the interface.
- **Current scope only**: from a scope instance, `getAll` returns the definitions of that scope and of its linked scopes, including the root.
- **Single lookup**: `get<PaymentProcessor>()` still returns only one of the bound definitions (the last one loaded). To pick one, give each a [qualifier](/docs/reference/koin-core/qualifiers).

- **Strict override**: with `allowOverride(false)`, binding the same interface without a qualifier in two different modules fails at start with `DefinitionOverrideException`. Give each binding a qualifier.

When you need both the list and a specific implementation, combine binding and qualifiers. With the Compiler Plugin DSL and annotations, put `@Named` on the class:

```kotlin
@Named("creditCard")
class CreditCardProcessor : PaymentProcessor { ... }

@Named("paypal")
class PayPalProcessor : PaymentProcessor { ... }

val paymentModule = module {
    single<CreditCardProcessor>() bind PaymentProcessor::class
    single<PayPalProcessor>() bind PaymentProcessor::class
}

class CheckoutService(
    @Named("creditCard") private val defaultProcessor: PaymentProcessor,
    private val allProcessors: List<PaymentProcessor>,
)
```

## Generic types

Koin identifies a definition by its class and qualifier. Type arguments are erased: `Repository<User>` and `Repository<Product>` are the same key, `Repository`. Two definitions of the same generic class override each other, and the Compiler Plugin validates them as one.

```kotlin
// Does not work: the second definition overrides the first
val repositoryModule = module {
    single<Repository<User>> { UserRepository() }
    single<Repository<Product>> { ProductRepository() }
}
```

Use one of these instead:

- **Concrete types**: inject `UserRepository` and `ProductRepository` directly. Each class is its own key.
- **Qualifiers**: keep the generic interface and tell the definitions apart with a qualifier.

**Compiler Plugin DSL**
```kotlin
@Qualifier(User::class)
class UserRepository : Repository<User> { ... }

@Qualifier(Product::class)
class ProductRepository : Repository<Product> { ... }

val repositoryModule = module {
    single<UserRepository>() bind Repository::class
    single<ProductRepository>() bind Repository::class
}

class UserService(@Qualifier(User::class) private val repository: Repository<User>)
```

**Annotations**
```kotlin
@Singleton
@Qualifier(User::class)
class UserRepository : Repository<User> { ... }

@Singleton
@Qualifier(Product::class)
class ProductRepository : Repository<Product> { ... }

@Singleton
class UserService(@Qualifier(User::class) private val repository: Repository<User>)
```

**Constructor / Classic DSL**
```kotlin
val repositoryModule = module {
    single<Repository<User>>(named<User>()) { UserRepository() }
    single<Repository<Product>>(named<Product>()) { ProductRepository() }
    single { UserService(get(named<User>())) }
}
```

`named<User>()` is a type qualifier built from the class `User`. `@Qualifier(User::class)` is its annotation form.

## Provider pattern

Some objects need values that exist only at runtime: a title, a callback, a user choice. Instead of resolving them from Koin each time, inject a provider class that creates them:

```kotlin
class DialogProvider(private val context: Context) {

    fun confirmDialog(title: String, onConfirm: () -> Unit): AlertDialog =
        AlertDialog.Builder(context)
            .setTitle(title)
            .setPositiveButton("OK") { _, _ -> onConfirm() }
            .create()
}

class SettingsScreen(private val dialogs: DialogProvider) {
    fun askReset() {
        dialogs.confirmDialog("Reset settings?") { reset() }.show()
    }
}
```

Declare `DialogProvider` like any class (`factory<DialogProvider>()`, `@Factory`, or `factoryOf(::DialogProvider)`). The provider gets its dependencies from Koin, the created objects get their runtime values from the caller.

For a value known at the call site and needed in the constructor, [injected parameters](/docs/reference/koin-core/injection-parameters) are the simpler option. For an instance that is costly and not always needed, inject `Lazy<T>`: see [Constructor parameters](/docs/reference/koin-core/definitions#constructor-parameters).

## Decorator pattern

A decorator wraps an implementation to add behavior (logging, caching, rate limiting) and exposes the same interface. Koin has no decorator keyword: register the inner implementation under its own type, and bind the interface to the outer decorator.

```kotlin
interface NotificationService {
    fun send(message: String)
}

class PushNotificationService : NotificationService { ... }

class LoggingNotificationService(
    private val delegate: NotificationService,
    private val logger: Logger,
) : NotificationService {
    override fun send(message: String) {
        logger.log("Sending: $message")
        delegate.send(message)
    }
}
```

**Compiler Plugin DSL**
```kotlin
import org.koin.plugin.module.dsl.create

fun loggingNotifications(
    push: PushNotificationService,
    logger: Logger,
): NotificationService = LoggingNotificationService(push, logger)

val notificationModule = module {
    single<Logger>()
    single<PushNotificationService>()
    single { create(::loggingNotifications) }
}
```

**Annotations**
```kotlin
@Module
class NotificationModule {

    @Singleton
    fun notifications(push: PushNotificationService, logger: Logger): NotificationService =
        LoggingNotificationService(push, logger)
}
```

Declare `PushNotificationService` with `@Singleton(binds = [])`, so it is not bound to `NotificationService` as well.

**Constructor / Classic DSL**
```kotlin
val notificationModule = module {
    singleOf(::Logger)
    singleOf(::PushNotificationService)
    single<NotificationService> {
        LoggingNotificationService(delegate = get<PushNotificationService>(), logger = get())
    }
}
```

Consumers ask for `NotificationService` and get the decorated instance. To stack several decorators, nest them in the same function: `RateLimitedNotificationService(LoggingNotificationService(push, logger), limiter)`.

The inner implementation must not be bound to the interface too. Otherwise two definitions answer for `NotificationService` and one overrides the other.

## Related

- [Definitions](/docs/reference/koin-core/definitions): definition types, binding, classes you don't own.
- [Qualifiers](/docs/reference/koin-core/qualifiers): `named()`, type qualifiers and `@Named`.
- [Injected Parameters](/docs/reference/koin-core/injection-parameters): runtime values passed at resolution.
- [Injection](/docs/reference/koin-core/injection): `get()`, `getAll()`, `inject()` outside constructors.
- [Troubleshooting](/docs/reference/koin-core/troubleshooting): override and missing definition errors.

---

# Lazy Modules

Source: https://insert-koin.io/docs/reference/koin-core/lazy-modules

A lazy module is a module that Koin registers in a background coroutine instead of during `startKoin`. This page covers declaring lazy modules, loading them in parallel, waiting for them, and the limits of the feature. It assumes you know [modules](/docs/reference/koin-core/modules) and [starting Koin](/docs/reference/koin-core/starting-koin).

## Dependency

Lazy modules are in the `koin-core-coroutines` artifact:

```kotlin
// build.gradle.kts
implementation("io.insert-koin:koin-core-coroutines")
```

## Declaring a lazy module

`lazyModule` takes the same content as `module`. Nothing is created or allocated until Koin loads it.

**Compiler Plugin DSL**
```kotlin
import org.koin.dsl.lazyModule
import org.koin.plugin.module.dsl.*

val analyticsModule = lazyModule {
    single<AnalyticsService>()
    single<EventTracker>()
}
```

**Annotations**
Annotation modules (`@Module`) are loaded at start and cannot be declared lazy. To load some definitions in the background, declare them in a `lazyModule` with any DSL form (Compiler Plugin, Constructor or Classic DSL).

**Constructor / Classic DSL**
```kotlin
import org.koin.dsl.lazyModule
import org.koin.core.module.dsl.*

val analyticsModule = lazyModule {
    singleOf(::AnalyticsService)
    singleOf(::EventTracker)
}
```

A lazy module can include other lazy modules:

```kotlin
val dataModule = lazyModule {
    single<UserRepository>()
}

val featureModule = lazyModule {
    includes(dataModule)
    single<FeatureService>()
}
```

## Loading lazy modules

Pass lazy modules to `lazyModules()` in `startKoin`. Modules in `modules()` load on the calling thread, before `startKoin` returns. Lazy modules load in background coroutines:

```kotlin
startKoin {
    modules(coreModule)
    lazyModules(analyticsModule, reportingModule)
}
```

Since Koin 4.2, each lazy module loads in its own coroutine, so several lazy modules load in parallel. Before 4.2 they loaded one after the other.

`lazyModules()` sets up the Koin coroutines engine if needed. It runs on the platform default dispatcher (`Dispatchers.Default` on JVM and Native). To choose another one, pass `dispatcher`:

```kotlin
startKoin {
    lazyModules(databaseModule, networkModule, dispatcher = Dispatchers.IO)
}
```

The dispatcher is set when the coroutines engine is created, by the first `lazyModules()` call. A `dispatcher` passed in a later call has no effect.

## Waiting for lazy modules

A definition from a lazy module is not available until its module is loaded. Wait for loading to finish before you resolve it:

| Function | Platform | Behavior |
|----------|----------|----------|
| `Koin.awaitAllStartJobs()` | All | Suspends until every lazy module is loaded |
| `Koin.onKoinStarted { koin -> }` | All | Suspends until loaded, then runs the block |
| `Koin.waitAllStartJobs()` | All | Blocks the thread until loaded. On JS, it does not block and logs a warning |
| `Koin.runOnKoinStarted { koin -> }` | JVM | Blocks until loaded, then runs the block |
| `Koin.isAllStartedJobsDone()` | All | Returns `true` when every lazy module is loaded |

From a coroutine:

```kotlin
suspend fun trackAppStart() {
    val koin = KoinPlatform.getKoin()
    koin.awaitAllStartJobs()
    koin.get<AnalyticsService>().trackAppStart()
}
```

From blocking code:

```kotlin
startKoin {
    lazyModules(analyticsModule)
}

KoinPlatform.getKoin().waitAllStartJobs()
val analytics = KoinPlatform.getKoin().get<AnalyticsService>()
```

:::warning
Do not call `waitAllStartJobs()` on the Android main thread during startup: it blocks the UI until every lazy module is loaded, which cancels the benefit. Wait from a coroutine instead.
:::

## Android example

Load what the first screen needs with `modules()`, and the rest in the background:

```kotlin
class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        startKoin {
            androidContext(this@MainApplication)
            modules(coreModule)
            lazyModules(analyticsModule, databaseModule, dispatcher = Dispatchers.IO)
        }
    }
}
```

Good candidates for lazy modules: analytics, crash reporting, features behind a navigation step, and definitions with a costly module body. Keep in `modules()` anything the first screen resolves.

## Limits

- **No dependency from regular to lazy modules**: if a definition in a regular module depends on a definition in a lazy module, resolving it before the lazy module is loaded fails with `NoDefinitionFoundException`. Koin does not check this for you.
- **Lazy modules load at start**: `lazyModules()` starts loading right away in the background. It does not load modules on first use.
- **Module registration only**: lazy loading moves module registration off the main thread. A `single` is still created on first request, on the thread that asks for it. Avoid `createdAtStart` in a lazy module: Koin creates eager instances at the end of `startKoin`, so a lazy module that is not loaded yet misses that step.
- **No annotations**: `@Module` classes cannot be lazy.

:::tip
To measure how long startup and module loading take on real devices, see [Production Monitoring](/docs/tooling/production-monitoring).
:::

## Related

- [Modules](/docs/reference/koin-core/modules): module declaration and `includes()`.
- [Starting Koin](/docs/reference/koin-core/starting-koin): `startKoin` and the application DSL.
- [Definitions](/docs/reference/koin-core/definitions#eager-creation): `createdAtStart` and eager creation.
- [Android Setup](/docs/reference/koin-android/start): starting Koin in an Android `Application`.
- [DSL Reference](/docs/reference/koin-core/dsl): every DSL keyword.

---

# Context Isolation

Source: https://insert-koin.io/docs/reference/koin-core/context-isolation

An isolated context is a Koin container that is not registered in the global context. This page shows how to create one for an SDK or a library, how to make your classes resolve from it, and how to test it. It assumes you know [how to start Koin](/docs/reference/koin-core/starting-koin).

## Why isolate

`startKoin` registers one container in the global context (`GlobalContext`). Every `KoinComponent` and every `by inject()` reads from it, and a second `startKoin` call fails with `KoinApplicationAlreadyStartedException`.

If your library calls `startKoin`, it fights with the host application for that single slot, and its definitions can override the app's ones. A library should create its own container with `koinApplication` instead and keep it private.

## Creating an isolated context

`koinApplication` builds a container with the same DSL as `startKoin`, without registering it globally. Keep it in an object of your SDK:

**Compiler Plugin DSL**
```kotlin
import org.koin.dsl.koinApplication
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*

internal val sdkModule = module {
    single<SdkRepository>()
    single<SdkService>()
}

internal object SdkKoinContext {
    val koinApp = koinApplication {
        modules(sdkModule)
    }
    val koin = koinApp.koin
}
```

**Annotations**
```kotlin
import org.koin.plugin.module.dsl.koinApplication

@Module
@ComponentScan("com.example.sdk")
internal class SdkModule

@KoinApplication(modules = [SdkModule::class])
internal object SdkApplication

internal object SdkKoinContext {
    val koinApp = koinApplication<SdkApplication>()
    val koin = koinApp.koin
}
```

`koinApplication<T>()` loads the modules of the `@KoinApplication` class, like `startKoin<T>()`, but does not register the container globally. List the SDK modules explicitly, so the SDK container does not pick up `@Configuration` modules from the host app.

**Constructor / Classic DSL**
```kotlin
import org.koin.dsl.koinApplication
import org.koin.dsl.module
import org.koin.core.module.dsl.*

internal val sdkModule = module {
    singleOf(::SdkRepository)
    singleOf(::SdkService)
}

internal object SdkKoinContext {
    val koinApp = koinApplication {
        modules(sdkModule)
    }
    val koin = koinApp.koin
}
```

The `object` creates the container on first access. To control when it starts and stops (an `init()` and `shutdown()` in your SDK API), create it in a function and call `koinApp.close()` on shutdown.

## Resolving from the isolated context

`KoinComponent` reads from the global context by default. Override `getKoin()` in an internal interface, and use that interface in your SDK classes:

```kotlin
internal interface SdkKoinComponent : KoinComponent {
    override fun getKoin(): Koin = SdkKoinContext.koin
}

class SdkClient : SdkKoinComponent {
    // resolved from SdkKoinContext, never from the host app
    private val service: SdkService by inject()
}
```

Classes created by Koin get their dependencies through the constructor, from the container that creates them. Only the entry points of your SDK (the classes the host app instantiates) need `SdkKoinComponent`.

## Testing

In a test, point `getKoin()` at the isolated context and load test modules into it:

```kotlin
class SdkClientTest : KoinTest {

    private val testModule = module {
        single<SdkService> { FakeSdkService() }
    }

    override fun getKoin(): Koin = SdkKoinContext.koin

    @Before
    fun setUp() {
        getKoin().loadModules(listOf(testModule))
    }

    @After
    fun tearDown() {
        getKoin().unloadModules(listOf(testModule))
    }
}
```

`testModule` is loaded after `sdkModule`, so its `SdkService` overrides the real one. More on tests in [Testing](/docs/reference/koin-test/testing).

## Platform support

Compose and Ktor have their own APIs to use an isolated context:

- **Compose**: `KoinIsolatedContext` provides an isolated container to a composable tree. See [Isolated Context in Compose](/docs/reference/koin-compose/isolated-context).
- **Ktor**: the `KoinIsolated` plugin runs a server with its own container. See [Isolated Context in Ktor](/docs/reference/koin-ktor/ktor-isolated).

## Limits

- **No global helpers**: top-level functions that use the global context, such as `GlobalContext.get()`, `KoinPlatform.getKoin()` or the default Android `by inject()` in an Activity, do not see the isolated container. Use your `SdkKoinComponent` instead.
- **Lifecycle is yours**: Koin does not close an isolated context. Call `koinApp.close()` when your SDK shuts down.
- **No sharing by default**: the isolated container does not see the host app's definitions. Pass what you need from the host through your SDK API, for example in `init(context)`.

## Related

- [Starting Koin](/docs/reference/koin-core/starting-koin): `startKoin`, `koinApplication` and the application DSL.
- [Koin Component](/docs/reference/koin-core/koin-component): `KoinComponent` and `getKoin()`.
- [Isolated Context in Compose](/docs/reference/koin-compose/isolated-context): `KoinIsolatedContext`.
- [Isolated Context in Ktor](/docs/reference/koin-ktor/ktor-isolated): the `KoinIsolated` plugin.
- [Testing](/docs/reference/koin-test/testing): `KoinTest` and test modules.

---

# Extension Manager

Source: https://insert-koin.io/docs/reference/koin-core/extension-manager

Koin has two extension points for library and framework authors. A `KoinExtension` attaches a feature to a Koin container, with a hook at registration and at close. A `ResolutionExtension` gives Koin another source of instances when no definition matches. Most applications never need either: use [definitions](/docs/reference/koin-core/definitions) first.

## KoinExtension

A `KoinExtension` is an object registered in the container under an id:

```kotlin
interface KoinExtension {
    fun onRegister(koin: Koin)
    fun onClose()
}
```

Koin calls `onRegister` when you register the extension, and `onClose` when the container closes (`stopKoin()` or `koinApplication.close()`).

Koin uses this mechanism itself: the coroutines engine behind [lazy modules](/docs/reference/koin-core/lazy-modules) is the `KoinCoroutinesEngine` extension.

### Writing an extension

```kotlin
class AuditExtension : KoinExtension {
    private lateinit var koin: Koin

    override fun onRegister(koin: Koin) {
        this.koin = koin
    }

    override fun onClose() {
        // release resources
    }

    fun record(event: String) { ... }
}
```

### Registering and reading it

Expose a function on `KoinApplication` to register the extension, and a property on `Koin` to read it back:

```kotlin
private const val AUDIT_EXTENSION = "audit"

fun KoinApplication.audit() {
    with(koin.extensionManager) {
        if (getExtensionOrNull<AuditExtension>(AUDIT_EXTENSION) == null) {
            registerExtension(AUDIT_EXTENSION, AuditExtension())
        }
    }
}

val Koin.audit: AuditExtension
    get() = extensionManager.getExtension(AUDIT_EXTENSION)
```

```kotlin
startKoin {
    audit()
    modules(appModule)
}

getKoin().audit.record("app_started")
```

| Function | Behavior |
|----------|----------|
| `registerExtension(id, extension)` | Stores the extension and calls `onRegister`. An extension with the same id is replaced |
| `getExtension<T>(id)` | Returns the extension. Fails with "Koin extension 'id' not found." if it is missing |
| `getExtensionOrNull<T>(id)` | Returns the extension, or `null` |

:::warning
`ExtensionManager` is marked `@KoinInternalApi`: you need to opt in, and the API may change between versions without a deprecation cycle.
:::

## ResolutionExtension

A `ResolutionExtension` is asked for an instance when nothing else matches: after the definitions of the current scope, the scope source and the linked scopes, including the root scope.

```kotlin
interface ResolutionExtension {
    val name: String
    fun resolve(scope: Scope, instanceContext: ResolutionContext): Any?
}
```

Return the instance for `instanceContext.clazz` (and `instanceContext.qualifier` if you use qualifiers), or `null` to let Koin continue and fail with `NoDefinitionFoundException`.

Koin uses this to read instances from Ktor's dependency injection in the [Ktor DI bridge](/docs/reference/koin-ktor/ktor-bridge).

### Example: instances from another container

```kotlin
class LegacyContainerResolution(
    private val legacy: Map<KClass<*>, Any>,
) : ResolutionExtension {

    override val name: String = "legacy-container"

    override fun resolve(scope: Scope, instanceContext: ResolutionContext): Any? =
        legacy[instanceContext.clazz]
}
```

Register it with `addResolutionExtension`, on the `koin` of the application:

```kotlin
@OptIn(KoinExperimentalAPI::class)
fun startApp(legacy: Map<KClass<*>, Any>) {
    startKoin {
        koin.addResolutionExtension(LegacyContainerResolution(legacy))
        modules(appModule)
    }
}
```

A definition in `appModule` that needs a type found only in the legacy map now gets it from the extension.

With the Compiler Plugin, a type that only an extension provides is unknown at build time, so compile-time safety reports it as missing. Mark it as provided: see [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety).

`addResolutionExtension` is marked `@KoinExperimentalAPI`.

## Limits

- **Internal and experimental APIs**: both extension points can change between Koin versions.
- **No lifecycle for resolution extensions**: Koin does not cache the instances a `ResolutionExtension` returns. Cache them yourself if needed.
- **Last in line**: a resolution extension is never asked when a definition matches. It cannot override a definition.
- **Thread safety**: `resolve` can be called from several threads at once.

## Related

- [Lazy Modules](/docs/reference/koin-core/lazy-modules): the feature built on the coroutines engine extension.
- [Ktor DI Bridge](/docs/reference/koin-ktor/ktor-bridge): a resolution extension in practice.
- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): declaring dependencies provided outside Koin.
- [Starting Koin](/docs/reference/koin-core/starting-koin): the application DSL where extensions are registered.
- [Scopes](/docs/reference/koin-core/scopes): resolution order inside a scope.

---

# Compile-Time Safety

Source: https://insert-koin.io/docs/reference/koin-compiler/compile-safety

The Koin Compiler Plugin checks your dependency graph while your code compiles. A missing definition, a wrong qualifier or a circular dependency fails the build, with the file and line, instead of crashing at runtime. This page covers what is checked, the exact diagnostics, and the cases the plugin cannot check. It assumes the plugin is installed (see [Compiler Plugin Setup](/docs/setup/compiler-plugin)).

Compile-time safety is enabled by default (`compileSafety = true`, see [Compiler Plugin Options](/docs/reference/koin-annotations/options)).

## Where the checks run

The plugin checks at two levels.

**Full graph**: at each Koin entry point, the plugin assembles every module that the entry point loads, from your sources and from dependency JARs, and checks every definition against that complete graph.

**Call sites**: every `get<T>()`, `inject<T>()`, `koinInject<T>()`, `koinViewModel<T>()`, `by viewModel()` and similar call is checked: `T` must exist in the assembled graph. If a feature module makes the call but cannot see the full graph, the plugin leaves a hint in the compiled module. The app module reads these hints from its dependencies and checks them when it compiles.

Recognized entry points:

| Entry point | Example |
|-------------|---------|
| `startKoin` | `startKoin<MyApp>()`, `startKoin { modules(appModule) }` |
| `koinApplication` | `koinApplication { modules(appModule) }` |
| `koinConfiguration` | `koinConfiguration<MyApp>()` |
| `@KoinApplication` | `@KoinApplication object MyApp` |
| `withConfiguration<T>()` | `startKoin { withConfiguration<MyApp>() }` |
| Ktor `install(Koin)` | `install(Koin) { modules(appModule) }` |

`modules(...)` accepts lists the plugin can follow: `listOf(...)`, `+`, `.toList()`, a top-level `val`, or a function returning `List<Module>`:

```kotlin
val dataModules = listOf(databaseModule, networkModule)
fun featureModules(): List<Module> = listOf(loginModule, profileModule)

startKoin {
    modules(dataModules + featureModules())
}
```

A module declared as a function (`fun dataModule(): Module = module { ... }`) is followed like a top-level `val`.

:::note
A Gradle module with no entry point of its own (a library, most feature modules) gets no missing-dependency diagnostics in its own compilation. A module checked alone cannot know how the app will wire it. Its definitions are checked when the app module assembles the graph. The plugin says so in the build output:

```
[Koin] compile-safety validation skipped — no Koin entry point in this compilation.
```
:::

## What is checked

| Case | Result |
|------|--------|
| Non-nullable parameter, no definition | Error |
| Nullable parameter (`T?`), no definition | OK, resolved with `getOrNull()` |
| Parameter with a default value, no definition | OK, uses the Kotlin default (with `skipDefaultValues = true`) |
| Parameter with a default value and a qualifier (`@Named`) | Error, the qualifier forces resolution |
| `@InjectedParam` parameter | OK, passed at runtime with `parametersOf()` |
| `@Property("key")` parameter | OK. Warning if no `@PropertyValue("key")` default exists |
| `List<T>` parameter | OK, `getAll()` returns an empty list if nothing matches |
| `Lazy<T>`, no definition for `T` | Error, the inner type is checked |
| `@Named("x")` parameter, no definition with that qualifier | Error, with a hint if the type exists with another qualifier |
| Scoped dependency declared in another scope | Error |
| Circular dependency (A needs B, B needs A) | Error |
| `@Provided` type or parameter | OK, provided outside the graph |
| `@ScopeId` parameter | OK, resolved from a named scope at runtime |
| `Scope` parameter | OK, the current scope is passed |
| Android framework type (`Context`, `SavedStateHandle`, ...) | OK, built-in list |
| `get<T>()` / `inject<T>()` with no definition for `T` | Error |
| `get<T>()` without `parametersOf()` when `T` has `@InjectedParam` | Error |
| `parametersOf(...)` with the wrong count or types | Error |

The rules for how each parameter type is resolved are on [Definitions](/docs/reference/koin-core/definitions#constructor-parameters).

## Checks per declaration style

Every style and DSL form is checked against the same graph. They can live in one project: a DSL definition can depend on an annotated class, and the other way around.

**Compiler Plugin DSL**
```kotlin
val appModule = module {
    single<Database>()
    single<UserRepository>()      // checked: Database exists
    viewModel<UserViewModel>()    // checked: UserRepository exists
}
```

The plugin reads the constructor, generates the resolution calls and checks every parameter. `create(::function)` is checked the same way, on the function parameters:

```kotlin
fun buildUserRepository(db: Database): UserRepository = UserRepository(db)

val appModule = module {
    single { create(::buildUserRepository) }    // checked: Database exists
}
```

**Annotations**
```kotlin
@Singleton
class Database

@Singleton
class UserRepository(private val db: Database)    // checked: Database exists

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

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

@KoinApplication(modules = [AppModule::class])
object MyApp
```

`startKoin<MyApp>()` is the entry point: the plugin checks every definition found by `@ComponentScan`. Annotated top-level functions are checked like classes:

```kotlin
@Factory
fun provideCache(db: Database): CacheService = RedisCache(db)    // checked: Database exists
```

Modules tagged with `@Configuration` are assembled with the `@KoinApplication` that requests their label, across Gradle modules, and checked together.

**Constructor / Classic DSL**
Constructor references are checked like the Compiler Plugin DSL:

```kotlin
val appModule = module {
    singleOf(::Database)
    singleOf(::UserRepository)        // checked: Database exists
    viewModelOf(::UserViewModel)      // checked: UserRepository exists
    scope<UserSession> {
        scopedOf(::SessionCache)
    }
}
```

`singleOf`, `factoryOf`, `scopedOf`, `viewModelOf` and `new(::T)` keep their runtime behavior. The plugin adds the checks, it does not rewrite them.

For a lambda you write yourself, the plugin does not read the constructor. It checks the `get()`, `inject()` and `getOrNull()` calls inside the lambda, like any call site:

```kotlin
val appModule = module {
    single { UserRepository(get()) }  // checked: the get() call needs Database
}
```

:::warning
Since Compiler Plugin 1.2.0, `singleOf`, `factoryOf`, `scopedOf` and `viewModelOf` are checked. Code that relied on a missing dependency in these functions no longer compiles. The build was hiding a runtime crash.
:::

## Diagnostics

Every diagnostic has a stable code, printed as `[Koin][CODE]`. Search for the code or the first line of the message.

### Missing dependency (KOIN-D001)

A definition parameter has no definition in the graph:

```
[Koin][KOIN-D001] Missing dependency: com.myapp.Database
  required by: com.myapp.UserRepository (parameter 'db')
  in module: com.myapp.AppModule
```

For a DSL definition, `required by:` starts with `dsl:`. When the type exists with another qualifier, a hint follows:

```
[Koin][KOIN-D001] Missing dependency: com.myapp.NetworkClient qualified with @Named("http")
  required by: com.myapp.ApiService (parameter 'client')
  in module: com.myapp.AppModule
  Hint: Found similar binding: com.myapp.NetworkClient (no qualifier)
```

Fix: declare the missing definition, add the module that declares it to `modules()` or `includes()`, or fix the qualifier (see [Qualifiers](/docs/reference/koin-core/qualifiers)).

### Missing definition at a call site (KOIN-D002, KOIN-D003)

A `get<T>()`, `inject<T>()` or `koinViewModel<T>()` call asks for a type that no loaded module declares:

```
[Koin][KOIN-D002] Missing definition: com.myapp.Tracker
  resolved by: get<Tracker>()
  No matching definition found in any loaded module.
  Check your declaration with Annotation or DSL.
```

`KOIN-D003` is the same error for a call made in a dependency module, reported when the app module compiles. Its second line reads `required by a call site in a dependency module`.

### Circular dependency (KOIN-D004)

```
[Koin][KOIN-D004] Circular dependency detected:
  com.myapp.A → com.myapp.B → com.myapp.A
  Break with Lazy<T> injection or refactor to remove the cycle.
```

A `Lazy<T>`, nullable, `List<T>`, `@InjectedParam`, `@Provided`, `@Property`, `@ScopeId` or default-valued parameter does not count as an edge in the cycle. Changing one parameter to `Lazy<T>` breaks the cycle. See [Troubleshooting](/docs/reference/koin-core/troubleshooting) for ways to remove it.

### Injected parameters (KOIN-D005, KOIN-D006)

The definition declares `@InjectedParam` parameters, and the call site does not pass them:

```
[Koin][KOIN-D006] com.myapp.Greeter requires 1 injected param(s) but get<Greeter>() has no parametersOf(...) at the call site.
  Expected @InjectedParam slots: name: kotlin.String
  Pass them via parametersOf(...) inside the trailing lambda.
```

`KOIN-D005` reports a `parametersOf(...)` with the wrong number of arguments or the wrong types (`Mismatched parametersOf(...) for ...`). Both checks only run when the call contains a `parametersOf(...)` the plugin can read. See [Injected Parameters](/docs/reference/koin-core/injection-parameters).

### Unsupported suspend binding (KOIN-D007)

A definition whose type extends a suspend function type is rejected, because Koin cannot resolve it at runtime:

```kotlin
fun interface SetUsernameUseCase : suspend (String) -> Unit

@Factory
fun provideSetUsernameUseCase(repository: UserRepository): SetUsernameUseCase =
    SetUsernameUseCase(repository::setUsername)
```

```
[Koin][KOIN-D007] Unsupported binding: com.myapp.SetUsernameUseCase extends kotlin.coroutines.SuspendFunction1
  Suspend function injection is not yet supported by Koin runtime.
  Remove the @Single / @Factory / @Scoped registration, or refactor the binding type to not extend a suspend function.
  Tracked at https://github.com/InsertKoinIO/koin-compiler-plugin/issues/16
```

Fix: use a regular interface with a `suspend` method, or a class.

### All codes

| Code | Severity | Message starts with |
|------|----------|---------------------|
| `KOIN-D001` | Error | `Missing dependency:` |
| `KOIN-D002` | Error | `Missing definition:` (call site in this module) |
| `KOIN-D003` | Error | `Missing definition:` (call site in a dependency module) |
| `KOIN-D004` | Error | `Circular dependency detected:` |
| `KOIN-D005` | Error | `Mismatched parametersOf(...) for` |
| `KOIN-D006` | Error | `<Type> requires N injected param(s) but` |
| `KOIN-D007` | Error | `Unsupported binding:` |
| `KOIN-D008` | Error | `Module id collision:` (two module names encode to the same hint name: rename one) |
| `KOIN-W001` | Warning | `Module '<name>' is not loaded at startKoin` |
| `KOIN-W003` | Warning | `Graph not verifiable at compile time:` |
| `KOIN-W004` | Warning | `Custom @Configuration label '<label>' requested by` |
| `KOIN-W005` | Warning | `Definition '<name>' in dependency module` |
| `KOIN-W006` | Warning | `<definition>'s bind(...) argument could not be resolved` |
| `KOIN-A001` | Error | `@KoinViewModel definition '<name>' cannot be generated` (add `io.insert-koin:koin-core-viewmodel`) |
| `KOIN-A002` | Error | `@KoinWorker definition '<name>' cannot be generated` (add `io.insert-koin:koin-android-workmanager`) |
| `KOIN-A003` | Error | `Cannot generate <Module>.module()` (add `io.insert-koin:koin-core`) |
| `KOIN-S001` | Error | `create(::<Type>) must be the only instruction in the lambda` (see [unsafeDslChecks](/docs/reference/koin-annotations/options#unsafedslchecks)) |
| `KOIN-P001` | Warning | `Missing @PropertyValue default:` |
| `KOIN-M001` | Warning | `@Monitor: Kotzilla SDK not found on classpath` |

The warnings describe what the plugin could not check. `KOIN-W003`, `KOIN-W004` and `KOIN-W005` are covered in [Limits](#limits). `KOIN-W006` means a `bind`/`binds` argument is not a literal `X::class` (or a literal array or list of them): use a literal.

## External types: `@Provided`

Some types reach your graph from outside Koin's declarations: a platform object, an SDK instance, a definition added by hand at runtime. Mark them `@Provided` so the plugin does not report them as missing:

```kotlin
// on a class: every use of this type is skipped
@Provided
class FirebaseAnalytics

// on a parameter: only this parameter is skipped
@Singleton
class PaymentProcessor(@Provided val gateway: PaymentGateway)
```

`@Provided` (`org.koin.core.annotation`) works with every declaration style: annotate the class or the constructor parameter, even when the definition is in a DSL module. It only changes the compile-time check. At runtime the type is still resolved with `get()`, and fails if nobody declared it. Prefer the parameter form: on a class, it turns off the check for every use of that type.

These types are always accepted, without `@Provided`:

- `android.content.Context`
- `android.app.Application`
- `android.app.Activity`
- `androidx.activity.ComponentActivity`
- `androidx.fragment.app.Fragment`
- `androidx.lifecycle.SavedStateHandle`
- `androidx.work.WorkerParameters`

### Modules loaded at runtime

A module loaded with `loadKoinModules(...)` after `startKoin` is not part of the graph the plugin assembles. The plugin cannot know when, or if, that call runs. Types that only come from such a module must be `@Provided`:

```kotlin
val featureModule = module { single<Repository>() }   // loaded later
val appModule = module { single<Service>() }          // Service(@Provided val repo: Repository)

startKoin { modules(appModule) }
loadKoinModules(featureModule)
```

The plugin still reports the runtime-loaded module as unreachable with `KOIN-W001`. Adding it to `modules()` would defeat on-demand loading, so you can ignore this warning (it fails the build only with `allWarningsAsErrors`).

## Special parameters

**Scope**: a parameter of type `org.koin.core.scope.Scope` receives the current scope. It is not checked, since the code resolves types from it dynamically.

```kotlin
@Scoped
class ScopedService(val scope: Scope) {
    fun load() = scope.get<SomeDependency>()
}
```

**@ScopeId**: the parameter is resolved from another scope, by name (`@ScopeId(name = "user_session")`) or by type (`@ScopeId(UserSessionScope::class)`, the scope ID is the full class name). It is not checked, since that scope exists only at runtime. See [Scopes](/docs/reference/koin-core/scopes).

**@Property**: the parameter reads a Koin property. If no `@PropertyValue("key")` default is declared, the build gets a warning, and the property must be set at startup:

```kotlin
@PropertyValue("api.timeout")
val defaultTimeout = 30

@Factory
class ApiClient(@Property("api.timeout") val timeout: Int)    // OK

@Factory
class Other(@Property("missing.key") val value: String)
// [Koin][KOIN-P001] Missing @PropertyValue default: "missing.key" ...
```

**Default values**: with `skipDefaultValues = true` (default), a parameter with a Kotlin default value uses it and is not checked. See [skipDefaultValues](/docs/reference/koin-annotations/options#skipdefaultvalues).

## Generic types

Koin resolves definitions on the erased class: type arguments are not part of the lookup key. The plugin follows the same rule. `get<Box<Int>>()` is checked against any `Box` definition, and `single<Box<A>>()` and `single<Box<B>>()` are the same definition, so the second overrides the first.

To keep several instances of one generic type, give each one a type qualifier derived from its type argument with `named<T>()`. The pattern is described in [Advanced Patterns](/docs/reference/koin-core/advanced-patterns).

## Incremental builds

The full-graph check runs when the aggregator module (the one with the entry point) compiles. Kotlin incremental compilation can skip that module after a change elsewhere, for example inside a `module { }` lambda body. The plugin turns on `strictSafety` in modules where it detects an entry point, so the check runs on every build. Details and escape hatch: [strictSafety](/docs/reference/koin-annotations/options#strictsafety).

## Limits

- **Dynamic module lists**: `modules(if (debug) a else b)`, `modules(*list)` or a list built at runtime cannot be followed. The plugin reports `KOIN-W003` and skips the full-graph check for that entry point. Pass modules directly to keep the check.
- **Hand-written lambdas and cycles**: a `single { A(get()) }` lambda adds no edge to the cycle check, so a circular dependency through hand-written lambdas is not detected. Use `single<T>()`, `singleOf(::T)` or `create(::T)` where cycles matter.
- **Custom configuration labels**: modules tagged with a label other than `"default"` are discovered at most one `implementation` dependency away (`KOIN-W004`). Add a direct dependency, or list the module in `@KoinApplication(modules = [...])`.
- **Function definitions far away**: a `@Module` function definition, or a qualified top-level function, in a module two or more `implementation` hops away is not visible to the check (`KOIN-W005`). It still works at runtime. Add a direct dependency to check it.
- **Runtime-loaded modules**: see [Modules loaded at runtime](#modules-loaded-at-runtime).

## Replacing verify() and checkModules()

With compile-time safety on, the build checks what `verify()` and `checkModules()` tests check, on every compilation. You can remove those tests for graphs the plugin fully checks. Keep them for graphs the plugin reports as not verifiable (`KOIN-W003`) or that use runtime-loaded modules. See [Verifying modules](/docs/reference/koin-test/verify).

## Related

- [Compiler Plugin Options](/docs/reference/koin-annotations/options): `compileSafety`, `strictSafety`, `skipDefaultValues` and the other options.
- [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin): what the plugin does and how it works.
- [Definitions](/docs/reference/koin-core/definitions): how constructor parameters are resolved.
- [Troubleshooting](/docs/reference/koin-core/troubleshooting): runtime errors, the logger and circular dependencies.
- [IDE Plugin](/docs/tooling/ide-plugin): see the graph and navigate definitions in the IDE.
- [Playground apps](https://github.com/InsertKoinIO/koin-compiler-plugin/tree/main/playground-apps): sample apps with annotations (`app-annotations/`) and the DSL (`app-dsl/`).

---

# Troubleshooting

Source: https://insert-koin.io/docs/reference/koin-core/troubleshooting

This page lists the errors Koin reports, what causes them and how to fix them. It also covers the tools to find a problem before it reaches users, and the patterns that lead to these errors. The messages are quoted as Koin prints them, so you can search the page for the text of your stack trace.

## Find problems early

Koin gives you three ways to see a configuration error, from the earliest to the latest.

- **Compile time**: with the [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin), a missing dependency or a dependency cycle fails the build. The error names the definition, the parameter and the module. See [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety) for every check and error code.
- **In the IDE**: the [Koin IDE plugin](/docs/tooling/ide-plugin) shows where each definition is declared, where it is used and what is missing, while you write code.
- **In tests**: without the Compiler Plugin, call `verify()` on your modules in a JVM unit test. It checks that each constructor parameter has a definition. See [Verify your configuration](/docs/reference/koin-test/verify).

```kotlin
class ModuleCheckTest {

    @Test
    fun checkKoinModules() {
        appModule.verify()
    }
}
```

## Logging

Koin logs nothing by default (`EmptyLogger`). Turn logging on to see each definition load and each instance resolution:

```kotlin
startKoin {
    printLogger(Level.DEBUG)
    modules(appModule)
}
```

| Level | What you see |
|-------|--------------|
| `Level.DEBUG` | Every resolution, with the scopes Koin searched. Use it to understand a failure |
| `Level.INFO` | Startup summary, such as `Started 42 definitions in 1.2 ms`. The default for `printLogger()` |
| `Level.WARNING` | Warnings, such as a definition that overrides another |
| `Level.ERROR` | Errors only |
| `Level.NONE` | Nothing |

On Android, use `androidLogger(Level.DEBUG)` to write to Logcat. See [Starting Koin](/docs/reference/koin-core/starting-koin) for the logger options.

`Level.DEBUG` slows down resolution. Keep it for debugging sessions, not for release builds.

## Runtime errors

### No definition found

```
NoDefinitionFoundException: No definition found for type 'com.example.UserRepository' on scope '['_root_']'.
Check or add definition for type 'com.example.UserRepository' in scope '_root_'.
```

Koin was asked for a type that no loaded module declares. Check, in this order:

- **Module not loaded**: the definition exists but its module is not in `modules(...)` or in an `includes(...)`.
- **Missing qualifier**: the definition has a qualifier and the request has none, or the reverse. The message then contains `and qualifier '...'`. See [Qualifiers](/docs/reference/koin-core/qualifiers).
- **Interface not bound**: the definition declares `UserRepositoryImpl` and the request asks for `UserRepository`. Bind the interface, see [Definitions](/docs/reference/koin-core/definitions#interface-binding).
- **Wrong scope**: the definition is `scoped` in a scope, and the request comes from another scope or from the root. The message lists the searched scopes. See [Scopes](/docs/reference/koin-core/scopes).

For `SavedStateHandle`, the message says instead that it is provided by the ViewModel `CreationExtras`. Resolve the ViewModel with `koinViewModel()` or `by viewModel()` and take `SavedStateHandle` as a constructor parameter. See [ViewModel](/docs/reference/koin-core/viewmodel).

### Could not create instance

```
InstanceCreationException: Could not create instance for '[Singleton: 'com.example.UserRepository']'
```

Koin found the definition, but creating the instance threw an exception. The real cause is the nested exception (`Caused by:`) in the stack trace. Often it is a `NoDefinitionFoundException` for one of the constructor parameters, or an exception thrown by the constructor itself.

### Already existing definition

```
DefinitionOverrideException: Already existing definition for [Singleton: 'com.example.ApiService'] at com.example.ApiService::_root_
```

Two modules declare the same type and qualifier, and overriding is off (`allowOverride(false)`). Remove the duplicate, give it a [qualifier](/docs/reference/koin-core/qualifiers), or mark the intended one with `.override()`. See [Definitions](/docs/reference/koin-core/definitions#overriding-a-definition).

### Scope errors

| Message | Exception | Cause |
|---------|-----------|-------|
| `Scope 'user_session' is closed` | `ClosedScopeException` | The scope was closed and something still asks it for an instance. Often a callback or a coroutine that outlives the screen |
| `No scope found for id 'user_session'` | `ScopeNotCreatedException` | `getScope(id)` was called before `createScope(id, ...)`. Use `getOrCreateScope` or create the scope first |
| `Scope with id 'user_session' is already created` | `ScopeAlreadyCreatedException` | `createScope` was called twice with the same id |
| `No value for scope 'user_session' in [Scoped: ...]` | `MissingScopeValueException` | A scoped value declared with `declare()` was not provided for this scope |
| `Activity should implement AndroidScopeComponent` | `IllegalStateException` | An Android scope API was used in an Activity that has no scope. See [Android Scopes](/docs/reference/koin-android/scope) |

See [Scopes](/docs/reference/koin-core/scopes) for the scope lifecycle.

### Injected parameters

| Message | Exception | Cause |
|---------|-----------|-------|
| `Can't get injected parameter #0 from DefinitionParameters[] for type 'kotlin.String'` | `NoParameterFoundException` | The definition reads a parameter that the caller did not pass with `parametersOf(...)` |
| `No value found for type 'kotlin.String'` | `DefinitionParameterException` | `params.get<T>()` found no parameter of that type |

See [Injected Parameters](/docs/reference/koin-core/injection-parameters).

### Start and properties

| Message | Exception | Cause |
|---------|-----------|-------|
| `KoinApplication has not been started` | `IllegalStateException` | Code used the global context (`KoinComponent`, `by inject()`) before `startKoin`. On Android, check that your `Application` class is declared in the manifest |
| `A Koin Application has already been started` | `KoinApplicationAlreadyStartedException` | `startKoin` was called twice. In tests, call `stopKoin()` after each test |
| `Can't resolve Context instance. Please use androidContext() function in your KoinApplication configuration.` | `MissingAndroidContextException` | A definition uses `androidContext()` and `startKoin` has no `androidContext(this)` |
| `Property 'api_url' not found` | `MissingPropertyException` | `getProperty("api_url")` with no such property and no default value |
| `No properties found for file '/koin.properties'` | `NoPropertyFileFoundException` | `fileProperties()` could not find the file |

### Compiler Plugin not applied

```
NotImplementedError: Error while using 'single<T>()'. The Koin Compiler plugin is missing. Please fix your setup to use 'io.insert-koin.compiler.plugin' Koin Gradle Plugin.
```

The code uses the Compiler Plugin DSL (`single<T>()`, `factory<T>()`, `startKoin<T>()`) but the plugin is not applied to this Gradle module. See [Compiler Plugin Setup](/docs/setup/compiler-plugin).

## Circular dependencies

A cycle happens when two classes need each other in their constructors:

```kotlin
class SessionManager(private val authService: AuthService)
class AuthService(private val sessionManager: SessionManager)
```

With the Compiler Plugin, the build fails:

```
[Koin][KOIN-D004] Circular dependency detected:
  com.example.AuthService → com.example.SessionManager → com.example.AuthService
  Break with Lazy<T> injection or refactor to remove the cycle.
```

With `verify()`, the test fails with `Circular injection between ... Fix your Koin configuration!`.

Without those checks, Koin does not detect the cycle. Each class resolves the other until the call stack overflows, and the app crashes with a `StackOverflowError`.

### Break the cycle with Lazy

Make one side lazy, so it is resolved on first use and not during construction:

**Compiler Plugin DSL**
```kotlin
class AuthService(private val sessionManager: Lazy<SessionManager>)

val authModule = module {
    single<SessionManager>()
    single<AuthService>()
}
```

**Annotations**
```kotlin
@Singleton
class SessionManager(private val authService: AuthService)

@Singleton
class AuthService(private val sessionManager: Lazy<SessionManager>)
```

**Constructor / Classic DSL**
```kotlin
class AuthService(private val sessionManager: Lazy<SessionManager>)

val authModule = module {
    single { SessionManager(get()) }
    single { AuthService(inject()) }
}
```

`AuthService` must not read `sessionManager.value` in its constructor or `init` block, or the cycle comes back.

### Remove the cycle

A lazy parameter hides the problem but keeps the coupling. Most cycles mean that both classes share a responsibility. Move it to a third class that both depend on, or make one side depend on an interface that exposes only what it needs.

```kotlin
class TokenStore

class SessionManager(private val tokenStore: TokenStore)
class AuthService(private val tokenStore: TokenStore)
```

## Patterns that cause errors

**Resolving inside methods**: calling `get()` or `KoinComponent` inside a class body hides its dependencies. The Compiler Plugin cannot check them, and a missing definition fails only when the method runs. Prefer constructor parameters. See [KoinComponent](/docs/reference/koin-core/koin-component) for the cases where you need it.

```kotlin
// Hidden dependency, resolved late
class UserViewModel : ViewModel(), KoinComponent {
    fun loadUser() {
        val repository = get<UserRepository>()
    }
}

// Visible dependency, checked at build time
class UserViewModel(private val repository: UserRepository) : ViewModel()
```

**Creating dependencies yourself**: `private val api = ApiService()` inside a class bypasses Koin. The class can't be tested with a fake, and its dependencies are not checked.

**Qualifiers for different types**: a qualifier is only needed when several definitions provide the same type. `UserRepository` and `OrderRepository` are already different types.

**Work inside definitions**: a definition should create an object, not run logic. Side effects in a `single { }` lambda run at an unpredictable time (first use), and on the main thread for `createdAtStart`. Keep the work in the class, or move startup work to [Lazy Modules](/docs/reference/koin-core/lazy-modules).

**One module for the whole app**: a single large module is hard to override in tests and to load lazily. Split by feature or layer. See [Modules](/docs/reference/koin-core/modules).

**Scoped instances kept after close**: a reference to a scoped instance stored in a `single` or a static field keeps it alive after its scope closes, and later calls may hit `ClosedScopeException`. Inject scoped instances only into objects of the same scope or shorter.

:::tip
Some problems only show up on real devices: slow resolutions on startup, scopes that never close, crashes in rare paths. To see them in real user sessions, see [Production Monitoring](/docs/tooling/production-monitoring).
:::

## Related

- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): every build-time check and its error code.
- [Verify your configuration](/docs/reference/koin-test/verify): check modules in tests without the Compiler Plugin.
- [Starting Koin](/docs/reference/koin-core/starting-koin): logger and start options.
- [Scopes](/docs/reference/koin-core/scopes): scope lifecycle and closing.
- [IDE Plugin](/docs/tooling/ide-plugin): see your dependency graph while you code.

---

# Starting Koin on Android

Source: https://insert-koin.io/docs/reference/koin-android/start

This page shows how to start Koin in an Android app: the `Application` class, the Android `Context`, the Logcat logger, properties from assets, module loading after start, and AndroidX App Startup. It assumes the `io.insert-koin:koin-android` dependency is in your build (see [Gradle Setup](/docs/setup/gradle)). For what `startKoin` does on every platform, see [Starting Koin](/docs/reference/koin-core/starting-koin).

## Start Koin in your Application class

Start Koin once, in `Application.onCreate()`:

**Compiler Plugin DSL**
```kotlin
import org.koin.android.ext.koin.androidContext
import org.koin.android.ext.koin.androidLogger
import org.koin.core.context.startKoin

class MainApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        startKoin {
            androidLogger()
            androidContext(this@MainApplication)
            modules(appModule)
        }
    }
}
```

`appModule` is a `module { }` declared with the Compiler Plugin DSL (`single<UserRepository>()`, `viewModel<UserViewModel>()`).

**Annotations**
```kotlin
import org.koin.android.ext.koin.androidContext
import org.koin.android.ext.koin.androidLogger
import org.koin.core.annotation.KoinApplication
import org.koin.plugin.module.dsl.startKoin

@KoinApplication
class MainApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        startKoin<MainApplication> {
            androidLogger()
            androidContext(this@MainApplication)
        }
    }
}
```

`startKoin<MainApplication>()` loads every `@Module` class tagged with `@Configuration`. You don't list modules yourself. To pick modules explicitly, use `@KoinApplication(modules = [AppModule::class])`. Module discovery is explained in [Modules](/docs/reference/koin-core/modules).

**Constructor / Classic DSL**
```kotlin
import org.koin.android.ext.koin.androidContext
import org.koin.android.ext.koin.androidLogger
import org.koin.core.context.startKoin

class MainApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        startKoin {
            androidLogger()
            androidContext(this@MainApplication)
            modules(appModule)
        }
    }
}
```

Register the class in `AndroidManifest.xml` with `android:name=".MainApplication"` on the `<application>` tag, or Android never runs it.

`androidContext()` adds the `Application` instance to Koin, bound to both `Application` and `Context`. Call it before any option that needs a `Context`, such as `androidFileProperties()` or `workManagerFactory()`.

## Android Context in definitions

A class that needs a `Context` declares it in its constructor. No qualifier is needed: Koin resolves `Context` to the instance passed to `androidContext()`.

**Compiler Plugin DSL**
```kotlin
class PreferencesStore(private val context: Context)
class NotificationHelper(private val application: Application)

val androidModule = module {
    single<PreferencesStore>()
    single<NotificationHelper>()
}
```

**Annotations**
```kotlin
@Singleton
class PreferencesStore(private val context: Context)

@Singleton
class NotificationHelper(private val application: Application)
```

**Constructor / Classic DSL**
```kotlin
val androidModule = module {
    singleOf(::PreferencesStore)
    singleOf(::NotificationHelper)
}
```

In a lambda definition, read them with `androidContext()` and `androidApplication()`: `single { PreferencesStore(androidContext()) }`.

| Function | Returns | Fails when |
|----------|---------|------------|
| `androidContext()` | The closest `Context`: the `Application`, or the Activity in an Activity scope | No `androidContext()` was given at start (`MissingAndroidContextException`) |
| `androidApplication()` | Always the `Application` instance | No `Application` was given to `androidContext()` |

Both functions are shortcuts for `get<Context>()` and `get<Application>()`, from `org.koin.android.ext.koin`.

### Which Context you get

In a `single`, or any definition resolved from the root scope, `Context` is the `Application`. This is safe for objects that live as long as the app.

In a definition resolved from an Activity scope, `Context` resolves to the Activity first, because the Activity is the source of that scope. This is how a scoped presenter can get the Activity. See [Android Scopes](/docs/reference/koin-android/scope).

### Activity context

Don't declare an `Activity` as a dependency of a `single`: the singleton keeps the Activity alive after it is destroyed, and the Activity leaks. When a class needs the Activity (screen metrics, a dialog), create it in the Activity, pass the Activity as an [injected parameter](/docs/reference/koin-core/injection-parameters), or declare it in an Activity scope:

```kotlin
class ScreenMetrics(private val activity: Activity) {
    fun screenWidth(): Int = activity.resources.displayMetrics.widthPixels
}

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val metrics = ScreenMetrics(this)
    }
}
```

### Several instances of the same Android type

When two definitions share a type, such as two `SharedPreferences` files, tell them apart with a [qualifier](/docs/reference/koin-core/qualifiers):

**Compiler Plugin DSL**
```kotlin
val preferencesModule = module {
    single(named("settings")) {
        androidContext().getSharedPreferences("settings", Context.MODE_PRIVATE)
    }
    single(named("session")) {
        androidContext().getSharedPreferences("session", Context.MODE_PRIVATE)
    }
}
```

**Annotations**
```kotlin
@Module
class PreferencesModule {

    @Singleton
    @Named("settings")
    fun settings(context: Context): SharedPreferences =
        context.getSharedPreferences("settings", Context.MODE_PRIVATE)

    @Singleton
    @Named("session")
    fun session(context: Context): SharedPreferences =
        context.getSharedPreferences("session", Context.MODE_PRIVATE)
}
```

**Constructor / Classic DSL**
```kotlin
val preferencesModule = module {
    single(named("settings")) {
        androidContext().getSharedPreferences("settings", Context.MODE_PRIVATE)
    }
    single(named("session")) {
        androidContext().getSharedPreferences("session", Context.MODE_PRIVATE)
    }
}
```

## Logging

`androidLogger()` sends Koin logs to Logcat. The default level is `Level.INFO`:

```kotlin
startKoin {
    androidLogger(Level.DEBUG)
    androidContext(this@MainApplication)
    modules(appModule)
}
```

`Level.DEBUG` logs every resolution and its duration, which helps when you debug a missing definition. It also slows resolution down, so keep it for debug builds: `androidLogger(if (BuildConfig.DEBUG) Level.DEBUG else Level.ERROR)`. Other loggers are listed in [Starting Koin](/docs/reference/koin-core/starting-koin).

## Properties from assets

`androidFileProperties()` loads Koin properties from a file in `src/main/assets`. The default file name is `koin.properties`:

```kotlin
startKoin {
    androidContext(this@MainApplication)
    androidFileProperties()                  // assets/koin.properties
    // androidFileProperties("app.properties")
    modules(appModule)
}
```

It reads the file through the `Context`, so call it after `androidContext()`. If the file is missing, Koin logs it and continues. To read a property in a definition, see [Starting Koin](/docs/reference/koin-core/starting-koin).

## Loading modules after start

`loadKoinModules()` and `unloadKoinModules()` add or remove modules while the app runs. On Android, this fits a feature that is only used from a few screens:

```kotlin
private val premiumModules = lazy { loadKoinModules(premiumModule) }

class PremiumActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        premiumModules.value
        super.onCreate(savedInstanceState)
    }
}
```

- Load before `super.onCreate()`: Fragments restored by the system then find their dependencies.
- Load once per process: loading the same module again re-registers its definitions, logs an override warning, and fails if Koin runs with `allowOverride(false)`.
- Unload with care: `unloadKoinModules(premiumModule)` drops the module definitions and their instances. Unload only when the feature is no longer needed, never on a configuration change, and track the loaded state yourself if you load it again later.

## Lazy modules

On large apps, loading every module in `Application.onCreate()` adds to startup time on the main thread. `lazyModules()` loads the modules you mark with `lazyModule { }` on a background thread, while the modules needed for the first screen load with `modules()`. Setup, waiting for completion and limits are in [Lazy Modules](/docs/reference/koin-core/lazy-modules).

## Start with AndroidX App Startup

[AndroidX App Startup](https://developer.android.com/topic/libraries/app-startup) runs initializers from one ContentProvider, before `Application.onCreate()`. The `io.insert-koin:koin-androidx-startup` artifact starts Koin as one of those initializers. Implement `KoinStartup` in your `Application` and return the configuration from `onKoinStartup()`:

**Compiler Plugin DSL**
```kotlin
import org.koin.androix.startup.KoinStartup
import org.koin.dsl.koinConfiguration

@OptIn(KoinExperimentalAPI::class)
class MainApplication : Application(), KoinStartup {

    override fun onKoinStartup() = koinConfiguration {
        androidContext(this@MainApplication)
        modules(appModule)
    }
}
```

**Annotations**
```kotlin
import org.koin.androix.startup.KoinStartup
import org.koin.plugin.module.dsl.koinConfiguration

@KoinApplication
@OptIn(KoinExperimentalAPI::class)
class MainApplication : Application(), KoinStartup {

    override fun onKoinStartup() = koinConfiguration<MainApplication> {
        androidContext(this@MainApplication)
    }
}
```

**Constructor / Classic DSL**
```kotlin
import org.koin.androix.startup.KoinStartup
import org.koin.dsl.koinConfiguration

@OptIn(KoinExperimentalAPI::class)
class MainApplication : Application(), KoinStartup {

    override fun onKoinStartup() = koinConfiguration {
        androidContext(this@MainApplication)
        modules(appModule)
    }
}
```

`KoinStartup` replaces the `startKoin` call in `onCreate()`: don't call both. The package name is `org.koin.androix.startup` (with this spelling), and the API is marked `@KoinExperimentalAPI`.

If another initializer needs Koin, make it depend on `KoinInitializer`. App Startup creates initializers itself, so an initializer is an entry point: it implements `KoinComponent` to retrieve its dependencies.

```kotlin
class CrashTrackerInitializer : Initializer<Unit>, KoinComponent {

    private val crashTracker: CrashTracker by inject()

    override fun create(context: Context) {
        crashTracker.configure(context)
    }

    override fun dependencies(): List<Class<out Initializer<*>>> =
        listOf(KoinInitializer::class.java)
}
```

:::warning
`KoinStartup` still runs on the main thread, during app startup. It does not make Koin start faster. Use it only to order Koin with other App Startup initializers. To move module loading off the main thread, use [Lazy Modules](/docs/reference/koin-core/lazy-modules).
:::

## Starting Koin outside the Application class

You can call `startKoin` from another class, as long as it runs once per process and before the first injection. Pass the application context, not an Activity:

```kotlin
startKoin {
    androidContext(context.applicationContext)
    modules(appModule)
}
```

`startKoin` registers a global instance. A library or SDK that ships its own Koin setup should not use it, because it would conflict with the host app: use an isolated context instead (see [Context Isolation](/docs/reference/koin-core/context-isolation)).

## Related

- [Starting Koin](/docs/reference/koin-core/starting-koin): `startKoin` options on every platform, loggers and properties.
- [Android Entry Points](/docs/reference/koin-android/entry-points): inject in Activity, Fragment, Service and other components.
- [Android Scopes](/docs/reference/koin-android/scope): bind instances to an Activity or Fragment lifecycle.
- [Modules](/docs/reference/koin-core/modules): organize definitions and use `@Configuration` discovery.
- [Lazy Modules](/docs/reference/koin-core/lazy-modules): load modules in the background.
- [Multi-Module Apps](/docs/reference/koin-android/multi-module): organize Koin modules across Gradle modules.

---

# Android Entry Points

Source: https://insert-koin.io/docs/reference/koin-android/entry-points

Android creates its components itself (Activity, Fragment, Service, BroadcastReceiver), so Koin can't use constructor injection for them. These classes are entry points: they ask Koin for their dependencies, and everything below them uses constructor injection. This page shows how to do it in each Android component. It assumes Koin is started (see [Starting Koin on Android](/docs/reference/koin-android/start)) and your definitions are declared (see [Definitions](/docs/reference/koin-core/definitions)).

The injection code is the same whichever style you use to declare definitions.

## Components at a glance

| Component | How to inject | Koin extensions built in |
|-----------|---------------|--------------------------|
| `Application` | `by inject()`, after `startKoin` | Yes |
| `Activity` | `by inject()`, `get()`, `by viewModel()` | Yes |
| `Fragment` | `by inject()`, `get()`, `by viewModel()`, `by activityViewModel()` | Yes |
| `Service` | `by inject()`, `get()` | Yes |
| `ContentProvider` | `by inject()`, with timing limits | Yes |
| `BroadcastReceiver` | Implement `KoinComponent` | No |
| Custom `View` | Implement `KoinComponent`, or pass data in | No |

Koin adds `inject()` and `get()` to every Android `ComponentCallbacks` class: `Application`, `Activity`, `Fragment`, `Service` and `ContentProvider`. Other framework-created classes (receivers, Views inflated from XML) implement [`KoinComponent`](/docs/reference/koin-core/koin-component) to get the same functions. Your own classes (repositories, use cases, ViewModels) never do: they receive dependencies through their constructor.

## Activity

```kotlin
import org.koin.android.ext.android.inject
import org.koin.androidx.viewmodel.ext.android.viewModel

class UserActivity : AppCompatActivity() {

    private val presenter: UserPresenter by inject()
    private val viewModel: UserViewModel by viewModel()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        presenter.loadUser()
    }
}
```

`by viewModel()` is not the same as `by inject()`: it goes through the Android `ViewModelStore`, so the instance survives rotation. Use it for every ViewModel. See [Android ViewModel](/docs/reference/koin-android/viewmodel).

## Fragment

```kotlin
import org.koin.android.ext.android.inject
import org.koin.androidx.viewmodel.ext.android.activityViewModel
import org.koin.androidx.viewmodel.ext.android.viewModel

class UserFragment : Fragment() {

    private val presenter: UserPresenter by inject()
    private val viewModel: UserDetailViewModel by viewModel()
    private val sharedViewModel: UserViewModel by activityViewModel()
}
```

`by viewModel()` gives a ViewModel owned by the Fragment. `by activityViewModel()` gives the one owned by the host Activity, shared with the Activity and its other Fragments.

To create Fragments with constructor injection instead, see [Fragment Factory](/docs/reference/koin-android/fragment-factory).

## Service

```kotlin
class MusicPlayerService : Service() {

    private val player: MusicPlayer by inject()
    private val repository: MusicRepository by inject()

    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        intent?.getStringExtra("SONG_ID")?.let { songId ->
            player.play(repository.getSong(songId))
        }
        return START_NOT_STICKY
    }

    override fun onBind(intent: Intent?): IBinder? = null

    override fun onDestroy() {
        player.release()
        super.onDestroy()
    }
}
```

A Service can live a long time. Release what it holds in `onDestroy()`. For instances that should live exactly as long as the Service, extend `ScopeService` (see [Android Scopes](/docs/reference/koin-android/scope#service-scope)). For deferred background work, prefer [WorkManager](/docs/reference/koin-android/workmanager), which supports constructor injection in Workers.

## BroadcastReceiver

Android creates receivers itself, with an empty constructor, and `BroadcastReceiver` has no Koin extensions. Implement `KoinComponent` to make it an entry point:

```kotlin
class BootReceiver : BroadcastReceiver(), KoinComponent {

    private val scheduler: SyncScheduler by inject()

    override fun onReceive(context: Context, intent: Intent) {
        if (intent.action == Intent.ACTION_BOOT_COMPLETED) {
            scheduler.scheduleSync()
        }
    }
}
```

Koin is ready in `onReceive()`, for receivers declared in the manifest and for receivers registered at runtime: Android creates the `Application`, and runs `startKoin`, before it delivers a broadcast.

`onReceive()` runs on the main thread and has about 10 seconds before the system considers the receiver blocked. Keep it short and hand long work to WorkManager:

```kotlin
class AlarmReceiver : BroadcastReceiver(), KoinComponent {

    private val workManager: WorkManager by inject()

    override fun onReceive(context: Context, intent: Intent) {
        val request = OneTimeWorkRequestBuilder<AlarmWorker>()
            .setInputData(workDataOf("alarm_id" to intent.getIntExtra("ID", -1)))
            .build()
        workManager.enqueue(request)
    }
}
```

This assumes a `WorkManager` definition in your modules, for example `single { WorkManager.getInstance(androidContext()) }`.

## ContentProvider

`ContentProvider` has Koin extensions, but Android creates it before `Application.onCreate()`. At that time `startKoin` has not run yet.

```kotlin
class UserContentProvider : ContentProvider() {

    private val repository: UserRepository by inject()

    override fun onCreate(): Boolean {
        // Koin is not started yet: don't touch repository here
        return true
    }

    override fun query(
        uri: Uri,
        projection: Array<out String>?,
        selection: String?,
        selectionArgs: Array<out String>?,
        sortOrder: String?,
    ): Cursor? = repository.query(uri)

    ...
}
```

`by inject()` is lazy, so the instance is resolved on the first `query()`, after `Application.onCreate()`. Calling `get()`, or reading `repository`, in `onCreate()` fails with "KoinApplication has not been started".

If the provider needs Koin in its own `onCreate()`, Koin must start before it. Start Koin there, guarded so it runs once, and remove `startKoin` from your `Application`:

```kotlin
override fun onCreate(): Boolean {
    val appContext = context?.applicationContext ?: return false
    if (GlobalContext.getOrNull() == null) {
        startKoin {
            androidContext(appContext)
            modules(appModule)
        }
    }
    return true
}
```

:::warning
Two calls to `startKoin` in the same process fail with `KoinApplicationAlreadyStartedException`. If you start Koin from a ContentProvider, the `Application` class must not start it again.
:::

## Custom View

A View should display data, not fetch it. Most Views need no injection: the Activity or Fragment injects a ViewModel and passes the data to the View.

```kotlin
class ChartView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
) : View(context, attrs) {

    fun setData(data: ChartData) {
        ...
        invalidate()
    }
}
```

When a View inflated from XML needs a shared helper (a renderer, an image loader), Android calls its constructor, so Koin can't pass the helper in. Implement `KoinComponent`:

```kotlin
class AvatarView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
) : AppCompatImageView(context, attrs), KoinComponent {

    private val imageLoader: ImageLoader by inject()

    fun load(url: String) {
        if (!isInEditMode) imageLoader.load(url, this)
    }
}
```

Koin is not started in the Android Studio layout preview. Don't resolve dependencies when `isInEditMode` is true.

## Application class

The `Application` class has Koin extensions too. Use them after `startKoin`:

```kotlin
class MainApplication : Application() {

    private val crashReporter: CrashReporter by inject()

    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidContext(this@MainApplication)
            modules(appModule)
        }
        crashReporter.install()
    }
}
```

## Lazy or eager

```kotlin
class UserActivity : AppCompatActivity() {

    // lazy: resolved on first access
    private val presenter: UserPresenter by inject()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // eager: resolved now
        val analytics: Analytics = get()
    }
}
```

| Function | Resolved | Use it for |
|----------|----------|------------|
| `by inject()` | On first access of the property | Properties: nothing is created until you use it |
| `get()` | When called | Local values inside a function |

A `get()` in a property initializer runs when Android constructs the Activity or Fragment, before `onCreate()`, and creates the instance even if the screen never uses it. Prefer `by inject()` for properties. The lazy delegate is thread safe by default (`LazyThreadSafetyMode.SYNCHRONIZED`); pass `inject(mode = LazyThreadSafetyMode.NONE)` when the property is only read on the main thread.

How `inject()` and `get()` work on every platform is explained in [Injection](/docs/reference/koin-core/injection).

## Parameters and qualifiers at the call site

Both functions take a [qualifier](/docs/reference/koin-core/qualifiers) and [injected parameters](/docs/reference/koin-core/injection-parameters):

```kotlin
class UserDetailActivity : AppCompatActivity() {

    private val userId: String by lazy { intent.getStringExtra("USER_ID").orEmpty() }

    private val presenter: UserDetailPresenter by inject { parametersOf(userId) }
    private val localDatabase: Database by inject(named("local"))
}
```

The parameter lambda runs when the property is first read. Reading `intent` there is safe, because it happens after `onCreate()`.

## Related

- [Android ViewModel](/docs/reference/koin-android/viewmodel): `by viewModel()`, `activityViewModel()` and navigation graph ViewModels.
- [Android Scopes](/docs/reference/koin-android/scope): instances bound to an Activity, Fragment or Service.
- [Injection](/docs/reference/koin-core/injection): `inject()`, `get()`, nullable and lazy injection on every platform.
- [KoinComponent](/docs/reference/koin-core/koin-component): when and how to use it outside Android components.
- [WorkManager](/docs/reference/koin-android/workmanager): constructor injection in Workers.

---

# Android ViewModel

Source: https://insert-koin.io/docs/reference/koin-android/viewmodel

This page covers the Android APIs to retrieve a ViewModel in an Activity or a Fragment: `by viewModel()`, `activityViewModel()`, navigation graph ViewModels and the Java API. How to declare a ViewModel, pass it parameters and use `SavedStateHandle` is the same on every platform: see [ViewModel](/docs/reference/koin-core/viewmodel). For Compose, see [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel).

The retrieval code below is the same whichever style you use to declare the ViewModel (`viewModel<UserViewModel>()`, `@KoinViewModel` or `viewModelOf(::UserViewModel)`).

## In an Activity

```kotlin
import org.koin.androidx.viewmodel.ext.android.viewModel
import org.koin.androidx.viewmodel.ext.android.getViewModel

class UserActivity : AppCompatActivity() {

    private val viewModel: UserViewModel by viewModel()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        viewModel.loadUser()

        // eager alternative, inside a function
        val sameViewModel: UserViewModel = getViewModel()
    }
}
```

`by viewModel()` is lazy: the ViewModel is created or retrieved on first access. Both functions go through the Activity `ViewModelStore`, so after a rotation you get the same instance back. Never retrieve a ViewModel with `by inject()` or `get()`: you would get a new, unmanaged instance each time.

These functions run on the main thread (`@MainThread`). Read the property in or after `onCreate()`.

## In a Fragment

```kotlin
import org.koin.androidx.viewmodel.ext.android.activityViewModel
import org.koin.androidx.viewmodel.ext.android.viewModel

class UserDetailFragment : Fragment() {

    // owned by this Fragment
    private val detailViewModel: UserDetailViewModel by viewModel()

    // owned by the host Activity, shared with it and its other Fragments
    private val userViewModel: UserViewModel by activityViewModel()
}
```

| Function | Owner of the ViewModel | Eager version |
|----------|------------------------|---------------|
| `by viewModel()` | The Fragment | `getViewModel()` |
| `by activityViewModel()` | The host Activity | `getActivityViewModel()` |

### Sharing between Fragments

Fragments that use `activityViewModel()` for the same class get the same instance, and so does the Activity with `by viewModel()`:

```kotlin
class WeatherActivity : AppCompatActivity() {
    private val weatherViewModel: WeatherViewModel by viewModel()
}

class WeatherHeaderFragment : Fragment() {
    private val weatherViewModel: WeatherViewModel by activityViewModel()
}

class WeatherListFragment : Fragment() {
    private val weatherViewModel: WeatherViewModel by activityViewModel()
}
```

### Another owner

`viewModel()` takes an `ownerProducer`. Use it to share a ViewModel between child Fragments of the same parent:

```kotlin
class ChildFragment : Fragment() {
    private val parentViewModel: ParentViewModel by viewModel(ownerProducer = { requireParentFragment() })
}
```

## Parameters and qualifiers

Pass values to the ViewModel with a `parametersOf` lambda, and pick a definition with a qualifier:

```kotlin
class ItemActivity : AppCompatActivity() {

    private val itemId: String by lazy { intent.getStringExtra("ITEM_ID").orEmpty() }

    private val viewModel: ItemViewModel by viewModel { parametersOf(itemId) }
    private val draftViewModel: EditorViewModel by viewModel(qualifier = named("draft"))
}
```

How to declare the parameter on the ViewModel side (`@InjectedParam`, `params.get()`) is in [ViewModel](/docs/reference/koin-core/viewmodel). Parameters are used only when the ViewModel is first created: after a rotation, the ViewModel is retrieved from the store and the new parameters are ignored.

With a qualifier, Koin stores the ViewModel under its own key. Two qualifiers on the same class give two separate instances in the same owner.

## SavedStateHandle

Add a `SavedStateHandle` parameter to the ViewModel constructor and Koin provides it. Declaration is covered in [ViewModel](/docs/reference/koin-core/viewmodel). On Android, the handle is built from the owner `CreationExtras`: it contains the Activity intent extras or the Fragment arguments. Pass `extrasProducer` to `viewModel()` if you need other extras.

The `stateViewModel()` functions from older Koin versions are removed. Use `viewModel()`.

## Navigation graph ViewModel

With the `io.insert-koin:koin-androidx-navigation` artifact, scope a ViewModel to a Navigation component graph:

```kotlin
import org.koin.androidx.navigation.koinNavGraphViewModel

class CheckoutStepFragment : Fragment() {
    private val checkoutViewModel: CheckoutViewModel by koinNavGraphViewModel(R.id.checkout_graph)
}
```

The ViewModel is owned by the back stack entry of `R.id.checkout_graph`:

- Created: the first time a Fragment of the graph reads the property.
- Shared: every Fragment in the graph that asks for it gets the same instance.
- Cleared: when the graph is popped from the back stack.

`koinNavGraphViewModel()` takes the same `qualifier`, `extrasProducer` and `parameters` arguments as `viewModel()`. For Navigation Compose, see [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel).

## ViewModels and Android scopes

When an Activity or Fragment has a Koin scope (`ScopeActivity`, `AndroidScopeComponent`), `by viewModel()` resolves the ViewModel from that scope. The ViewModel can then receive dependencies scoped to the Activity.

:::warning
Don't inject Activity-scoped or Fragment-scoped instances into a ViewModel. The ViewModel survives a rotation, the Activity scope does not: the ViewModel keeps a reference to closed objects and leaks the old Activity. For instances that live as long as the ViewModel, use the ViewModel scope (see [Android Scopes](/docs/reference/koin-android/scope#viewmodel-scope)).
:::

## Lower-level API

`viewModelForClass()` takes a `KClass` instead of a reified type. Use it when the class is only known at runtime:

```kotlin
val viewModel: UserViewModel by viewModelForClass(
    clazz = UserViewModel::class,
    owner = this,
    key = "user_42",
    parameters = { parametersOf("42") },
)
```

`key` lets you keep several instances of the same class in one owner. Unlike `viewModel()`, it starts from empty `CreationExtras`: pass a `state` argument if the ViewModel needs a `SavedStateHandle`.

## Java

Add the `io.insert-koin:koin-android-compat` artifact and use the static functions of `ViewModelCompat`:

```java
import kotlin.Lazy;
import org.koin.android.compat.ViewModelCompat;

public class UserJavaActivity extends AppCompatActivity {

    private final Lazy<UserViewModel> viewModel =
        ViewModelCompat.viewModel(this, UserViewModel.class);

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        UserViewModel vm = ViewModelCompat.getViewModel(this, UserViewModel.class);
    }
}
```

`SharedViewModelCompat` gives the host Activity ViewModel from a Fragment, and `ScopeCompat` resolves from a given scope. `ViewModelCompat` and `SharedViewModelCompat` always resolve from the root scope, never from an Activity scope.

## Related

- [ViewModel](/docs/reference/koin-core/viewmodel): declare ViewModels, parameters and `SavedStateHandle` on every platform.
- [Android Scopes](/docs/reference/koin-android/scope): Activity, Fragment and ViewModel scopes.
- [Android Entry Points](/docs/reference/koin-android/entry-points): inject other dependencies in Activities and Fragments.
- [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel): `koinViewModel()` in Composables.
- [Unit Testing](/docs/reference/koin-test/testing): test ViewModels with Koin.

---

# Android Scopes

Source: https://insert-koin.io/docs/reference/koin-android/scope

An Android scope keeps instances alive as long as one component (an Activity, a Fragment, a Service or a ViewModel) and closes them with it. This page covers the Android scope APIs: scope archetypes, `ScopeActivity`, `ScopeFragment`, `AndroidScopeComponent`, retained and Service scopes. What a scope is, `scoped`, linking and closing in general are explained in [Scopes](/docs/reference/koin-core/scopes).

## Scope lifetimes

| Scope | Opened | Closed | Survives rotation |
|-------|--------|--------|-------------------|
| `activityScope` | First access in the Activity | Activity `ON_DESTROY` | No |
| `activityRetainedScope` | First access in the Activity | Activity finishes (backed by a ViewModel) | Yes |
| `fragmentScope` | First access in the Fragment | Fragment `ON_DESTROY` | No |
| Service scope | `Service.onCreate()` | `Service.onDestroy()` | Not applicable |
| `viewModelScope` | ViewModel creation | ViewModel cleared | Yes |

A `single` lives as long as the app, so it is the outer level for all of them.

## Declaring scoped definitions

Android has one scope archetype per component type. An archetype is a scope declaration that every Activity (or Fragment) with a scope can use, so you don't write one scope per class:

**Compiler Plugin DSL**
```kotlin
import org.koin.androidx.scope.dsl.activityRetainedScope
import org.koin.androidx.scope.dsl.activityScope
import org.koin.androidx.scope.dsl.fragmentScope

val screenModule = module {
    activityScope {
        scoped<ScreenNavigator>()
    }
    activityRetainedScope {
        scoped<FormState>()
    }
    fragmentScope {
        scoped<DetailPresenter>()
    }
}
```

**Annotations**
```kotlin
import org.koin.android.annotation.ActivityRetainedScope
import org.koin.android.annotation.ActivityScope
import org.koin.android.annotation.FragmentScope

@ActivityScope
class ScreenNavigator(private val activity: Activity)

@ActivityRetainedScope
class FormState

@FragmentScope
class DetailPresenter(private val repository: UserRepository)
```

**Constructor / Classic DSL**
```kotlin
import org.koin.androidx.scope.dsl.activityRetainedScope
import org.koin.androidx.scope.dsl.activityScope
import org.koin.androidx.scope.dsl.fragmentScope

val screenModule = module {
    activityScope {
        scopedOf(::ScreenNavigator)
    }
    activityRetainedScope {
        scopedOf(::FormState)
    }
    fragmentScope {
        scopedOf(::DetailPresenter)
    }
}
```

To restrict definitions to one Activity class, declare a type-based scope instead (`scope<UserActivity> { }` in the DSL, `@Scope(UserActivity::class)` with `@Scoped` in annotations). Koin looks in the type-based scope first, then in the archetype. Type-based scopes are explained in [Scopes](/docs/reference/koin-core/scopes).

## Activity scope

Extend `ScopeActivity`, or implement `AndroidScopeComponent` and create the scope with `activityScope()`:

```kotlin
import org.koin.androidx.scope.ScopeActivity

class UserActivity : ScopeActivity() {

    private val navigator: ScreenNavigator by inject()
}
```

```kotlin
import org.koin.android.scope.AndroidScopeComponent
import org.koin.androidx.scope.activityScope

class UserActivity : AppCompatActivity(), AndroidScopeComponent {

    override val scope: Scope by activityScope()

    private val navigator: ScreenNavigator by inject()
}
```

With a scope, `inject()`, `get()` and `viewModel()` in the Activity resolve from the Activity scope first, then from the root scope. The scope closes on the Activity `ON_DESTROY` lifecycle event, so it is closed by the time your `onDestroy()` code runs.

The Activity is the source of its scope. A scoped definition can ask for `Activity` or `Context` and receive the current Activity:

```kotlin
@ActivityScope
class ScreenNavigator(private val activity: Activity) {
    fun openSettings() = activity.startActivity(Intent(activity, SettingsActivity::class.java))
}
```

`activityScope()` (the delegate, in `org.koin.androidx.scope`) and `activityScope { }` (the module DSL, in `org.koin.androidx.scope.dsl`) share a name. Check the import when the compiler picks the wrong one.

### Retained Activity scope

`activityRetainedScope()` keeps the same scope across configuration changes. Koin stores it in a ViewModel of the Activity and closes it when that ViewModel is cleared, so when the Activity finishes:

```kotlin
import org.koin.androidx.scope.RetainedScopeActivity

class FormActivity : RetainedScopeActivity() {

    private val formState: FormState by inject()
}
```

Or, with `AndroidScopeComponent`: `override val scope: Scope by activityRetainedScope()`.

Definitions in a retained scope outlive the Activity instance. They must not keep a reference to the Activity, its Views or a Fragment. A retained scope has no source: `Context` resolves to the `Application` there.

## Fragment scope

Extend `ScopeFragment`, or implement `AndroidScopeComponent` with `fragmentScope()`:

```kotlin
import org.koin.androidx.scope.ScopeFragment

class DetailFragment : ScopeFragment() {

    private val presenter: DetailPresenter by inject()

    // resolved from the parent Activity scope
    private val navigator: ScreenNavigator by inject()
}
```

```kotlin
import org.koin.androidx.scope.fragmentScope

class DetailFragment : Fragment(), AndroidScopeComponent {

    override val scope: Scope by fragmentScope()
}
```

The Fragment scope is linked to the host Activity scope, so it sees the Activity scoped instances. This works only if the host Activity has a scope (`ScopeActivity` or `AndroidScopeComponent`); otherwise the link is skipped and Koin logs it. Pass `fragmentScope(useParentActivityScope = false)` to skip it on purpose.

:::warning
The Fragment scope follows the Fragment lifecycle (`ON_DESTROY`), not the view lifecycle. A scoped instance that holds a View or a binding keeps it after `onDestroyView()`, until the Fragment is destroyed. Release View references in `onDestroyView()`.
:::

## Service scope

Extend `ScopeService`. Its scope opens in `onCreate()` and closes in `onDestroy()`. There is no Service archetype: declare a type-based scope for the Service class.

**Compiler Plugin DSL**
```kotlin
val playerModule = module {
    scope<MusicService> {
        scoped<PlaybackSession>()
    }
}
```

**Annotations**
```kotlin
@Scope(MusicService::class)
@Scoped
class PlaybackSession
```

**Constructor / Classic DSL**
```kotlin
val playerModule = module {
    scope<MusicService> {
        scopedOf(::PlaybackSession)
    }
}
```

```kotlin
import org.koin.android.scope.ScopeService

class MusicService : ScopeService() {

    private val session: PlaybackSession by inject()

    override fun onBind(intent: Intent?): IBinder? = null
}
```

If your Service can't extend `ScopeService`, implement `AndroidScopeComponent` with `override val scope: Scope by serviceScope()` and call `destroyServiceScope()` in `onDestroy()`.

## ViewModel scope

A ViewModel scope holds instances that live exactly as long as one ViewModel. Declare them with `viewModelScope { }` or `@ViewModelScope`. Then either enable the `viewModelScopeFactory()` option, so Koin creates a scope for each ViewModel, or extend `ScopeViewModel`:

```kotlin
import org.koin.core.option.viewModelScopeFactory

startKoin {
    androidContext(this@MainApplication)
    options(viewModelScopeFactory())
    modules(appModule)
}
```

Declaration, the option and `ScopeViewModel` are explained in [Scopes](/docs/reference/koin-core/scopes). On Android, retrieve the ViewModel with `by viewModel()` as usual (see [Android ViewModel](/docs/reference/koin-android/viewmodel)).

Don't declare a ViewModel with `scoped` in an `activityScope`: you get a plain object, not managed by the `ViewModelStore`, recreated on every rotation. Declare it with `viewModel` and retrieve it with `by viewModel()`.

## Cleaning up before the scope closes

Override `onCloseScope()` in an `AndroidScopeComponent`. Koin calls it right before it closes an Activity or Fragment scope, while scoped instances are still available:

```kotlin
class UserActivity : ScopeActivity() {

    override fun onCloseScope() {
        get<ScreenNavigator>().clear()
    }
}
```

`onCloseScope()` is not called for a retained scope or a Service scope. For cleanup tied to one definition, use `onClose { }` on the definition (see [Definitions](/docs/reference/koin-core/definitions#release-callback)).

## Limits

- Scope required: a class that injects scoped definitions must have a scope (`ScopeActivity`, `ScopeFragment`, `ScopeService` or `AndroidScopeComponent`). Without one, `inject()` resolves from the root scope and fails with `NoDefinitionFoundException`.
- Main thread: create the Activity and Fragment scopes from the main thread (property delegates read in or after `onCreate()`).
- Custom scopes: a scope you create yourself with `getKoin().createScope()` is not tied to any lifecycle. Close it yourself.

:::tip
To see scope lifetimes and leaked instances in real user sessions, see [Production Monitoring](/docs/tooling/production-monitoring).
:::

## Related

- [Scopes](/docs/reference/koin-core/scopes): scope concepts, linking, `@Scope` and the ViewModel scope.
- [Android ViewModel](/docs/reference/koin-android/viewmodel): ViewModels with Activity and Fragment scopes.
- [Android Entry Points](/docs/reference/koin-android/entry-points): inject in Android components.
- [Fragment Factory](/docs/reference/koin-android/fragment-factory): create Fragments from an Activity scope.
- [Android Best Practices](/docs/reference/koin-android/best-practices): avoid Context and Activity leaks.

---

# WorkManager

Source: https://insert-koin.io/docs/reference/koin-android/workmanager

Koin plugs a `WorkerFactory` into [Android WorkManager](https://developer.android.com/topic/libraries/architecture/workmanager), so your Workers get their dependencies through the constructor. This page covers the setup, how to declare a Worker and how to pass input data. It assumes Koin is started in your `Application` (see [Starting Koin on Android](/docs/reference/koin-android/start)).

## Setup

Add the WorkManager artifact next to `koin-android`:

```kotlin
// build.gradle.kts
dependencies {
    implementation("io.insert-koin:koin-android")
    implementation("io.insert-koin:koin-androidx-workmanager")
}
```

Versions come from the Koin BOM (see [Gradle Setup](/docs/setup/gradle)).

Call `workManagerFactory()` in `startKoin`, after `androidContext()`:

```kotlin
import org.koin.androidx.workmanager.koin.workManagerFactory

class MainApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        startKoin {
            androidContext(this@MainApplication)
            workManagerFactory()
            modules(appModule)
        }
    }
}
```

`workManagerFactory()` initializes WorkManager with a configuration that uses the Koin `WorkerFactory`. It does nothing if WorkManager is already initialized, which is the case when the default AndroidX initializer runs first. Remove that initializer in `AndroidManifest.xml`:

```xml
<provider
    android:name="androidx.startup.InitializationProvider"
    android:authorities="${applicationId}.androidx-startup"
    android:exported="false"
    tools:node="merge">
    <meta-data
        android:name="androidx.work.WorkManagerInitializer"
        android:value="androidx.startup"
        tools:node="remove" />
</provider>
```

:::warning
If you keep the default initializer, WorkManager starts without the Koin factory. Workers then fail at runtime because WorkManager can't create a class with extra constructor parameters.
:::

## Declaring a Worker

A Worker takes `Context` and `WorkerParameters` from WorkManager, then any dependency from Koin:

```kotlin
class SyncWorker(
    context: Context,
    params: WorkerParameters,
    private val repository: SyncRepository,
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        repository.sync()
        return Result.success()
    }
}
```

Declare it as a worker:

**Compiler Plugin DSL**
```kotlin
import org.koin.plugin.module.dsl.worker

val workModule = module {
    single<SyncRepository>()
    worker<SyncWorker>()
}
```

**Annotations**
```kotlin
import org.koin.android.annotation.KoinWorker

@KoinWorker
class SyncWorker(
    context: Context,
    params: WorkerParameters,
    private val repository: SyncRepository,
) : CoroutineWorker(context, params) {
    ...
}
```

**Constructor / Classic DSL**
```kotlin
import org.koin.androidx.workmanager.dsl.worker
import org.koin.androidx.workmanager.dsl.workerOf

val workModule = module {
    singleOf(::SyncRepository)
    workerOf(::SyncWorker)

    // or write the constructor call
    worker { params -> SyncWorker(androidContext(), params.get(), get()) }
}
```

`WorkerParameters` is the only injected parameter: read it with `params.get()` or `get()`, and the `Context` with `androidContext()`.

A worker definition is a `factory` named after the Worker class and bound to `ListenableWorker`. When WorkManager asks for a Worker class, the Koin factory looks up that name. If no definition matches, Koin returns `null` and WorkManager falls back to its default factory.

## Enqueuing work

Nothing changes on the WorkManager side:

```kotlin
val request = OneTimeWorkRequestBuilder<SyncWorker>().build()
WorkManager.getInstance(context).enqueue(request)
```

## Input data

Values that change per run go through WorkManager input data, not through Koin:

```kotlin
class UserSyncWorker(
    context: Context,
    params: WorkerParameters,
    private val repository: UserRepository,
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        val userId = inputData.getString("USER_ID") ?: return Result.failure()
        repository.syncUser(userId)
        return Result.success()
    }
}
```

```kotlin
val request = OneTimeWorkRequestBuilder<UserSyncWorker>()
    .setInputData(workDataOf("USER_ID" to "123"))
    .build()

WorkManager.getInstance(context).enqueue(request)
```

Input data is stored by WorkManager and survives process death, which Koin parameters do not.

## Related

- [Starting Koin on Android](/docs/reference/koin-android/start): `startKoin` and `androidContext()`.
- [Definitions](/docs/reference/koin-core/definitions): definition types, including `worker`.
- [Android Entry Points](/docs/reference/koin-android/entry-points): hand work from a BroadcastReceiver to WorkManager.
- [Android WorkManager guide](https://developer.android.com/topic/libraries/architecture/workmanager): the WorkManager API.

---

# Fragment Factory

Source: https://insert-koin.io/docs/reference/koin-android/fragment-factory

By default, Android creates Fragments with their empty constructor, so you inject them with `by inject()` (see [Android Entry Points](/docs/reference/koin-android/entry-points)). With the AndroidX [FragmentFactory](https://developer.android.com/reference/kotlin/androidx/fragment/app/FragmentFactory), Koin creates the Fragment itself and passes dependencies to its constructor. This page covers the setup, the `fragment` definition and Fragments from an Activity scope.

The `fragment` definition is part of `io.insert-koin:koin-android`. No other artifact is needed.

## Setup

Enable the Koin fragment factory in `startKoin`:

```kotlin
import org.koin.androidx.fragment.koin.fragmentFactory

startKoin {
    androidContext(this@MainApplication)
    fragmentFactory()
    modules(appModule)
}
```

Then install it in each Activity that hosts these Fragments, before `super.onCreate()`:

```kotlin
import org.koin.androidx.fragment.android.setupKoinFragmentFactory

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        setupKoinFragmentFactory()
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }
}
```

`super.onCreate()` restores Fragments after a rotation or process death. The factory must be in place before that, or Android uses the default factory and fails on Fragments without an empty constructor.

## Declaring a Fragment

**Compiler Plugin DSL**
The Compiler Plugin DSL has no `fragment<T>()` function. Use the Classic DSL `fragment { }` or the Constructor DSL `fragmentOf()` in the same module:

```kotlin
class UserFragment(private val repository: UserRepository) : Fragment()

val uiModule = module {
    single<UserRepository>()
    fragmentOf(::UserFragment)
}
```

**Annotations**
There is no Fragment annotation. Declare the Fragment in a DSL module, next to your annotated classes (see [DSL Reference](/docs/reference/koin-core/dsl)):

```kotlin
val uiModule = module {
    fragmentOf(::UserFragment)
}
```

**Constructor / Classic DSL**
```kotlin
import org.koin.androidx.fragment.dsl.fragment
import org.koin.androidx.fragment.dsl.fragmentOf

class UserFragment(private val repository: UserRepository) : Fragment()

val uiModule = module {
    singleOf(::UserRepository)
    fragmentOf(::UserFragment)

    // or write the constructor call
    fragment { UserFragment(get()) }
}
```

A `fragment` definition is a `factory`: every transaction gets a new Fragment instance. If no definition matches a Fragment class, the Koin factory falls back to the default AndroidX behavior.

## Adding a Fragment

Use the reified `replace` extension on `FragmentTransaction`:

```kotlin
import org.koin.androidx.fragment.android.replace

supportFragmentManager.beginTransaction()
    .replace<UserFragment>(R.id.container)
    .commit()
```

With arguments and a tag:

```kotlin
supportFragmentManager.beginTransaction()
    .replace<UserFragment>(
        containerViewId = R.id.container,
        args = bundleOf("USER_ID" to "42"),
        tag = "user",
    )
    .commit()
```

Pass per-instance values in `args`, not in the constructor: Android recreates the Fragment through the factory, and only the arguments are restored.

## Fragments from an Activity scope

To give a Fragment instances from its Activity scope, declare the Fragment inside the scope and pass the scope to `setupKoinFragmentFactory()`:

```kotlin
val checkoutModule = module {
    scope<CheckoutActivity> {
        scopedOf(::CheckoutSession)
        fragmentOf(::PaymentFragment)
    }
}
```

```kotlin
class CheckoutActivity : ScopeActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        setupKoinFragmentFactory(scope)
        super.onCreate(savedInstanceState)
    }
}
```

With a scope, the factory resolves Fragments from that scope, then from the root scope. In this case it does not need `fragmentFactory()` in `startKoin`: that option only declares the global factory used by `setupKoinFragmentFactory()` without arguments. Activity scopes are covered in [Android Scopes](/docs/reference/koin-android/scope).

## Related

- [Android Entry Points](/docs/reference/koin-android/entry-points): inject in a Fragment with `by inject()`.
- [Android Scopes](/docs/reference/koin-android/scope): Activity and Fragment scopes.
- [Definitions](/docs/reference/koin-core/definitions): `factory` and the other definition types.
- [AndroidX Fragments guide](https://developer.android.com/guide/fragments): the Fragment API.

---

# Android Library Integration

Source: https://insert-koin.io/docs/reference/koin-android/binding-patterns

This page gives complete Koin setups for libraries most Android apps use: Retrofit with OkHttp, Room and a JSON serializer, then a layered app structure. Library classes come from builders, so they are declared with provider functions. How that works (`create(::function)`, annotated functions) is explained in [Definitions](/docs/reference/koin-core/definitions#classes-you-dont-own); this page only shows the Android setups.

## Retrofit and OkHttp

```kotlin
interface ApiService {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: String): User
}
```

**Compiler Plugin DSL**
```kotlin
import org.koin.plugin.module.dsl.create

fun okHttpClient(): OkHttpClient =
    OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)
        .addInterceptor(HttpLoggingInterceptor().apply {
            level = if (BuildConfig.DEBUG) HttpLoggingInterceptor.Level.BODY else HttpLoggingInterceptor.Level.NONE
        })
        .build()

fun retrofit(client: OkHttpClient, json: Json): Retrofit =
    Retrofit.Builder()
        .baseUrl(BuildConfig.API_URL)
        .client(client)
        .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
        .build()

fun apiService(retrofit: Retrofit): ApiService = retrofit.create(ApiService::class.java)

val networkModule = module {
    single { create(::okHttpClient) }
    single { create(::retrofit) }
    single { create(::apiService) }
}
```

**Annotations**
```kotlin
@Module
class NetworkModule {

    @Singleton
    fun okHttpClient(): OkHttpClient =
        OkHttpClient.Builder()
            .connectTimeout(30, TimeUnit.SECONDS)
            .readTimeout(30, TimeUnit.SECONDS)
            .addInterceptor(HttpLoggingInterceptor().apply {
                level = if (BuildConfig.DEBUG) HttpLoggingInterceptor.Level.BODY else HttpLoggingInterceptor.Level.NONE
            })
            .build()

    @Singleton
    fun retrofit(client: OkHttpClient, json: Json): Retrofit =
        Retrofit.Builder()
            .baseUrl(BuildConfig.API_URL)
            .client(client)
            .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
            .build()

    @Singleton
    fun apiService(retrofit: Retrofit): ApiService = retrofit.create(ApiService::class.java)
}
```

**Constructor / Classic DSL**
```kotlin
val networkModule = module {
    single {
        OkHttpClient.Builder()
            .connectTimeout(30, TimeUnit.SECONDS)
            .readTimeout(30, TimeUnit.SECONDS)
            .addInterceptor(HttpLoggingInterceptor().apply {
                level = if (BuildConfig.DEBUG) HttpLoggingInterceptor.Level.BODY else HttpLoggingInterceptor.Level.NONE
            })
            .build()
    }
    single {
        Retrofit.Builder()
            .baseUrl(BuildConfig.API_URL)
            .client(get())
            .addConverterFactory(get<Json>().asConverterFactory("application/json".toMediaType()))
            .build()
    }
    single { get<Retrofit>().create(ApiService::class.java) }
}
```

Declare `OkHttpClient` and `Retrofit` as `single`: each one holds a connection pool and thread pools, and creating several wastes them. `BuildConfig.API_URL` is a `buildConfigField` you define per build type. The `Json` instance comes from the next section.

## JSON serialization

**Compiler Plugin DSL**
```kotlin
fun json(): Json = Json {
    ignoreUnknownKeys = true
    explicitNulls = false
}

val serializationModule = module {
    single { create(::json) }
}
```

**Annotations**
```kotlin
@Module
class SerializationModule {

    @Singleton
    fun json(): Json = Json {
        ignoreUnknownKeys = true
        explicitNulls = false
    }
}
```

**Constructor / Classic DSL**
```kotlin
val serializationModule = module {
    single {
        Json {
            ignoreUnknownKeys = true
            explicitNulls = false
        }
    }
}
```

The same pattern works for Gson (`single { create(::gson) }` with `fun gson(): Gson = GsonBuilder().create()`) or Moshi. One shared instance keeps the serializer configuration in one place.

## Room

```kotlin
@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}
```

**Compiler Plugin DSL**
```kotlin
fun appDatabase(context: Context): AppDatabase =
    Room.databaseBuilder(context, AppDatabase::class.java, "app-database").build()

fun userDao(database: AppDatabase): UserDao = database.userDao()

val databaseModule = module {
    single { create(::appDatabase) }
    single { create(::userDao) }
}
```

**Annotations**
```kotlin
@Module
class DatabaseModule {

    @Singleton
    fun appDatabase(context: Context): AppDatabase =
        Room.databaseBuilder(context, AppDatabase::class.java, "app-database").build()

    @Singleton
    fun userDao(database: AppDatabase): UserDao = database.userDao()
}
```

**Constructor / Classic DSL**
```kotlin
val databaseModule = module {
    single {
        Room.databaseBuilder(androidContext(), AppDatabase::class.java, "app-database").build()
    }
    single { get<AppDatabase>().userDao() }
}
```

Declare the database as a `single`: a `RoomDatabase` instance is costly, and the Room documentation asks for one instance per database in a process. `Context` here is the `Application`, given by `androidContext()` at start (see [Starting Koin on Android](/docs/reference/koin-android/start)). DAOs are cheap and Room returns the same instance for each call, so `single` or `factory` both work.

## WorkManager

Workers get their dependencies through a dedicated `WorkerFactory`. Setup and the `worker` definition are in [WorkManager](/docs/reference/koin-android/workmanager).

## Layered architecture

A typical Android app has a data layer (network, database, repositories), a domain layer (use cases) and a UI layer (ViewModels). Each layer uses the definition type that matches its lifetime:

| Layer | Classes | Definition |
|-------|---------|------------|
| Data | `OkHttpClient`, `Retrofit`, `AppDatabase`, data sources, repositories | `single` |
| Domain | Use cases, with no state | `factory` |
| UI | ViewModels | `viewModel` |

**Compiler Plugin DSL**
```kotlin
val dataModule = module {
    includes(networkModule, databaseModule, serializationModule)
    single<UserRemoteDataSource>()
    single<UserLocalDataSource>()
    single<UserRepositoryImpl>() bind UserRepository::class
}

val domainModule = module {
    factory<GetUserUseCase>()
}

val uiModule = module {
    viewModel<UserViewModel>()
}
```

**Annotations**
```kotlin
@Singleton
class UserRemoteDataSource(private val api: ApiService)

@Singleton
class UserLocalDataSource(private val dao: UserDao)

@Singleton
class UserRepositoryImpl(
    private val remote: UserRemoteDataSource,
    private val local: UserLocalDataSource,
) : UserRepository

@Factory
class GetUserUseCase(private val repository: UserRepository) {
    suspend operator fun invoke(userId: String): User = repository.getUser(userId)
}

@KoinViewModel
class UserViewModel(
    private val getUser: GetUserUseCase,
    private val savedStateHandle: SavedStateHandle,
) : ViewModel()
```

**Constructor / Classic DSL**
```kotlin
val dataModule = module {
    includes(networkModule, databaseModule, serializationModule)
    singleOf(::UserRemoteDataSource)
    singleOf(::UserLocalDataSource)
    singleOf(::UserRepositoryImpl) bind UserRepository::class
}

val domainModule = module {
    factoryOf(::GetUserUseCase)
}

val uiModule = module {
    viewModelOf(::UserViewModel)
}
```

The ViewModel depends on the use case, the use case on the `UserRepository` interface, and only the data module knows `UserRepositoryImpl`. To swap the data source in tests, override the `UserRepository` binding (see [Unit Testing](/docs/reference/koin-test/testing)). When each layer lives in its own Gradle module, see [Multi-Module Apps](/docs/reference/koin-android/multi-module).

## Related

- [Definitions](/docs/reference/koin-core/definitions): definition types, interface binding and provider functions.
- [Starting Koin on Android](/docs/reference/koin-android/start): `androidContext()` and Android Context in definitions.
- [Android ViewModel](/docs/reference/koin-android/viewmodel): retrieve ViewModels in Activities and Fragments.
- [WorkManager](/docs/reference/koin-android/workmanager): constructor injection in Workers.
- [Multi-Module Apps](/docs/reference/koin-android/multi-module): one Koin module per Gradle module.

---

# Multi-Module Apps

Source: https://insert-koin.io/docs/reference/koin-android/multi-module

This page shows how to organize Koin in an Android app split into Gradle modules (`:app`, `:feature:*`, `:core:*`). It covers where each Koin module lives, how the app loads them, how features share types, and dynamic feature modules. Module composition (`includes()`, public and private modules, `@Configuration`) is explained in [Modules](/docs/reference/koin-core/modules).

## Project layout

```
:app                  Application class, startKoin, appModule
:feature:login        LoginViewModel, LoginUseCase, loginModule
:feature:profile      ProfileViewModel, profileModule
:core:data            repositories, Retrofit, Room, dataModule
:core:domain          interfaces shared by features (UserRepository)
```

Each Gradle module declares the Koin module for its own classes. Classes can then stay `internal` to their Gradle module: only the Koin module is public. The `:app` module is the only one that knows every feature, so it is where Koin starts.

## Declaring and loading feature modules

**Compiler Plugin DSL**
```kotlin
// Gradle module ":feature:login"
internal class LoginUseCase(private val auth: AuthService)
internal class LoginViewModel(private val login: LoginUseCase) : ViewModel()

val loginModule = module {
    factory<LoginUseCase>()
    viewModel<LoginViewModel>()
}
```

```kotlin
// Gradle module ":app"
val appModule = module {
    includes(dataModule, loginModule, profileModule)
}

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidLogger()
            androidContext(this@MainApplication)
            modules(appModule)
        }
    }
}
```

**Annotations**
```kotlin
// Gradle module ":feature:login"
@Module
@ComponentScan("com.app.feature.login")
@Configuration
class LoginModule

@Factory
internal class LoginUseCase(private val auth: AuthService)

@KoinViewModel
internal class LoginViewModel(private val login: LoginUseCase) : ViewModel()
```

```kotlin
// Gradle module ":app"
@KoinApplication
class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin<MainApplication> {
            androidLogger()
            androidContext(this@MainApplication)
        }
    }
}
```

`startKoin<MainApplication>()` finds every `@Configuration` module on the app classpath, including those from feature Gradle modules. Adding a feature means adding the Gradle dependency, nothing else. To list modules explicitly instead, use `@KoinApplication(modules = [LoginModule::class, ProfileModule::class])`.

**Constructor / Classic DSL**
```kotlin
// Gradle module ":feature:login"
internal class LoginUseCase(private val auth: AuthService)
internal class LoginViewModel(private val login: LoginUseCase) : ViewModel()

val loginModule = module {
    factoryOf(::LoginUseCase)
    viewModelOf(::LoginViewModel)
}
```

```kotlin
// Gradle module ":app"
val appModule = module {
    includes(dataModule, loginModule, profileModule)
}

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidLogger()
            androidContext(this@MainApplication)
            modules(appModule)
        }
    }
}
```

## Sharing types between features

A feature should not depend on another feature. When `:feature:profile` needs the current user, it depends on an interface in a core module, and the implementation is bound where it lives:

```kotlin
// Gradle module ":core:domain"
interface UserRepository {
    suspend fun currentUser(): User
}
```

**Compiler Plugin DSL**
```kotlin
// Gradle module ":core:data"
internal class UserRepositoryImpl(private val api: ApiService) : UserRepository

val dataModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class
}
```

**Annotations**
```kotlin
// Gradle module ":core:data"
@Singleton
internal class UserRepositoryImpl(private val api: ApiService) : UserRepository
```

**Constructor / Classic DSL**
```kotlin
// Gradle module ":core:data"
internal class UserRepositoryImpl(private val api: ApiService) : UserRepository

val dataModule = module {
    singleOf(::UserRepositoryImpl) bind UserRepository::class
}
```

`ProfileViewModel(private val users: UserRepository)` in `:feature:profile` then resolves `UserRepositoryImpl` at runtime. Koin resolves across Gradle modules as long as every Koin module is loaded: the feature only needs to see the interface type. You don't need an extra entry point interface or component per feature.

With the Compiler Plugin, a feature module has no `startKoin` of its own, so its dependencies are checked when `:app` compiles and assembles the full graph. See [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety).

## Dynamic feature modules

With Play Feature Delivery, the base app can't reference code from a dynamic feature module: the dependency goes from the feature to the app. Load the feature Koin module from the feature itself, in its entry Activity, with `loadKoinModules()`:

```kotlin
// Dynamic feature module ":feature:premium"
internal object PremiumKoin {
    private val modules = lazy { loadKoinModules(premiumModule) }
    fun load() = modules.value
}

class PremiumActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        PremiumKoin.load()
        super.onCreate(savedInstanceState)
    }
}
```

The `lazy` makes sure the module loads once per process, before `super.onCreate()`. Why both matter, and how to unload, is covered in [Starting Koin on Android](/docs/reference/koin-android/start#loading-modules-after-start).

The Compiler Plugin can't see a module loaded this way. Types used by the base app that only come from such a module must be marked `@Provided` (see [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety)).

## Testing feature modules

Test each feature module on its own, with fakes for what other modules provide. With the Compiler Plugin, the full graph is checked at build time. Without it, check each module with `verify()` (see [Verifying your Configuration](/docs/reference/koin-test/verify)). Unit tests with Koin are covered in [Unit Testing](/docs/reference/koin-test/testing), and on-device tests in [Instrumented Testing](/docs/reference/koin-android/instrumented-testing).

## Related

- [Modules](/docs/reference/koin-core/modules): `includes()`, module visibility and `@Configuration` discovery.
- [Starting Koin on Android](/docs/reference/koin-android/start): `startKoin` and loading modules at runtime.
- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): how the graph is checked across Gradle modules.
- [Lazy Modules](/docs/reference/koin-core/lazy-modules): load feature modules in the background at startup.
- [Android Library Integration](/docs/reference/koin-android/binding-patterns): data, domain and UI layers.

---

# Advanced Android Patterns

Source: https://insert-koin.io/docs/reference/koin-android/advanced-patterns

This page collects Android-only patterns: choosing an implementation per build type or flavor, and declaring UI helpers that need the current Activity. Patterns that work on every platform (collections, generics, decorators, providers) are in [Advanced Patterns](/docs/reference/koin-core/advanced-patterns). Scope linking is in [Scopes](/docs/reference/koin-core/scopes).

## Implementations per build variant

### With BuildConfig

Choose the implementation in a provider function:

**Compiler Plugin DSL**
```kotlin
import org.koin.plugin.module.dsl.create

fun analytics(context: Context): Analytics =
    if (BuildConfig.ENABLE_ANALYTICS) FirebaseAnalyticsTracker(context) else NoOpAnalytics()

val analyticsModule = module {
    single { create(::analytics) }
}
```

**Annotations**
```kotlin
@Module
class AnalyticsModule {

    @Singleton
    fun analytics(context: Context): Analytics =
        if (BuildConfig.ENABLE_ANALYTICS) FirebaseAnalyticsTracker(context) else NoOpAnalytics()
}
```

**Constructor / Classic DSL**
```kotlin
val analyticsModule = module {
    single<Analytics> {
        if (BuildConfig.ENABLE_ANALYTICS) FirebaseAnalyticsTracker(androidContext()) else NoOpAnalytics()
    }
}
```

`ENABLE_ANALYTICS` is a `buildConfigField` set per build type or flavor. `BuildConfig.DEBUG` works the same way. Both implementations are compiled into every variant; only one is created.

### With source sets

To keep debug-only code out of the release APK, declare the same Koin module in each variant source set:

```kotlin
// src/debug/kotlin/com/app/di/VariantModule.kt
val variantModule = module {
    single<Logger> { VerboseLogger() }
    single<NetworkInspector> { ChuckerInspector(androidContext()) }
}
```

```kotlin
// src/release/kotlin/com/app/di/VariantModule.kt
val variantModule = module {
    single<Logger> { CrashlyticsLogger() }
    single<NetworkInspector> { NoOpInspector() }
}
```

```kotlin
// src/main
startKoin {
    androidContext(this@MainApplication)
    modules(appModule, variantModule)
}
```

`src/main` sees one `variantModule` per build, so it compiles in both. Each variant only ships its own implementations and their libraries (use `debugImplementation` for debug-only dependencies).

## UI helpers that need the Activity

Some helpers need the current Activity, not the Application: dialogs, permission requests, anything that uses the Activity theme. An `AlertDialog` built with the Application context fails when it is shown. Declare these helpers in the Activity scope, where `Context` resolves to the Activity:

**Compiler Plugin DSL**
```kotlin
class DialogProvider(private val context: Context) {

    fun confirm(title: String, onConfirm: () -> Unit): AlertDialog =
        AlertDialog.Builder(context)
            .setTitle(title)
            .setPositiveButton(android.R.string.ok) { _, _ -> onConfirm() }
            .create()
}

val uiModule = module {
    activityScope {
        scoped<DialogProvider>()
    }
}
```

**Annotations**
```kotlin
@ActivityScope
class DialogProvider(private val context: Context) {

    fun confirm(title: String, onConfirm: () -> Unit): AlertDialog =
        AlertDialog.Builder(context)
            .setTitle(title)
            .setPositiveButton(android.R.string.ok) { _, _ -> onConfirm() }
            .create()
}
```

**Constructor / Classic DSL**
```kotlin
val uiModule = module {
    activityScope {
        scopedOf(::DialogProvider)
    }
}
```

```kotlin
class SettingsActivity : ScopeActivity() {

    private val dialogs: DialogProvider by inject()

    fun onResetClicked() {
        dialogs.confirm("Reset settings?") { resetSettings() }.show()
    }
}
```

The Activity must have a scope (`ScopeActivity` or `AndroidScopeComponent`). From an Activity without a scope, `DialogProvider` is not found. The scope closes with the Activity, so the helper never outlives it. See [Android Scopes](/docs/reference/koin-android/scope).

Don't declare such a helper as a `single`: a `single` resolves its dependencies from the root scope, where `Context` is the Application, and it would outlive the Activity anyway.

## Related

- [Advanced Patterns](/docs/reference/koin-core/advanced-patterns): collections, generics, decorators and providers on every platform.
- [Android Scopes](/docs/reference/koin-android/scope): Activity and Fragment scopes, and what `Context` resolves to.
- [Android Best Practices](/docs/reference/koin-android/best-practices): Context leaks and memory.
- [Troubleshooting](/docs/reference/koin-core/troubleshooting): circular dependencies and resolution errors.

---

# Android Best Practices

Source: https://insert-koin.io/docs/reference/koin-android/best-practices

This page lists the Android-specific mistakes that cause leaks, crashes or exposed secrets with Koin, and how to avoid them. It assumes you know [Android Scopes](/docs/reference/koin-android/scope) and [Starting Koin on Android](/docs/reference/koin-android/start). General module organization is in [Modules](/docs/reference/koin-core/modules), and error messages are explained in [Troubleshooting](/docs/reference/koin-core/troubleshooting).

## Memory and Context leaks

An instance leaks when something that lives longer keeps a reference to it. On Android, the usual victim is an Activity: a `single` lives as long as the process, an Activity only until the next rotation.

### Activity passed into a single

```kotlin
// leaks: the single keeps the first Activity forever
class UserActivity : AppCompatActivity() {
    private val tracker: ScreenTracker by inject { parametersOf(this) }
}

val appModule = module {
    single { params -> ScreenTracker(params.get<Activity>()) }
}
```

A `single` is created once, with the parameters of the first call. Later calls get the same instance, still holding the first Activity. Use one of these instead:

- Application context: when the class only needs resources or system services, declare it as a `single` with `Context`. In a `single`, `Context` is the `Application`.
- Activity scope: when the class needs the Activity, declare it in `activityScope { }` or with `@ActivityScope`. It is created per Activity and released with it.
- Factory with parameters: when the caller passes the Activity, use a `factory` and don't keep the result beyond the Activity lifetime.

The Compiler Plugin treats `Context`, `Activity`, `Application`, `Fragment` and `SavedStateHandle` as types provided by the platform, so it doesn't report them as missing. It also can't tell whether an `Activity` parameter is safe in a given definition: check this in review.

### Listeners held by singletons

```kotlin
class UserRepository {
    private val listeners = mutableListOf<UserListener>()

    fun addListener(listener: UserListener) { listeners += listener }
    fun removeListener(listener: UserListener) { listeners -= listener }
}
```

A repository is a `single`. If an Activity or Fragment registers itself as a listener and never removes it, the repository keeps the screen alive. Remove listeners in the matching lifecycle callback (`onStop()` for `onStart()`, `onDestroyView()` for `onViewCreated()`), or expose a `Flow` and collect it with `repeatOnLifecycle`, which cancels collection for you.

### Scoped instances that outlive their owner

- Retained scope: `activityRetainedScope` survives rotation. Its instances must not reference the Activity, a View or a Fragment.
- Fragment scope: it closes in `onDestroy()`, after `onDestroyView()`. Don't keep Views or bindings in Fragment-scoped instances.
- ViewModel: never inject Activity-scoped or Fragment-scoped instances into a ViewModel. The ViewModel survives rotation, the Activity scope does not.

These rules are explained in [Android Scopes](/docs/reference/koin-android/scope).

### Scopes you create yourself

`activityScope()`, `fragmentScope()`, `ScopeActivity`, `ScopeFragment` and `ScopeService` close their scope with the lifecycle. A scope created with `getKoin().createScope()` has no lifecycle: close it yourself, or every instance in it stays in memory.

```kotlin
// on login
val sessionScope = getKoin().createScope<UserSession>(userId)

// on logout
sessionScope.close()
```

## Debugging on Android

Turn on the Logcat logger with the debug level while you investigate:

```kotlin
startKoin {
    androidLogger(Level.DEBUG)
    androidContext(this@MainApplication)
    modules(appModule)
}
```

Filter Logcat on the `[Koin]` tag. At debug level, Koin logs each module load, each resolution and its duration, and each scope that opens or closes. Use `Level.ERROR` or `Level.NONE` in release builds.

Errors you only see on Android:

| Error | Usual cause |
|-------|-------------|
| `MissingAndroidContextException` | `androidContext()` is missing from `startKoin` |
| `KoinApplication has not been started` | The `Application` class is not declared in the manifest, or a ContentProvider injects in its `onCreate()` (see [Android Entry Points](/docs/reference/koin-android/entry-points#contentprovider)) |
| `NoDefinitionFoundException` for a scoped type | The Activity or Fragment has no scope (`ScopeActivity`, `AndroidScopeComponent`) |
| `ClosedScopeException` | Code resolves a scoped instance in or after `onDestroy()`, when the scope is already closed. Do that cleanup in `onCloseScope()` |
| Workers fail with "Could not instantiate" | The default WorkManager initializer is still in the manifest (see [WorkManager](/docs/reference/koin-android/workmanager)) |

With the Compiler Plugin, missing definitions are reported at build time instead (see [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety)).

:::tip
To see resolution times, scope lifetimes and Koin errors from real user sessions, see [Production Monitoring](/docs/tooling/production-monitoring).
:::

## Secrets

An APK can be unpacked. Anything compiled into it or stored in `assets/` can be read:

- Hardcoded keys: don't write API keys as string literals in a module.
- Koin properties: `androidFileProperties()` reads `assets/koin.properties`, which ships inside the APK. Use it for configuration, never for secrets.
- `BuildConfig` fields: they are compiled into the APK too. They hide a value from source control, not from the APK.

Fetch secrets at runtime from your backend, or keep tokens in encrypted storage, and inject the storage instead of the value:

```kotlin
class AuthInterceptor(private val tokens: TokenStore) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response =
        chain.proceed(
            chain.request().newBuilder()
                .header("Authorization", "Bearer ${tokens.currentToken()}")
                .build()
        )
}
```

`TokenStore` is a `single` backed by your encrypted storage, and `AuthInterceptor` is added to the `OkHttpClient` definition (see [Android Library Integration](/docs/reference/koin-android/binding-patterns)).

## Migrating from Hilt or Dagger

Annotation mapping, module migration and gradual migration are covered in [Migrating from Hilt](/docs/reference/koin-android/hilt-migration). To keep `@Inject` and `jakarta.inject` annotations, see [JSR-330 Annotations](/docs/reference/koin-android/jsr330).

## Related

- [Android Scopes](/docs/reference/koin-android/scope): lifetimes of Activity, Fragment, retained and ViewModel scopes.
- [Starting Koin on Android](/docs/reference/koin-android/start): `androidContext()`, logging and properties.
- [Troubleshooting](/docs/reference/koin-core/troubleshooting): resolution errors and circular dependencies.
- [Lazy Modules](/docs/reference/koin-core/lazy-modules): reduce Koin work at app startup.
- [Migrating from Hilt](/docs/reference/koin-android/hilt-migration): move an existing Hilt app to Koin.

---

# Koin for Compose

Source: https://insert-koin.io/docs/reference/koin-compose/compose

This page covers the Compose packages, the two ways to start Koin in a Compose app, and `koinInject()` to retrieve dependencies in a Composable. It works the same on Jetpack Compose (Android) and Compose Multiplatform. You should know how to declare [definitions](/docs/reference/koin-core/definitions) and [modules](/docs/reference/koin-core/modules).

## Packages

| Package | Contains | Platforms |
|---------|----------|-----------|
| `io.insert-koin:koin-compose` | `KoinApplication`, `koinInject`, scope and module APIs | Multiplatform |
| `io.insert-koin:koin-compose-viewmodel` | `koinViewModel`, `koinActivityViewModel` (Android) | Multiplatform |
| `io.insert-koin:koin-compose-viewmodel-navigation` | `sharedKoinViewModel`, `KoinNavigationScope`, `navigationScope` | Multiplatform |
| `io.insert-koin:koin-compose-navigation3` | Navigation 3 entries | Multiplatform |
| `io.insert-koin:koin-androidx-compose` | `koin-compose` + `koin-compose-viewmodel`, plus `KoinActivityScope` and `KoinFragmentScope` | Android |
| `io.insert-koin:koin-androidx-compose-navigation` | Deprecated `koinNavViewModel` only | Android |

All Compose APIs live in the multiplatform packages. `koin-androidx-compose` is a convenience artifact for Android projects:

```kotlin
// Android app
dependencies {
    implementation("io.insert-koin:koin-androidx-compose:$koin_version")
}

// Compose Multiplatform, in commonMain
commonMain.dependencies {
    implementation("io.insert-koin:koin-compose:$koin_version")
    implementation("io.insert-koin:koin-compose-viewmodel:$koin_version")
}
```

For the BOM and version catalogs, see [Gradle Setup](/docs/setup/gradle).

## Starting Koin

You have two options. Pick one per app.

### Start outside Compose

Start Koin where your platform starts: the `Application` class on Android, the shared `initKoin()` function in a KMP project (see [KMP Setup](/docs/reference/koin-core/kmp-setup)). Compose then uses the running Koin instance with no extra setup:

```kotlin
class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidContext(this@MainApplication)
            modules(appModule)
        }
    }
}

@Composable
fun App() {
    val repository = koinInject<UserRepository>()
}
```

Use this option when code outside Compose (a `Service`, a `WorkManager` worker, iOS Swift code) also needs Koin, because that code runs without any Composable.

### Start from a Composable with KoinApplication

`KoinApplication` starts Koin from the root Composable and provides it to all children:

**Compiler Plugin DSL**
```kotlin
import org.koin.compose.KoinApplication
import org.koin.dsl.koinConfiguration

@Composable
fun App() {
    KoinApplication(
        configuration = koinConfiguration { modules(appModule) }
    ) {
        MainScreen()
    }
}
```

**Annotations**
```kotlin
// di/Koin.kt
import org.koin.core.annotation.KoinApplication

@KoinApplication
object KoinApp
```

The annotation and the Composable are both named `KoinApplication`, so keep them in separate files.

```kotlin
// App.kt
import org.koin.compose.KoinApplication
import org.koin.plugin.module.dsl.koinConfiguration

@Composable
fun App() {
    KoinApplication(configuration = koinConfiguration<KoinApp>()) {
        MainScreen()
    }
}
```

`koinConfiguration<KoinApp>()` loads the modules of the `@KoinApplication` class. Pass a lambda to add options: `koinConfiguration<KoinApp> { printLogger() }`.

**Constructor / Classic DSL**
```kotlin
import org.koin.compose.KoinApplication
import org.koin.dsl.koinConfiguration

@Composable
fun App() {
    KoinApplication(
        configuration = koinConfiguration { modules(appModule) }
    ) {
        MainScreen()
    }
}
```

What `KoinApplication` does for you:

- **Platform setup**: on Android it calls `androidContext()` with the application context and sets up `androidLogger()`. On other platforms it sets up `printLogger()`. Change the level with the `logLevel` parameter (default `Level.INFO`).
- **Existing instance**: if Koin is already started, `KoinApplication` attaches to the running instance and ignores its own configuration.
- **Lifecycle**: Koin is not stopped when `KoinApplication` leaves the composition, so it survives an Android configuration change or Activity recreation. It is stopped only if the composition is abandoned.

`koinConfiguration { }` builds a reusable [KoinConfiguration](/docs/reference/koin-core/starting-koin), so you can share the same configuration between `KoinApplication`, `startKoin` and tests.

### Deprecated entry points

| API | Status | Use instead |
|-----|--------|-------------|
| `KoinApplication(application = { ... })` | Deprecated | `KoinApplication(configuration = koinConfiguration { ... })` |
| `KoinMultiplatformApplication(config)` | Deprecated | `KoinApplication(configuration)` |
| `KoinContext { }` | Deprecated, not needed | Nothing. Compose finds the instance started with `startKoin` |
| `KoinAndroidContext { }` | Deprecated, not needed | Nothing |

## Injecting with koinInject

`koinInject()` resolves a dependency from the current Koin scope (the root scope, unless a [Compose scope](/docs/reference/koin-compose/compose-scopes) is active):

```kotlin
import org.koin.compose.koinInject

@Composable
fun UserScreen() {
    val repository = koinInject<UserRepository>()
}
```

Declare it as a default parameter. The Composable still works with Koin, and a test or a preview can pass its own instance:

```kotlin
@Composable
fun UserScreen(repository: UserRepository = koinInject()) {
    // ...
}
```

`koinInject()` wraps the resolution in `remember`, keyed on the qualifier, the scope and the parameters. A recomposition with the same keys returns the same object without resolving again.

### Qualifier and scope

```kotlin
@Composable
fun SyncScreen() {
    val localDb = koinInject<Database>(qualifier = named("local"))
    val cache = koinInject<SessionCache>(scope = sessionScope)
}
```

See [Qualifiers](/docs/reference/koin-core/qualifiers) for declaring named definitions.

### Parameters

Pass [injected parameters](/docs/reference/koin-core/injection-parameters) with a lambda, or with a `ParametersHolder`:

```kotlin
@Composable
fun UserDetail(userId: String) {
    // lambda form
    val presenter = koinInject<UserPresenter> { parametersOf(userId) }

    // holder form
    val presenter2 = koinInject<UserPresenter>(parametersHolder = parametersOf(userId))
}
```

With the lambda form, Koin invokes the lambda on every recomposition to compare the values. The holder form skips that step, which the Koin sources recommend for performance. Parameters are compared by value: when `userId` changes, `koinInject()` resolves a new instance.

## Accessing Koin directly

| Function | Returns |
|----------|---------|
| `getKoin()` | The `Koin` instance of the current composition |
| `currentKoinScope()` | The scope `koinInject()` uses by default |

Both are Composable functions in `org.koin.compose`. Prefer `koinInject()` in UI code.

## Previews

Compose previews do not run your `Application` class. Use `KoinApplicationPreview` to give a preview its own Koin instance: see [Compose Testing](/docs/reference/koin-compose/compose-testing).

## API summary

| API | Purpose | Page |
|-----|---------|------|
| `KoinApplication(configuration) { }` | Start Koin from Compose | This page |
| `koinInject<T>()` | Resolve any dependency | This page |
| `koinViewModel<T>()` | Resolve a ViewModel | [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel) |
| `KoinScope`, `KoinNavigationScope` | Scope bound to a Composable or a destination | [Scopes in Compose](/docs/reference/koin-compose/compose-scopes) |
| `rememberKoinModules { }` | Load modules with a Composable | [Dynamic Modules](/docs/reference/koin-compose/compose-modules) |
| `KoinIsolatedContext` | Use an isolated Koin instance | [Isolated Context](/docs/reference/koin-compose/isolated-context) |
| `navigation<T> { }`, `koinEntryProvider()` | Navigation 3 entries | [Navigation 3](/docs/reference/koin-compose/navigation3) |

## Related

- [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel): `koinViewModel()` and navigation-scoped ViewModels.
- [Lifecycle and State](/docs/reference/koin-compose/compose-lifecycle): how injected objects behave across recomposition.
- [KMP Setup](/docs/reference/koin-core/kmp-setup): start Koin in a Compose Multiplatform project.
- [Android Start](/docs/reference/koin-android/start): `androidContext()` and the Android `Application` class.
- [Compose Testing](/docs/reference/koin-compose/compose-testing): previews and UI tests.

---

# ViewModel in Compose

Source: https://insert-koin.io/docs/reference/koin-compose/compose-viewmodel

This page covers the Compose functions that retrieve a ViewModel: `koinViewModel()`, `sharedKoinViewModel()` and `koinActivityViewModel()`. Declaring a ViewModel in a module, with parameters, `SavedStateHandle` or a ViewModel scope, is the same on every platform: see [ViewModel](/docs/reference/koin-core/viewmodel).

All functions on this page are in `io.insert-koin:koin-compose-viewmodel`, except `sharedKoinViewModel()`, which is in `io.insert-koin:koin-compose-viewmodel-navigation`. See [Koin for Compose](/docs/reference/koin-compose/compose) for the packages.

## koinViewModel

```kotlin
import org.koin.compose.viewmodel.koinViewModel

@Composable
fun UserScreen(viewModel: UserViewModel = koinViewModel()) {
    val state by viewModel.state.collectAsState()
    // ...
}
```

`koinViewModel()` gets the ViewModel from the current `ViewModelStoreOwner` (`LocalViewModelStoreOwner`), and creates it with Koin the first time. The instance lives as long as that owner: an Activity, a Fragment, or a navigation destination.

Declaring it as a default parameter keeps the Composable testable: a test or a preview passes its own instance.

`koinViewModel()` is a Composable function. Call it in the body of a Composable, not in a callback such as `onClick`.

### Parameters

| Parameter | Default | Use |
|-----------|---------|-----|
| `qualifier` | `null` | Pick a [named](/docs/reference/koin-core/qualifiers) ViewModel definition |
| `viewModelStoreOwner` | `LocalViewModelStoreOwner.current` | Store the ViewModel in another owner |
| `key` | `null` | Keep several instances of the same class in one owner |
| `extras` | Extras of the owner | `CreationExtras` used to build `SavedStateHandle` |
| `scope` | `currentKoinScope()` | Koin scope used to resolve the ViewModel |
| `parameters` | `null` | Lambda returning [injected parameters](/docs/reference/koin-core/injection-parameters) |

### Passing parameters

```kotlin
@Composable
fun DetailScreen(itemId: String) {
    val viewModel = koinViewModel<DetailViewModel> { parametersOf(itemId) }
}
```

Parameters are used only when the ViewModel is created. If the same owner already holds a `DetailViewModel`, you get that instance back, even with a different `itemId`. When one owner must hold one ViewModel per value, add a `key`:

```kotlin
@Composable
fun DetailScreen(itemId: String) {
    val viewModel = koinViewModel<DetailViewModel>(key = itemId) {
        parametersOf(itemId)
    }
}
```

With Navigation Compose, each destination has its own owner, so you don't need a `key` for screens on the back stack.

## With Navigation Compose

Inside a `composable { }` destination, the current `ViewModelStoreOwner` is the `NavBackStackEntry`. `koinViewModel()` creates one ViewModel per destination, cleared when the destination is popped. Its `SavedStateHandle` holds the navigation arguments:

```kotlin
@Serializable
data class DetailRoute(val itemId: String)

class DetailViewModel(handle: SavedStateHandle) : ViewModel() {
    val itemId: String = handle.toRoute<DetailRoute>().itemId
}

NavHost(navController, startDestination = HomeRoute) {
    composable<DetailRoute> {
        DetailScreen(viewModel = koinViewModel())
    }
}
```

Koin injects `SavedStateHandle` for you: declare it as a constructor parameter. See [ViewModel](/docs/reference/koin-core/viewmodel) for the declaration side.

:::warning
`koinNavViewModel()` is deprecated, in both `koin-compose-viewmodel-navigation` and `koin-androidx-compose-navigation`. Replace it with `koinViewModel()` and the same parameters: navigation arguments reach `SavedStateHandle` the same way.
:::

### Sharing a ViewModel in a navigation graph

`sharedKoinViewModel()` stores the ViewModel in the back stack entry of the parent graph. Every destination of that graph gets the same instance:

```kotlin
import org.koin.compose.viewmodel.sharedKoinViewModel

navigation<BookGraph>(startDestination = BookList) {
    composable<BookList> { entry ->
        val shared = entry.sharedKoinViewModel<BookSharedViewModel>(navController)
        BookListScreen(shared)
    }
    composable<BookDetail> { entry ->
        val shared = entry.sharedKoinViewModel<BookSharedViewModel>(navController)
        BookDetailScreen(shared)
    }
}
```

The parent graph is `destination.parent?.route` by default. Pass `navGraphRoute` to target another graph. If the destination has no parent graph, `sharedKoinViewModel()` falls back to `koinViewModel()`.

## Activity-wide ViewModel (Android)

`koinActivityViewModel()` stores the ViewModel in the current `ComponentActivity`. Every Composable of that Activity gets the same instance, whatever navigation destination it is in:

```kotlin
import org.koin.compose.viewmodel.koinActivityViewModel

@Composable
fun CartBadge() {
    val cart = koinActivityViewModel<CartViewModel>()
}

@Composable
fun CartScreen() {
    val cart = koinActivityViewModel<CartViewModel>() // same instance as in CartBadge
}
```

It is available on Android only, and fails if `LocalActivity` is not a `ComponentActivity`. It takes the same `qualifier`, `key`, `scope` and `parameters` arguments as `koinViewModel()`.

## Scoped dependencies

A ViewModel can own a scope for its dependencies (`viewModelScope { }` or `@ViewModelScope`). Nothing changes on the Compose side: `koinViewModel()` creates the ViewModel and its scope. The declaration is described in [ViewModel](/docs/reference/koin-core/viewmodel).

## API summary

| API | Owner of the instance | Package |
|-----|-----------------------|---------|
| `koinViewModel()` | `LocalViewModelStoreOwner` (Activity, Fragment, destination) | `koin-compose-viewmodel` |
| `NavBackStackEntry.sharedKoinViewModel()` | Parent navigation graph entry | `koin-compose-viewmodel-navigation` |
| `koinActivityViewModel()` | Current `ComponentActivity` (Android) | `koin-compose-viewmodel` |
| `koinNavViewModel()` | Deprecated, use `koinViewModel()` | `koin-compose-viewmodel-navigation` |

## Related

- [ViewModel](/docs/reference/koin-core/viewmodel): declare ViewModels, parameters, `SavedStateHandle`, ViewModel scope.
- [Android ViewModel](/docs/reference/koin-android/viewmodel): `by viewModel()` in Activities and Fragments.
- [Navigation 3](/docs/reference/koin-compose/navigation3): ViewModels with Navigation 3 entries.
- [Lifecycle and State](/docs/reference/koin-compose/compose-lifecycle): what lives how long in Compose.
- [Compose Testing](/docs/reference/koin-compose/compose-testing): test Composables that use `koinViewModel()`.

---

# Scopes in Compose

Source: https://insert-koin.io/docs/reference/koin-compose/compose-scopes

This page covers the Compose functions that open a Koin scope for a part of the UI tree: `KoinScope`, `KoinNavigationScope`, `UnboundKoinScope`, and the Android `KoinActivityScope` and `KoinFragmentScope`. Inside such a block, `koinInject()` and `koinViewModel()` resolve from that scope. How scopes work and how to declare them is explained in [Scopes](/docs/reference/koin-core/scopes).

Most functions on this page are marked `@KoinExperimentalAPI`. Opt in with `@OptIn(KoinExperimentalAPI::class)`.

## KoinScope

`KoinScope` gets or creates a scope, provides it to its children, and closes it when the Composable leaves the composition.

Declare the scope:

**Compiler Plugin DSL**
```kotlin
class FeatureScope

val featureModule = module {
    scope<FeatureScope> {
        scoped<FeatureCache>()
        scoped<FeatureRepository>()
    }
}
```

**Annotations**
```kotlin
class FeatureScope

@Scope(FeatureScope::class)
class FeatureCache

@Scope(FeatureScope::class)
class FeatureRepository(private val cache: FeatureCache)
```

**Constructor / Classic DSL**
```kotlin
class FeatureScope

val featureModule = module {
    scope<FeatureScope> {
        scopedOf(::FeatureCache)
        scopedOf(::FeatureRepository)
    }
}
```

Open it in Compose:

```kotlin
import org.koin.compose.scope.KoinScope

@Composable
fun FeatureScreen() {
    KoinScope<FeatureScope>(scopeID = "feature") {
        FeatureContent()
    }
}

@Composable
fun FeatureContent() {
    val repository = koinInject<FeatureRepository>() // resolved from the FeatureScope
}
```

`KoinScope` has three forms:

| Form | Scope |
|------|-------|
| `KoinScope<T>(scopeID) { }` | Gets or creates the scope with that id, qualified by type `T` |
| `KoinScope(scopeID, scopeQualifier) { }` | Gets or creates the scope with that id and qualifier |
| `KoinScope(scopeDefinition = { createScope(...) }) { }` | The scope returned by the lambda, which runs on the `Koin` instance |

The scope is closed when the Composable is forgotten (it leaves the composition) or abandoned. A root scope is never closed.

### Multi-screen flows

Put `KoinScope` above a `NavHost` to share scoped objects between the screens of a flow, such as a checkout:

```kotlin
@Composable
fun CheckoutFlow() {
    KoinScope<CheckoutFlowScope>(scopeID = "checkout") {
        NavHost(navController, startDestination = CartRoute) {
            composable<CartRoute> { CartScreen() }
            composable<PaymentRoute> { PaymentScreen() }
        }
    }
}

@Composable
fun PaymentScreen() {
    val state = koinInject<CheckoutState>() // same CheckoutState as in CartScreen
}
```

The scope closes when `CheckoutFlow` leaves the composition.

:::note
A `viewModel` declared in the scope is still stored in the current `ViewModelStoreOwner`. Inside a `NavHost`, each destination gets its own ViewModel instance. Share state between screens through a `scoped` object such as `CheckoutState`, or use `sharedKoinViewModel()` (see [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel)).
:::

## rememberKoinScope

`rememberKoinScope(scope)` binds a scope you created to the composition, without providing it to children. The scope is closed when the Composable leaves the composition:

```kotlin
@Composable
fun FeatureScreen() {
    val koin = getKoin()
    val scope = rememberKoinScope(remember { koin.createScope<FeatureScope>("feature") })
    val repository = koinInject<FeatureRepository>(scope = scope)
}
```

## KoinNavigationScope

`KoinNavigationScope` opens one scope per Navigation Compose destination. It is in `io.insert-koin:koin-compose-viewmodel-navigation`.

Declare the definitions with `navigationScope { }`. It creates a scope qualified by `NavBackStackEntry`:

```kotlin
import org.koin.module.dsl.navigationScope

val appModule = module {
    navigationScope {
        scoped<ScreenStateHolder>()
        viewModel<ScreenViewModel>()
    }
}
```

With annotations or the Constructor DSL, use the same `navigationScope { }` block in a DSL module (with `scopedOf(::ScreenStateHolder)` in the Constructor DSL). There is no annotation for this scope.

Wrap each destination:

```kotlin
NavHost(navController, startDestination = ListRoute) {
    composable<ListRoute> { entry ->
        KoinNavigationScope(entry) {
            ListScreen() // its own ScreenStateHolder
        }
    }
    composable<DetailRoute> { entry ->
        KoinNavigationScope(entry) {
            DetailScreen() // another ScreenStateHolder
        }
    }
}
```

The scope id is `NavBackStackEntry.id`. The scope is not closed when the destination leaves the composition, so it survives while the entry stays on the back stack. It is closed only if the composition is abandoned.

:::warning
`KoinNavigationScope` creates its scope in the global Koin instance (`KoinPlatform.getKoin()`), not in the Koin of the composition. It does not work inside `KoinIsolatedContext`.
:::

## UnboundKoinScope

`UnboundKoinScope` provides a scope you manage yourself. Koin never closes it:

```kotlin
@OptIn(KoinDelicateAPI::class, KoinExperimentalAPI::class)
@Composable
fun SessionArea(sessionScope: Scope) {
    UnboundKoinScope(scope = sessionScope) {
        SessionContent()
    }
}
```

Use it when the scope lifetime does not follow the UI tree: a user session opened at login, a scope shared by several composition roots. It is marked `@KoinDelicateAPI`: you must call `scope.close()` yourself, or the scope and its instances stay in memory.

## Android scopes

These functions are in `io.insert-koin:koin-androidx-compose` (`KoinActivityScope`, `KoinFragmentScope`) and in the Android target of `koin-compose` (`koinActivityInject`). The Activity or Fragment must implement `AndroidScopeComponent`. Declaring Activity and Fragment scopes is covered in [Android Scopes](/docs/reference/koin-android/scope).

```kotlin
class MainActivity : ComponentActivity(), AndroidScopeComponent {
    override val scope: Scope by activityScope()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            KoinActivityScope {
                MainScreen()
            }
        }
    }
}

@Composable
fun MainScreen() {
    val presenter = koinInject<MainPresenter>() // resolved from the Activity scope
}
```

`KoinFragmentScope { }` does the same in a `ComposeView` hosted by a Fragment.

`koinActivityInject()` resolves from the Activity scope at any depth, without a wrapping block:

```kotlin
@Composable
fun DeepNestedScreen() {
    val session: SessionManager = koinActivityInject()
}
```

It fails if `LocalActivity` does not implement `AndroidScopeComponent`.

## Comparison

| API | Scope lifetime | Closed by |
|-----|----------------|-----------|
| `KoinScope` | The Composable | Koin, when the Composable leaves the composition |
| `rememberKoinScope` | The Composable | Koin, when the Composable leaves the composition |
| `KoinNavigationScope` | The back stack entry | Koin, only if the composition is abandoned |
| `UnboundKoinScope` | Yours | You |
| `KoinActivityScope` | The Activity | The Activity scope (`activityScope()`) |
| `KoinFragmentScope` | The Fragment | The Fragment scope (`fragmentScope()`) |

## Related

- [Scopes](/docs/reference/koin-core/scopes): declare scopes, link them, close them.
- [Android Scopes](/docs/reference/koin-android/scope): Activity, Fragment and ViewModel scopes.
- [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel): share a ViewModel across a navigation graph.
- [Lifecycle and State](/docs/reference/koin-compose/compose-lifecycle): what each Compose API releases and when.
- [Dynamic Modules](/docs/reference/koin-compose/compose-modules): load modules with a Composable.

---

# Lifecycle and State

Source: https://insert-koin.io/docs/reference/koin-compose/compose-lifecycle

This page explains how objects injected with Koin behave in the Compose lifecycle: what happens on recomposition, what each Koin API releases when a Composable leaves the composition, and where to place injection calls. It assumes you know `koinInject()` and `koinViewModel()` (see [Koin for Compose](/docs/reference/koin-compose/compose)) and the [Compose lifecycle](https://developer.android.com/develop/ui/compose/lifecycle).

## Recomposition

`koinInject()` resolves the dependency once and keeps it with `remember`, keyed on the qualifier, the scope and the parameters:

```kotlin
@Composable
fun UserScreen(userId: String) {
    val repository = koinInject<UserRepository>() // resolved once
    val presenter = koinInject<UserPresenter> { parametersOf(userId) } // resolved again when userId changes
}
```

On a recomposition with the same keys, you get the same object. When a key changes (a new `userId`), Koin resolves again. For a `single`, that returns the same instance. For a `factory`, that creates a new one.

`koinViewModel()` does not use `remember`: the ViewModel is stored in the `ViewModelStoreOwner` and survives recomposition and Android configuration changes. Its parameters are used only at creation (see [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel)).

Both are Composable functions, so they can't be called inside `remember { }`, `LaunchedEffect` or an `onClick` lambda. Call them in the Composable body and use the result inside the lambda:

```kotlin
@Composable
fun SaveButton() {
    val repository = koinInject<UserRepository>()

    Button(onClick = { repository.save() }) {
        Text("Save")
    }
}
```

## What is released, and when

| API | On recomposition | When the Composable leaves the composition |
|-----|------------------|--------------------------------------------|
| `koinInject()` | Same object if keys are unchanged | Reference dropped. Koin keeps a `single` or `scoped` instance |
| `koinViewModel()` | Same ViewModel | Nothing. The ViewModel is cleared with its `ViewModelStoreOwner` |
| `KoinApplication` | Same Koin instance | Koin keeps running. Stopped only if the composition is abandoned |
| `KoinScope`, `rememberKoinScope` | Same scope | Scope closed |
| `KoinNavigationScope` | Same scope | Scope kept. Closed only if the composition is abandoned |
| `UnboundKoinScope` | Same scope | Nothing. You close the scope |
| `rememberKoinModules` | Modules loaded once | Modules unloaded only if you set `unloadOnForgotten` |

Details: [Scopes in Compose](/docs/reference/koin-compose/compose-scopes), [Dynamic Modules](/docs/reference/koin-compose/compose-modules).

## Where to inject

Inject at the screen level and pass plain data and lambdas down. Child Composables then don't depend on Koin, and previews and tests don't need a Koin instance:

```kotlin
@Composable
fun UserListScreen(viewModel: UserListViewModel = koinViewModel()) {
    val users by viewModel.users.collectAsState()
    UserList(users = users, onDelete = viewModel::delete)
}

@Composable
fun UserList(users: List<User>, onDelete: (User) -> Unit) {
    LazyColumn {
        items(users) { user -> UserCard(user, onDelete) }
    }
}
```

Avoid `koinInject()` inside `LazyColumn` items: each item runs its own resolution and `remember`. Inject once in the parent and pass the object or a lambda.

### Pass as a parameter or inject?

| Pass as a parameter | Inject with Koin |
|---------------------|------------------|
| Values that change: ids, search query, selection | Long-lived services: repositories, use cases |
| Navigation arguments | Infrastructure: database, HTTP client |
| Data the parent already has | ViewModels |

```kotlin
@Composable
fun UserProfile(
    userId: String,                              // changes: pass it
    repository: UserRepository = koinInject()   // service: inject it
) {
    var user by remember { mutableStateOf<User?>(null) }

    LaunchedEffect(userId) {
        user = repository.getUser(userId)
    }

    user?.let { ProfileContent(it) }
}
```

## Injected objects and stability

Koin does not change how Compose sees a type. A Composable parameter of type `UserRepository` or `UserViewModel` is stable or unstable according to the Compose compiler rules, like any other class. If skipping matters for a Composable, pass it stable values (state, primitives, lambdas) instead of the injected object.

## Side effects

Injected objects are regular Kotlin objects: use them in `LaunchedEffect`, `DisposableEffect` or `SideEffect` like any other value. Resolve them in the Composable body first:

```kotlin
@Composable
fun EventScreen() {
    val eventBus = koinInject<EventBus>()

    DisposableEffect(eventBus) {
        val listener = eventBus.subscribe { event -> /* ... */ }
        onDispose { eventBus.unsubscribe(listener) }
    }
}
```

## Related

- [Koin for Compose](/docs/reference/koin-compose/compose): `koinInject()` and starting Koin.
- [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel): ViewModel owners and parameters.
- [Scopes in Compose](/docs/reference/koin-compose/compose-scopes): scopes bound to the UI tree.
- [Dynamic Modules](/docs/reference/koin-compose/compose-modules): load and unload modules with a Composable.
- [Compose Testing](/docs/reference/koin-compose/compose-testing): previews and UI tests.

---

# Dynamic Modules

Source: https://insert-koin.io/docs/reference/koin-compose/compose-modules

This page covers `rememberKoinModules`, which loads Koin modules when a Composable enters the composition and can unload them when it leaves. Use it to load the definitions of a feature only when its screen is shown. You should know how to declare [modules](/docs/reference/koin-core/modules).

`rememberKoinModules` is in `io.insert-koin:koin-compose` and is marked `@KoinExperimentalAPI`.

## rememberKoinModules

```kotlin
import org.koin.compose.module.rememberKoinModules

val checkoutModule = module {
    factory<CheckoutRepository>()
    viewModel<CheckoutViewModel>()
}

@OptIn(KoinExperimentalAPI::class)
@Composable
fun CheckoutScreen() {
    rememberKoinModules(unloadOnForgotten = true) { listOf(checkoutModule) }

    val viewModel = koinViewModel<CheckoutViewModel>()
}
```

The lambda returns the modules to load. Koin loads them into the Koin instance of the composition the first time `CheckoutScreen` is composed. Recompositions don't load them again.

Call `rememberKoinModules` before the `koinInject()` or `koinViewModel()` calls that need its definitions.

## Unloading

By default, the modules stay loaded after the Composable leaves the composition. Three parameters control unloading:

| Parameter | Default | Effect |
|-----------|---------|--------|
| `unloadOnForgotten` | `unloadModules` | Unload when the Composable leaves the composition |
| `unloadOnAbandoned` | `unloadModules` | Unload if the composition is abandoned |
| `unloadModules` | `false` | Default value for both parameters above |

```kotlin
// unload in both cases
rememberKoinModules(unloadModules = true) { listOf(checkoutModule) }
```

Unloading removes the definitions and drops their `single` instances. Code that still holds a reference to an instance keeps it, but Koin can no longer resolve that type. Don't unload a module that another screen still uses.

## Loading per destination

Call `rememberKoinModules` in a navigation destination to load a feature when the user navigates to it:

```kotlin
NavHost(navController, startDestination = HomeRoute) {
    composable<HomeRoute> {
        HomeScreen()
    }
    composable<CheckoutRoute> {
        rememberKoinModules(unloadOnForgotten = true) { listOf(checkoutModule) }
        CheckoutScreen()
    }
}
```

## Module styles

**Compiler Plugin DSL**
```kotlin
val checkoutModule = module {
    factory<CheckoutRepository>()
    viewModel<CheckoutViewModel>()
}
```

**Annotations**
`rememberKoinModules` takes `Module` values. Annotated `@Module` classes are loaded at start through `@KoinApplication` (see [Modules](/docs/reference/koin-core/modules)). To load a feature on demand, declare its module with the DSL.

**Constructor / Classic DSL**
```kotlin
val checkoutModule = module {
    factoryOf(::CheckoutRepository)
    viewModelOf(::CheckoutViewModel)
}
```

## Limits

- **Main thread**: modules are loaded synchronously during composition. A large module adds to the time of that frame. To load modules in the background at start, see [Lazy Modules](/docs/reference/koin-core/lazy-modules).
- **Overrides**: a module loaded later wins over an earlier definition of the same type (see [Definitions](/docs/reference/koin-core/definitions)). Unloading it does not restore the earlier definition.
- **Previews**: `rememberKoinModules` needs a running Koin instance. For previews, use `KoinApplicationPreview` (see [Compose Testing](/docs/reference/koin-compose/compose-testing)).

## Related

- [Modules](/docs/reference/koin-core/modules): declare and compose modules.
- [Lazy Modules](/docs/reference/koin-core/lazy-modules): load modules in the background at start.
- [Starting Koin](/docs/reference/koin-core/starting-koin): load and unload modules outside Compose.
- [Scopes in Compose](/docs/reference/koin-compose/compose-scopes): instances bound to a Composable.
- [Lifecycle and State](/docs/reference/koin-compose/compose-lifecycle): what each Compose API releases and when.

---

# Isolated Context in Compose

Source: https://insert-koin.io/docs/reference/koin-compose/isolated-context

This page shows how to make Compose functions resolve from an isolated Koin instance with `KoinIsolatedContext`. Use it when you build an SDK or a library that ships Composables and must not share the host app's Koin container. What an isolated context is, and how to create one, is explained in [Context Isolation](/docs/reference/koin-core/context-isolation).

## KoinIsolatedContext

Keep the isolated `KoinApplication` in a static holder, as described in [Context Isolation](/docs/reference/koin-core/context-isolation):

**Compiler Plugin DSL**
```kotlin
object PaymentSdkKoin {
    val koinApp = koinApplication {
        modules(paymentModule)
    }
}

internal val paymentModule = module {
    single<PaymentProcessor>()
    viewModel<PaymentViewModel>()
}
```

**Annotations**
```kotlin
import org.koin.plugin.module.dsl.koinApplication

@Module
@ComponentScan("com.example.paymentsdk")
internal class PaymentModule

@KoinApplication(modules = [PaymentModule::class])
internal object PaymentSdkApp

object PaymentSdkKoin {
    val koinApp = koinApplication<PaymentSdkApp>()
}
```

**Constructor / Classic DSL**
```kotlin
object PaymentSdkKoin {
    val koinApp = koinApplication {
        modules(paymentModule)
    }
}

internal val paymentModule = module {
    singleOf(::PaymentProcessor)
    viewModelOf(::PaymentViewModel)
}
```

Wrap the SDK UI with `KoinIsolatedContext`:

```kotlin
import org.koin.compose.KoinIsolatedContext

@Composable
fun PaymentScreen(amount: Double, onDone: (PaymentResult) -> Unit) {
    KoinIsolatedContext(context = PaymentSdkKoin.koinApp) {
        PaymentFlow(amount, onDone)
    }
}

@Composable
private fun PaymentFlow(amount: Double, onDone: (PaymentResult) -> Unit) {
    val viewModel = koinViewModel<PaymentViewModel>() // resolved from the SDK's Koin
    // ...
}
```

Inside the block, `koinInject()`, `koinViewModel()`, `getKoin()`, `currentKoinScope()` and `rememberKoinModules()` use the isolated instance. Outside the block, the host app keeps its own Koin.

## Host and SDK in the same screen

Resolve host dependencies outside the block, and SDK dependencies inside:

```kotlin
@Composable
fun CheckoutScreen() {
    val analytics = koinInject<HostAnalytics>() // host app's Koin

    KoinIsolatedContext(context = PaymentSdkKoin.koinApp) {
        val processor = koinInject<PaymentProcessor>() // SDK's Koin
        PaymentButton(processor, onEvent = { analytics.track(it) })
    }
}
```

The two containers don't see each other. Pass values across the boundary with parameters and callbacks.

## Initialization and shutdown

When the SDK needs configuration from the host, create the `KoinApplication` in an `initialize` function and close it on shutdown:

```kotlin
object PaymentSdk {
    private var koinApp: KoinApplication? = null

    fun initialize(config: PaymentConfig) {
        koinApp = koinApplication {
            modules(module { single { config } }, paymentModule)
        }
    }

    fun shutdown() {
        koinApp?.close()
        koinApp = null
    }

    @Composable
    fun PaymentScreen(amount: Double, onDone: (PaymentResult) -> Unit) {
        val app = koinApp ?: error("PaymentSdk.initialize() was not called")
        KoinIsolatedContext(context = app) {
            PaymentFlow(amount, onDone)
        }
    }
}
```

The host calls `PaymentSdk.initialize(...)` once, for example in `Application.onCreate()`, before any SDK screen is shown.

## Limits

- **KoinNavigationScope**: it creates its scope in the global Koin instance, so it does not follow `KoinIsolatedContext`. Use `KoinScope` inside the isolated block instead (see [Scopes in Compose](/docs/reference/koin-compose/compose-scopes)).
- **Code outside Compose**: SDK classes receive their dependencies through their constructors, from the isolated instance. An SDK entry point outside Compose (a `Service`, a callback called by the host) that must retrieve dependencies itself uses a `KoinComponent` that overrides `getKoin()`. See [Context Isolation](/docs/reference/koin-core/context-isolation).
- **Lifecycle**: `KoinIsolatedContext` does not start or stop the instance. You own its lifetime.

## Related

- [Context Isolation](/docs/reference/koin-core/context-isolation): create an isolated Koin instance and a custom `KoinComponent`.
- [Koin for Compose](/docs/reference/koin-compose/compose): `KoinApplication` and `koinInject()`.
- [Scopes in Compose](/docs/reference/koin-compose/compose-scopes): scopes inside an isolated block.
- [Isolated Context in Ktor](/docs/reference/koin-ktor/ktor-isolated): the same concept for a Ktor server.

---

# Navigation 3

Source: https://insert-koin.io/docs/reference/koin-compose/navigation3

This page shows how to declare [Navigation 3](https://developer.android.com/guide/navigation/navigation-3) entries in Koin modules and pass them to `NavDisplay`. Each feature module contributes its own screens, and the app collects them all with one entry provider. It assumes you know the Navigation 3 basics (back stack, `NavDisplay`, `NavEntry`) and [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel).

All APIs on this page are marked `@KoinExperimentalAPI`.

## Setup

```kotlin
// shared/build.gradle.kts, or app/build.gradle.kts on Android
plugins {
    kotlin("plugin.serialization")
}

commonMain.dependencies {
    implementation("io.insert-koin:koin-compose-navigation3:$koin_version")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:$serialization_version")
}
```

`koin-compose-navigation3` targets Android, iOS, JVM desktop, JS and Wasm.

## Declaring entries

Routes are `@Serializable` classes:

```kotlin
@Serializable data object HomeRoute
@Serializable data class DetailRoute(val itemId: String)
```

Declare one `navigation<T> { }` per route in your modules. The lambda is a Composable that receives the route:

```kotlin
import org.koin.dsl.navigation3.navigation

val homeModule = module {
    viewModel<HomeViewModel>()

    navigation<HomeRoute> {
        HomeScreen(viewModel = koinViewModel())
    }
}

val detailModule = module {
    viewModel<DetailViewModel>()

    navigation<DetailRoute> { route ->
        DetailScreen(viewModel = koinViewModel { parametersOf(route.itemId) })
    }
}
```

Each `navigation<T>` is stored as a definition qualified by the route type. The lambda runs with the Koin `Scope` as receiver, so you can call `get<T>()` in it, as well as Composable functions such as `koinViewModel()`.

## Building the entry provider

`koinEntryProvider()` collects every `navigation<T>` entry of the current scope into one provider for `NavDisplay`:

```kotlin
import org.koin.compose.navigation3.koinEntryProvider

@Composable
fun App() {
    val backStack = remember { mutableStateListOf<Any>(HomeRoute) }

    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeLastOrNull() },
        entryProvider = koinEntryProvider()
    )
}
```

With `rememberNavBackStack()`, your routes implement `NavKey`. Use `koinEntryProvider<NavKey>()` to match the back stack type.

### From an Android Activity

On Android, two extensions on `ComponentCallbacks` build the provider from the Activity or Fragment scope:

| Function | Behavior |
|----------|----------|
| `entryProvider<T>()` | Lazy delegate: `val provider by entryProvider<Any>()` |
| `getEntryProvider<T>()` | Builds the provider now |

They resolve from the component's Koin scope: the Activity scope if it implements `AndroidScopeComponent`, the root scope otherwise.

## Entries in a scope

Declare entries inside a scope when the screens need objects that live with that scope. With `activityRetainedScope`, they survive configuration changes:

```kotlin
class Navigator(start: Any) {
    val backStack = mutableStateListOf(start)
    fun goTo(route: Any) { backStack.add(route) }
    fun goBack() { backStack.removeLastOrNull() }
}

val appModule = module {
    activityRetainedScope {
        scoped { Navigator(start = ConversationList) }

        navigation<ConversationList> {
            val navigator = get<Navigator>()
            ConversationListScreen(onClick = { navigator.goTo(ConversationDetail(it)) })
        }

        navigation<ConversationDetail> { route ->
            ConversationDetailScreen(conversationId = route.id)
        }
    }
}

class MainActivity : ComponentActivity(), AndroidScopeComponent {
    override val scope: Scope by activityRetainedScope()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            val navigator: Navigator = get()
            NavDisplay(
                backStack = navigator.backStack,
                onBack = { navigator.goBack() },
                entryProvider = getEntryProvider()
            )
        }
    }
}
```

`getEntryProvider()` reads the entries from the Activity scope. Entries declared in a scope are visible only from that scope. `activityRetainedScope` is described in [Android Scopes](/docs/reference/koin-android/scope).

## ViewModels for an entry

To scope a ViewModel to its entry, add the ViewModel store decorator to `NavDisplay`. Without it, `koinViewModel()` uses the store of the Activity, and every entry of the same route shares one instance:

```kotlin
NavDisplay(
    backStack = backStack,
    onBack = { backStack.removeLastOrNull() },
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        rememberViewModelStoreNavEntryDecorator()
    ),
    entryProvider = koinEntryProvider()
)
```

Pass the route, or a field of it, as a parameter:

**Compiler Plugin DSL**
```kotlin
class DetailViewModel(
    @InjectedParam val route: DetailRoute,
    private val repository: ItemRepository
) : ViewModel()

val detailModule = module {
    viewModel<DetailViewModel>()

    navigation<DetailRoute> { route ->
        DetailScreen(viewModel = koinViewModel { parametersOf(route) })
    }
}
```

**Annotations**
```kotlin
@KoinViewModel
class DetailViewModel(
    @InjectedParam val route: DetailRoute,
    private val repository: ItemRepository
) : ViewModel()

// navigation<T> entries are declared in a DSL module
val detailModule = module {
    navigation<DetailRoute> { route ->
        DetailScreen(viewModel = koinViewModel { parametersOf(route) })
    }
}
```

**Constructor / Classic DSL**
```kotlin
class DetailViewModel(
    val route: DetailRoute,
    private val repository: ItemRepository
) : ViewModel()

val detailModule = module {
    viewModelOf(::DetailViewModel) // route comes from parametersOf(route)

    navigation<DetailRoute> { route ->
        DetailScreen(viewModel = koinViewModel { parametersOf(route) })
    }
}
```

## Entry metadata

`navigation<T>` takes a `metadata` map, passed to the `NavEntry`. Use it for per-entry transitions or scene strategies such as list-detail:

```kotlin
val conversationModule = module {
    navigation<ConversationList>(metadata = ListDetailSceneStrategy.listPane()) {
        ConversationListScreen()
    }

    navigation<ConversationDetail>(metadata = ListDetailSceneStrategy.detailPane()) { route ->
        ConversationDetailScreen(route.id)
    }

    navigation<ModalRoute>(
        metadata = NavDisplay.transitionSpec {
            slideInVertically(initialOffsetY = { it }) togetherWith ExitTransition.KeepUntilTransitionsFinished
        }
    ) {
        ModalScreen()
    }
}
```

Then pass the scene strategy to `NavDisplay` (`sceneStrategy = rememberListDetailSceneStrategy()`). The metadata keys come from Navigation 3 and the adaptive libraries, not from Koin.

## From Navigation 2

| Navigation 2 | Navigation 3 with Koin |
|--------------|------------------------|
| String or typed route in `NavHost { composable(...) }` | `@Serializable` route class |
| `composable<Route> { ... }` in the `NavHost` | `navigation<Route> { ... }` in a Koin module |
| `NavHost(navController, startDestination)` | `NavDisplay(backStack, entryProvider = koinEntryProvider())` |
| Arguments read from `SavedStateHandle` | Route object passed to the lambda |

## API summary

| API | Package | Purpose |
|-----|---------|---------|
| `Module.navigation<T>(metadata) { }` | `org.koin.dsl.navigation3` | Declare an entry in a module |
| `ScopeDSL.navigation<T>(metadata) { }` | `org.koin.dsl.navigation3` | Declare an entry in a scope |
| `koinEntryProvider<T>(scope)` | `org.koin.compose.navigation3` | Entry provider from the current Compose scope |
| `entryProvider<T>()`, `getEntryProvider<T>()` | `org.koin.androidx.compose.navigation3` | Entry provider from an Activity or Fragment (Android) |

## Related

- [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel): `koinViewModel()` and its owners.
- [Android Scopes](/docs/reference/koin-android/scope): `activityRetainedScope` and Activity scopes.
- [Injected Parameters](/docs/reference/koin-core/injection-parameters): `parametersOf` and `@InjectedParam`.
- [Koin for Compose](/docs/reference/koin-compose/compose): packages and starting Koin.
- [Navigation 3 recipes](https://github.com/android/nav3-recipes): Google's samples for Navigation 3 itself.

---

# Kotlin Multiplatform Setup

Source: https://insert-koin.io/docs/reference/koin-core/kmp-setup

This page sets up Koin in a Kotlin Multiplatform (KMP) project: Gradle dependencies, where the Koin code goes, one shared function that starts Koin, and how each platform calls it. It assumes you know [modules](/docs/reference/koin-core/modules) and [Starting Koin](/docs/reference/koin-core/starting-koin). How to give each platform its own implementations is covered in [KMP Sharing Patterns](/docs/reference/koin-core/kmp-shared-modules).

## Supported targets

`koin-core` and the Compiler Plugin support every Kotlin target:

| Target | Supported |
|--------|-----------|
| Android | Yes |
| iOS (`iosArm64`, `iosX64`, `iosSimulatorArm64`) | Yes |
| JVM (desktop, server) | Yes |
| JS and Wasm (`js`, `wasmJs`) | Yes |
| macOS, Linux, Windows (Kotlin/Native) | Yes |

Compose artifacts follow the targets of Compose Multiplatform. See the artifact table in [Gradle Setup](/docs/setup/gradle).

## Dependencies

Apply the [Koin Compiler Plugin](/docs/setup/compiler-plugin) to the shared module and add Koin to the source sets:

```kotlin
// shared/build.gradle.kts
plugins {
    kotlin("multiplatform")
    alias(libs.plugins.koin.compiler)
}

kotlin {
    androidTarget()
    iosArm64()
    iosSimulatorArm64()
    jvm()

    sourceSets {
        commonMain.dependencies {
            implementation(project.dependencies.platform(libs.koin.bom))
            implementation(libs.koin.core)
            implementation(libs.koin.annotations) // only with annotations

            // Compose Multiplatform
            implementation(libs.koin.compose)
            implementation(libs.koin.compose.viewmodel)
        }
        androidMain.dependencies {
            implementation(libs.koin.android)
        }
        commonTest.dependencies {
            implementation(libs.koin.test)
        }
    }
}
```

The Compiler Plugin runs on every target from one declaration. There is no per-target configuration, unlike the KSP setup of Koin Annotations 1.x (see [Migrating from KSP](/docs/migration/from-ksp-to-compiler-plugin)).

## Project structure

```
shared/
└── src/
    ├── commonMain/kotlin/di/
    │   ├── Koin.kt              // modules and initKoin()
    │   └── PlatformModule.kt    // expect declaration
    ├── androidMain/kotlin/di/
    │   └── PlatformModule.android.kt
    └── iosMain/kotlin/di/
        └── PlatformModule.ios.kt
androidApp/   // Application class calls initKoin()
iosApp/       // Swift App calls initKoin()
```

Shared definitions live in `commonMain`. Each platform source set only contains what differs per platform.

## Shared start function

Write one function in `commonMain` that starts Koin. Each platform calls it, and can add its own configuration through the `config` parameter:

**Compiler Plugin DSL**
```kotlin
// commonMain/kotlin/di/Koin.kt
import org.koin.core.context.startKoin
import org.koin.dsl.KoinAppDeclaration
import org.koin.dsl.includes
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*

val dataModule = module {
    single<UserRepository>()
    viewModel<UserViewModel>()
}

val appModule = module {
    includes(dataModule, platformModule())
}

fun initKoin(config: KoinAppDeclaration? = null) {
    startKoin {
        includes(config)
        modules(appModule)
    }
}
```

**Annotations**
```kotlin
// commonMain/kotlin/di/Koin.kt
import org.koin.core.annotation.*
import org.koin.dsl.KoinAppDeclaration
import org.koin.dsl.includes
import org.koin.plugin.module.dsl.startKoin

@Module(includes = [PlatformModule::class])
@ComponentScan("com.example.app")
@Configuration
class AppModule

@KoinApplication
object KoinApp

fun initKoin(config: KoinAppDeclaration? = null) {
    startKoin<KoinApp> {
        includes(config)
    }
}
```

`@Configuration` modules are found by `@KoinApplication` at build time. `PlatformModule` is an `expect` module class, see [KMP Sharing Patterns](/docs/reference/koin-core/kmp-shared-modules).

**Constructor / Classic DSL**
```kotlin
// commonMain/kotlin/di/Koin.kt
import org.koin.core.context.startKoin
import org.koin.core.module.dsl.*
import org.koin.dsl.KoinAppDeclaration
import org.koin.dsl.includes
import org.koin.dsl.module

val dataModule = module {
    singleOf(::UserRepository)
    viewModelOf(::UserViewModel)
}

val appModule = module {
    includes(dataModule, platformModule())
}

fun initKoin(config: KoinAppDeclaration? = null) {
    startKoin {
        includes(config)
        modules(appModule)
    }
}
```

`includes(config)` applies the platform configuration (Android context, logger, extra modules) to the same Koin start. `platformModule()` is an `expect` function, see [KMP Sharing Patterns](/docs/reference/koin-core/kmp-shared-modules).

## Platform entry points

### Android

Call `initKoin` from your `Application` class and pass the Android context:

```kotlin
// androidApp
class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        initKoin {
            androidContext(this@MainApplication)
            androidLogger()
        }
    }
}
```

Android definitions can then use `Context` as a constructor parameter. See [Android Start](/docs/reference/koin-android/start).

### iOS

Add a function without parameters in `iosMain`, and call it from the Swift `App` initializer:

```kotlin
// iosMain/kotlin/di/KoinIos.kt
fun initKoinIos() = initKoin()
```

```swift
// iosApp/iOSApp.swift
import Shared

@main
struct iOSApp: App {
    init() {
        KoinIosKt.doInitKoinIos()
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}
```

Kotlin/Native naming rules explain the Swift call. Top-level functions of `KoinIos.kt` are exported in a class named `KoinIosKt`. A function whose name starts with `init` gets a `do` prefix, so `initKoinIos` becomes `doInitKoinIos`. The helper avoids passing a Kotlin lambda (`config`) from Swift.

Calling Koin from Swift code is covered in [KMP Platform Integration](/docs/reference/koin-mp/kmp).

### JVM desktop

```kotlin
// jvmMain
fun main() = application {
    initKoin {
        printLogger()
    }
    Window(onCloseRequest = ::exitApplication) {
        App()
    }
}
```

### Web

```kotlin
// jsMain or wasmJsMain
fun main() {
    initKoin()
    // start your UI
}
```

## Compose Multiplatform

With Compose Multiplatform, you can start Koin from the root Composable with `KoinApplication` instead of calling `initKoin` on each platform. On Android, it sets the Android context for you:

**Compiler Plugin DSL**
```kotlin
// commonMain
@Composable
fun App() {
    KoinApplication(configuration = koinConfiguration { modules(appModule) }) {
        MainScreen()
    }
}
```

**Annotations**
```kotlin
// commonMain
@Composable
fun App() {
    KoinApplication(configuration = koinConfiguration<KoinApp>()) {
        MainScreen()
    }
}
```

`koinConfiguration<T>()` comes from `org.koin.plugin.module.dsl`.

**Constructor / Classic DSL**
```kotlin
// commonMain
@Composable
fun App() {
    KoinApplication(configuration = koinConfiguration { modules(appModule) }) {
        MainScreen()
    }
}
```

Keep `initKoin` if code outside Compose needs Koin before the first screen (a background service, Swift code). Both options are compared in [Koin for Compose](/docs/reference/koin-compose/compose).

## Related

- [KMP Sharing Patterns](/docs/reference/koin-core/kmp-shared-modules): platform modules and `expect`/`actual` definitions.
- [KMP Platform Integration](/docs/reference/koin-mp/kmp): Android context in shared code, Swift interop, desktop and web.
- [Koin for Compose](/docs/reference/koin-compose/compose): `KoinApplication` and `koinInject()`.
- [ViewModel](/docs/reference/koin-core/viewmodel): ViewModels shared by Android and Compose Multiplatform.
- [Gradle Setup](/docs/setup/gradle): BOM, version catalog, artifact list.

---

# KMP Sharing Patterns

Source: https://insert-koin.io/docs/reference/koin-core/kmp-shared-modules

This page covers how to declare definitions that differ per platform in a Kotlin Multiplatform project: a platform module with `expect`/`actual`, an `expect`/`actual` class, and an interface with one implementation per platform. It assumes your project is set up as in [KMP Setup](/docs/reference/koin-core/kmp-setup). For the Kotlin rules of `expect`/`actual`, see the [Kotlin documentation](https://kotlinlang.org/docs/multiplatform/multiplatform-expect-actual.html).

## Organizing shared modules

Put everything that doesn't depend on a platform in `commonMain` modules, split by layer or by feature, and assemble them with `includes()`:

```kotlin
// commonMain
val dataModule = module {
    single<ApiClient>()
    single<UserRepository>()
}

val domainModule = module {
    factory<GetUserUseCase>()
}

val appModule = module {
    includes(dataModule, domainModule, platformModule())
}
```

Module composition is described in [Modules](/docs/reference/koin-core/modules). The rest of this page is about `platformModule()`: the part that differs per platform.

## Platform module

Declare the module in `commonMain` with `expect`, and write one `actual` per platform. Each platform module declares its own classes:

**Compiler Plugin DSL**
```kotlin
// commonMain
interface PlatformComponent {
    fun getInfo(): String
}

expect fun platformModule(): Module
```

```kotlin
// androidMain
class AndroidComponent(private val context: Context) : PlatformComponent {
    override fun getInfo() = "Android ${context.packageName}"
}

actual fun platformModule(): Module = module {
    single<AndroidComponent>() bind PlatformComponent::class
}
```

```kotlin
// iosMain
class IOSComponent : PlatformComponent {
    override fun getInfo() = "iOS"
}

actual fun platformModule(): Module = module {
    single<IOSComponent>() bind PlatformComponent::class
}
```

**Annotations**
```kotlin
// commonMain
interface PlatformComponent {
    fun getInfo(): String
}

@Module
expect class PlatformModule
```

```kotlin
// androidMain
@Module
@ComponentScan
actual class PlatformModule

@Singleton
class AndroidComponent(private val context: Context) : PlatformComponent {
    override fun getInfo() = "Android ${context.packageName}"
}
```

```kotlin
// iosMain
@Module
@ComponentScan
actual class PlatformModule

@Singleton
class IOSComponent : PlatformComponent {
    override fun getInfo() = "iOS"
}
```

Each `actual` module scans its own source set, so it only finds the classes of that platform. `@Singleton` binds the class to its supertypes, so `PlatformComponent` resolves to the platform class. Include `PlatformModule` from a common module with `@Module(includes = [PlatformModule::class])`.

**Constructor / Classic DSL**
```kotlin
// commonMain
interface PlatformComponent {
    fun getInfo(): String
}

expect fun platformModule(): Module
```

```kotlin
// androidMain
actual fun platformModule(): Module = module {
    singleOf(::AndroidComponent) bind PlatformComponent::class
}
```

```kotlin
// iosMain
actual fun platformModule(): Module = module {
    singleOf(::IOSComponent) bind PlatformComponent::class
}
```

Use this pattern when platform implementations need different constructor parameters. Common code depends on the `PlatformComponent` interface only, and each platform is free to inject what it needs (here, `Context` on Android). On Android, `Context` resolves once `androidContext()` is set at start (see [KMP Setup](/docs/reference/koin-core/kmp-setup)).

### Platform libraries

Platform drivers and engines (SQLDelight, Ktor client engines, settings) are built with a function call. Declare them in the platform module with a lambda:

```kotlin
// androidMain
actual fun platformModule(): Module = module {
    single<SqlDriver> { AndroidSqliteDriver(AppDatabase.Schema, androidContext(), "app.db") }
    single<HttpClientEngine> { OkHttp.create() }
}

// iosMain
actual fun platformModule(): Module = module {
    single<SqlDriver> { NativeSqliteDriver(AppDatabase.Schema, "app.db") }
    single<HttpClientEngine> { Darwin.create() }
}
```

The common module then builds on them without knowing the platform: `single { AppDatabase(get()) }`, `single { HttpClient(get<HttpClientEngine>()) }`. For other ways to declare classes you don't own, see [Definitions](/docs/reference/koin-core/definitions).

## expect/actual class

When the class has the same constructor on every platform, declare it once in common code and let each platform implement it:

**Compiler Plugin DSL**
```kotlin
// commonMain
expect class NativeComponent() {
    fun getInfo(): String
}

val nativeComponentModule = module {
    single<NativeComponent>()
}
```

```kotlin
// androidMain
actual class NativeComponent actual constructor() {
    actual fun getInfo() = "Android NativeComponent"
}

// iosMain
actual class NativeComponent actual constructor() {
    actual fun getInfo() = "iOS NativeComponent"
}
```

**Annotations**
```kotlin
// commonMain
@Module
@ComponentScan
class NativeComponentModule

@Singleton
expect class NativeComponent() {
    fun getInfo(): String
}
```

```kotlin
// androidMain
@Singleton
actual class NativeComponent actual constructor() {
    actual fun getInfo() = "Android NativeComponent"
}

// iosMain
@Singleton
actual class NativeComponent actual constructor() {
    actual fun getInfo() = "iOS NativeComponent"
}
```

You can also declare the `expect` class through a provider function of a common `@Module` class:

```kotlin
// commonMain
@Module
class NativeModule {
    @Factory
    fun nativeComponent(): NativeComponent = NativeComponent()
}
```

**Constructor / Classic DSL**
```kotlin
// commonMain
expect class NativeComponent() {
    fun getInfo(): String
}

val nativeComponentModule = module {
    singleOf(::NativeComponent)
}
```

The `actual` classes are the same as in the other tabs.

An `expect` class has one constructor contract for all platforms. If a platform needs another dependency (an Android `Context`, for example), you can't add it to that platform only. Use the [platform module](#platform-module) pattern with an interface instead, or a platform wrapper (see [KMP Platform Integration](/docs/reference/koin-mp/kmp)).

## Components on one platform only

A platform module can declare classes that exist on one platform and nowhere else. The other platforms keep an empty module:

**Compiler Plugin DSL**
```kotlin
// androidMain
actual fun platformModule(): Module = module {
    single<NotificationHelper>()
}

// iosMain
actual fun platformModule(): Module = module { }
```

**Annotations**
```kotlin
// androidMain
@Module
@ComponentScan("com.example.app.android")
actual class PlatformModule

// iosMain: nothing to declare
@Module
actual class PlatformModule
```

**Constructor / Classic DSL**
```kotlin
// androidMain
actual fun platformModule(): Module = module {
    singleOf(::NotificationHelper)
}

// iosMain
actual fun platformModule(): Module = module { }
```

Only Android code can then use `NotificationHelper`. Common code can't reference it, since the class does not exist in `commonMain`.

## Choosing a pattern

| Situation | Pattern |
|-----------|---------|
| Same constructor on every platform | `expect`/`actual` class |
| Different constructor parameters per platform | Interface in common code, implementation in the platform module |
| Platform library built with a function (driver, engine) | Lambda in the platform module |
| Class that exists on one platform only | Platform module, empty on other platforms |
| Android `Context` needed by shared code | Platform wrapper, see [KMP Platform Integration](/docs/reference/koin-mp/kmp) |

## Limits

- **Manual wiring**: if a provider function receives a Koin `Scope` and calls `scope.get()` itself, that call is dynamic and not covered by [compile-time safety](/docs/reference/koin-compiler/compile-safety). Prefer constructor parameters.
- **Tests**: shared modules can be tested in `commonTest`. See [Testing](/docs/reference/koin-test/testing).

## Related

- [KMP Setup](/docs/reference/koin-core/kmp-setup): dependencies and the shared `initKoin` function.
- [KMP Platform Integration](/docs/reference/koin-mp/kmp): Android context in shared code, Swift interop, desktop and web.
- [Modules](/docs/reference/koin-core/modules): `includes()`, `@Module`, `@ComponentScan`, `@Configuration`.
- [Definitions](/docs/reference/koin-core/definitions): binding, provider functions, classes you don't own.
- [ViewModel](/docs/reference/koin-core/viewmodel): ViewModels declared in `commonMain`.

---

# KMP Platform Integration

Source: https://insert-koin.io/docs/reference/koin-mp/kmp

This page covers the platform details of a Kotlin Multiplatform app with Koin: using the Android `Context` from shared code, calling Koin from Swift, and the desktop and web targets. It assumes your project follows [KMP Setup](/docs/reference/koin-core/kmp-setup) and [KMP Sharing Patterns](/docs/reference/koin-core/kmp-shared-modules).

Complete projects: the [Compose Multiplatform sample](https://github.com/InsertKoinIO/koin-getting-started/tree/main/compose) (Compiler Plugin DSL) and the [annotations sample](https://github.com/InsertKoinIO/koin-getting-started/tree/main/compose-annotations).

## Android Context in shared code

Shared code can't use `android.content.Context`, but some shared classes need it on Android (to open files, read preferences). Wrap it in a platform type that common code can depend on:

**Compiler Plugin DSL**
```kotlin
// commonMain
interface ContextWrapper {
    fun getContextInfo(): String
}

class FileStore(private val ctx: ContextWrapper)

val storageModule = module {
    single<FileStore>()
}
```

```kotlin
// androidMain
class AndroidContextWrapper(val context: Context) : ContextWrapper {
    override fun getContextInfo() = "Android: ${context.packageName}"
}

actual fun platformModule(): Module = module {
    single<AndroidContextWrapper>() bind ContextWrapper::class
}
```

```kotlin
// iosMain
class IOSContextWrapper : ContextWrapper {
    override fun getContextInfo() = "iOS"
}

actual fun platformModule(): Module = module {
    single<IOSContextWrapper>() bind ContextWrapper::class
}
```

**Annotations**
```kotlin
// commonMain
interface ContextWrapper {
    fun getContextInfo(): String
}

@Singleton
class FileStore(private val ctx: ContextWrapper)
```

```kotlin
// androidMain
@Singleton
class AndroidContextWrapper(val context: Context) : ContextWrapper {
    override fun getContextInfo() = "Android: ${context.packageName}"
}
```

```kotlin
// iosMain
@Singleton
class IOSContextWrapper : ContextWrapper {
    override fun getContextInfo() = "iOS"
}
```

The platform classes are found by the `actual` platform module with `@ComponentScan` (see [KMP Sharing Patterns](/docs/reference/koin-core/kmp-shared-modules)).

**Constructor / Classic DSL**
```kotlin
// commonMain
interface ContextWrapper {
    fun getContextInfo(): String
}

class FileStore(private val ctx: ContextWrapper)

val storageModule = module {
    singleOf(::FileStore)
}
```

```kotlin
// androidMain
actual fun platformModule(): Module = module {
    singleOf(::AndroidContextWrapper) bind ContextWrapper::class
}

// iosMain
actual fun platformModule(): Module = module {
    singleOf(::IOSContextWrapper) bind ContextWrapper::class
}
```

`FileStore` is compiled once in `commonMain` and receives the platform wrapper. Only one Android definition touches `Context`, and it resolves once `androidContext()` is set at start. Put the Android-specific operations behind methods of `ContextWrapper` rather than checking the platform type in common code.

## iOS and Swift

### Retrieving dependencies from Swift

Swift can't call Koin's reified functions such as `get<T>()`. At the Swift boundary, write a small Kotlin helper in `iosMain` that implements `KoinComponent`, and use it from Swift. This is an interop entry point: your shared classes keep receiving their dependencies through their constructors.

```kotlin
// iosMain
class GreetingHelper : KoinComponent {
    private val greeting: Greeting by inject()
    fun greet(): String = greeting.greeting()
}
```

```swift
struct ContentView: View {
    let greet = GreetingHelper().greet()

    var body: some View {
        Text(greet)
    }
}
```

Koin must be started before the helper is used: see the iOS entry point in [KMP Setup](/docs/reference/koin-core/kmp-setup). `KoinComponent` is described in [KoinComponent](/docs/reference/koin-core/koin-component).

### Declaring a Swift instance in Koin

Sometimes a Swift class implements a Kotlin interface, and Kotlin code needs it from Koin. Register the instance at runtime with `Koin.declare()`. Swift passes the type as an Objective-C class or protocol, which this `iosMain` helper converts to a Kotlin `KClass`:

```kotlin
// iosMain
@OptIn(BetaInteropApi::class)
fun Koin.declareFromSwift(
    instance: Any,
    bindTo: ObjCObject,
    qualifier: Qualifier? = null,
    allowOverride: Boolean = true
) {
    val kClass: KClass<*> = when (bindTo) {
        is ObjCClass -> getOriginalKotlinClass(bindTo)
        is ObjCProtocol -> getOriginalKotlinClass(bindTo)
        else -> null
    } ?: error("Can't resolve Kotlin KClass from $bindTo")

    declare(
        instance = instance,
        qualifier = qualifier,
        secondaryTypes = listOf(kClass),
        allowOverride = allowOverride
    )
}
```

```swift
koin.declareFromSwift(
    instance: SwiftAnalytics(),
    bindTo: Analytics.self,
    qualifier: nil,
    allowOverride: true
)
```

`getOriginalKotlinClass()` comes from `kotlin.native` and maps a class (`.self` on a class) or a protocol (`.self` on a protocol) back to its Kotlin type. Declared instances are not checked at compile time: a Kotlin consumer fails at runtime if Swift has not declared the instance yet. The helper is based on a [proposal by @SarahDelCastillo](https://github.com/InsertKoinIO/koin/issues/1108#issuecomment-3645990426).

### Threading

Koin runs on the current Kotlin/Native memory model (the default since Kotlin 1.7.20). You can resolve dependencies and use scopes from any thread, with no freezing or `@SharedImmutable` annotation.

## Desktop (JVM)

Start Koin in `main()`, before the first window:

```kotlin
// jvmMain
fun main() = application {
    initKoin {
        printLogger()
        modules(desktopModule)
    }

    Window(onCloseRequest = ::exitApplication) {
        App()
    }
}

val desktopModule = module {
    single<DesktopFileManager>()
}
```

The `config` parameter of the shared `initKoin` adds desktop-only modules and the logger. Desktop is a JVM target, so JVM-only features such as `fileProperties()` are available (see [Starting Koin](/docs/reference/koin-core/starting-koin)).

## Web (JS and Wasm)

Start Koin in the `main()` of the `js` or `wasmJs` source set:

```kotlin
// jsMain or wasmJsMain
fun main() {
    initKoin {
        modules(webModule)
    }
    // start your UI
}

val webModule = module {
    single<BrowserStorage>()
}
```

With Compose Multiplatform for web, you can start Koin from the root Composable with `KoinApplication` instead (see [Koin for Compose](/docs/reference/koin-compose/compose)).

## Related

- [KMP Setup](/docs/reference/koin-core/kmp-setup): dependencies, `initKoin`, entry points.
- [KMP Sharing Patterns](/docs/reference/koin-core/kmp-shared-modules): platform modules and `expect`/`actual` definitions.
- [KoinComponent](/docs/reference/koin-core/koin-component): retrieve dependencies from classes Koin does not create.
- [Koin for Compose](/docs/reference/koin-compose/compose): Compose Multiplatform integration.
- [Testing](/docs/reference/koin-test/testing): test shared modules in `commonTest`.

---

# Koin for Ktor

Source: https://insert-koin.io/docs/reference/koin-ktor/ktor

This page shows how to add Koin to a Ktor server application: install the `Koin` plugin, inject dependencies in your routes, load modules from feature functions, and listen to Koin lifecycle events. You should know how to declare [definitions](/docs/reference/koin-core/definitions) and [modules](/docs/reference/koin-core/modules). For a step-by-step project, see the [Ktor tutorial](/docs/quickstart/ktor).

## Setup

```kotlin
// build.gradle.kts
dependencies {
    implementation(platform(libs.koin.bom))
    implementation(libs.koin.ktor)
    implementation(libs.koin.logger.slf4j) // optional, SLF4J logger
}
```

Catalog entries and versions are in [Gradle Setup](/docs/setup/gradle). The `koin-ktor` plugin targets Ktor 3.

## Installing the Koin plugin

Install `Koin` in your application module. Its configuration block is the same as `startKoin { }`:

**Compiler Plugin DSL**
```kotlin
import org.koin.ktor.plugin.Koin
import org.koin.logger.slf4jLogger

val appModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class
    single<UserService>()
}

fun Application.module() {
    install(Koin) {
        slf4jLogger()
        modules(appModule)
    }
}
```

**Annotations**
```kotlin
import org.koin.ktor.plugin.Koin
import org.koin.logger.slf4jLogger
import org.koin.plugin.module.dsl.withConfiguration

@Module
@ComponentScan("com.example")
@Configuration
class AppModule

@KoinApplication
object KoinUserApplication

fun Application.module() {
    install(Koin) {
        slf4jLogger()
        withConfiguration<KoinUserApplication>()
    }
}
```

`withConfiguration<T>()` loads the modules assembled by the `@KoinApplication` class.

**Constructor / Classic DSL**
```kotlin
import org.koin.ktor.plugin.Koin
import org.koin.logger.slf4jLogger

val appModule = module {
    singleOf(::UserRepositoryImpl) bind UserRepository::class
    singleOf(::UserService)
}

fun Application.module() {
    install(Koin) {
        slf4jLogger()
        modules(appModule)
    }
}
```

What the plugin does:

- **Global start**: it starts Koin in the global context, like `startKoin`. If a global Koin instance is already running (for example after a Ktor auto-reload), the plugin stops it first. To keep Koin out of the global context, use [`KoinIsolated`](/docs/reference/koin-ktor/ktor-isolated).
- **Eager instances**: definitions marked `createdAtStart` are created at install time.
- **Request scope**: it opens a Koin scope for each call. See [Request Scopes](/docs/reference/koin-ktor/ktor-scopes).
- **Shutdown**: when Ktor raises `ApplicationStopping`, the plugin closes the Koin instance.

Logging, properties and other options of the configuration block are described in [Starting Koin](/docs/reference/koin-core/starting-koin).

## Injecting dependencies

`inject()` (lazy) and `get()` (immediate) are extension functions from `org.koin.ktor.ext` on `Application`, `Route`, `Routing` and `ApplicationCall`:

```kotlin
import org.koin.ktor.ext.inject

fun Application.module() {
    install(Koin) { modules(appModule) }

    val userService by inject<UserService>()

    routing {
        get("/users") {
            call.respond(userService.getAllUsers())
        }
    }
}
```

In a route extension function:

```kotlin
fun Route.customerRoutes() {
    val customerService by inject<CustomerService>()

    get("/customers/{id}") {
        val id = call.parameters["id"] ?: return@get call.respond(HttpStatusCode.BadRequest)
        call.respond(customerService.getCustomer(id))
    }
}
```

Inside a handler, resolve from the call:

```kotlin
get("/users/{id}") {
    val userService = call.get<UserService>()
    call.respond(userService.getUser(call.parameters["id"]!!))
}
```

All four receivers resolve from the Koin instance stored in the `Application`: the global one with `Koin`, the isolated one with `KoinIsolated`. They accept a `qualifier` and `parameters`, like the core functions (see [Injection](/docs/reference/koin-core/injection)). `getProperty(key)` and `getProperty(key, defaultValue)` read Koin properties from the same receivers.

## Loading modules from feature functions

Once the plugin is installed, a feature function can add its own definitions:

```kotlin
import org.koin.ktor.plugin.koinModule
import org.koin.ktor.plugin.koinModules

fun Application.customerFeature() {
    koinModule {
        singleOf(::CustomerRepository)
        singleOf(::CustomerService)
    }

    routing { customerRoutes() }
}

fun Application.orderFeature() {
    koinModules(orderDataModule, orderServiceModule)

    routing { orderRoutes() }
}

fun Application.module() {
    install(Koin) {
        slf4jLogger()
        modules(coreModule)
    }
    customerFeature()
    orderFeature()
}
```

`koinModule { }` declares a module inline, `koinModules(...)` loads existing `Module` values. Both fail with "Koin plugin is not installed properly" if `install(Koin)` was not called first.

## Lifecycle events

The plugin raises three events on the application monitor:

| Event | Raised |
|-------|--------|
| `KoinApplicationStarted` | When the plugin is installed and Koin is started |
| `KoinApplicationStopPreparing` | On `ApplicationStopping`, before Koin is closed |
| `KoinApplicationStopped` | After Koin is closed |

```kotlin
fun Application.module() {
    monitor.subscribe(KoinApplicationStarted) { koinApp ->
        log.info("Koin started")
    }
    monitor.subscribe(KoinApplicationStopped) {
        log.info("Koin stopped")
    }

    install(Koin) {
        slf4jLogger()
        modules(appModule)
    }
}
```

`KoinApplicationStarted` is raised during `install(Koin)`. Subscribe before installing the plugin, or the handler never runs. Each handler receives the `KoinApplication`.

## Ktor's own DI

Ktor 3.4 has a built-in dependency injection plugin. Koin can share dependencies with it in both directions: see [Ktor DI Bridge](/docs/reference/koin-ktor/ktor-bridge).

## Related

- [Request Scopes](/docs/reference/koin-ktor/ktor-scopes): instances that live for one HTTP call.
- [Ktor DI Bridge](/docs/reference/koin-ktor/ktor-bridge): resolve between Koin and Ktor DI.
- [Isolated Context in Ktor](/docs/reference/koin-ktor/ktor-isolated): Koin without the global context.
- [Ktor Testing](/docs/reference/koin-ktor/ktor-testing): test routes with Koin.
- [Ktor tutorial](/docs/quickstart/ktor) and [Ktor tutorial with annotations](/docs/quickstart/ktor-annotations): build a Ktor app with Koin step by step.

---

# Request Scopes

Source: https://insert-koin.io/docs/reference/koin-ktor/ktor-scopes

This page covers the request scope of the Koin Ktor plugin: a Koin scope opened for each HTTP call and closed when the response is sent. Use it for objects that hold per-request state, such as a request logger or the current user. How scopes work in general is explained in [Scopes](/docs/reference/koin-core/scopes). You need the plugin installed as in [Koin for Ktor](/docs/reference/koin-ktor/ktor).

## Declaring request-scoped definitions

**Compiler Plugin DSL**
```kotlin
import org.koin.module.requestScope

val appModule = module {
    single<UserRepository>() // shared by all requests

    requestScope {
        scoped<RequestLogger>()
        scoped<UserSessionHandler>()
    }
}
```

**Annotations**
```kotlin
import org.koin.ktor.plugin.RequestScope

@Scope(RequestScope::class)
class RequestLogger(private val call: ApplicationCall)

@Scope(RequestScope::class)
class UserSessionHandler(private val call: ApplicationCall)
```

`requestScope { }` is a scope qualified by the `RequestScope` type, so `@Scope(RequestScope::class)` targets the same scope.

**Constructor / Classic DSL**
```kotlin
import org.koin.module.requestScope

val appModule = module {
    singleOf(::UserRepository) // shared by all requests

    requestScope {
        scopedOf(::RequestLogger)
        scopedOf(::UserSessionHandler)
    }
}
```

## Resolving in a handler

`call.scope` is the request scope of the current call:

```kotlin
routing {
    get("/users/{id}") {
        val logger = call.scope.get<RequestLogger>()
        val userService = call.get<UserService>()

        logger.log("Fetching user")
        call.respond(userService.getUser(call.parameters["id"]!!))
    }
}
```

Within one call, every `call.scope.get<RequestLogger>()` returns the same instance. The next call gets a new one. A request-scoped definition can depend on singletons, since the request scope falls back to the root scope.

`call.scope` throws "Koin Request Scope is not ready" if the call has no scope, for example when neither `Koin` nor `KoinIsolated` is installed.

## Injecting the ApplicationCall

The call is the source of its request scope, so request-scoped classes can take `ApplicationCall` as a constructor parameter without declaring it:

```kotlin
class RequestLogger(private val call: ApplicationCall) {
    fun log(message: String) {
        println("[${call.request.httpMethod.value} ${call.request.path()}] $message")
    }
}

class UserSessionHandler(private val call: ApplicationCall) {
    fun userId(): String? = call.request.headers["X-User-ID"]
}
```

The scope source is described in [Scopes](/docs/reference/koin-core/scopes). `ApplicationCall` is available in the request scope only: a `single` can't receive it.

## Lifecycle

| Step | When |
|------|------|
| Scope created | Ktor `CallSetup`, before routing |
| Scope id | `request_` followed by a unique counter |
| Scope closed | Ktor `ResponseSent`, after the response is sent |

Closing the scope drops all its instances. To run cleanup code, add `onClose` to the definition:

```kotlin
requestScope {
    scoped { RequestMetrics() } onClose { metrics ->
        metrics?.recordDuration()
    }
}
```

`onClose` receives the instance as a nullable value. There is no `onCreate` callback: run initialization in the constructor or the definition lambda. See [Definitions](/docs/reference/koin-core/definitions) for callbacks.

## Pitfalls

- **Request object in a singleton**: don't inject a request-scoped class into a `single`. The singleton is created once and would keep the instance of the first request. Resolve request-scoped objects from `call.scope` in the handler, or pass them as arguments.
- **Background work**: a coroutine launched from a handler that outlives the call must not use `call.scope` after the response is sent: the scope is closed by then.

## Related

- [Scopes](/docs/reference/koin-core/scopes): scope concepts, scope source, linking.
- [Koin for Ktor](/docs/reference/koin-ktor/ktor): install the plugin and inject in routes.
- [Definitions](/docs/reference/koin-core/definitions): `onClose` and other definition options.
- [Ktor Testing](/docs/reference/koin-ktor/ktor-testing): test routes that use request scopes.

---

# Ktor DI Bridge

Source: https://insert-koin.io/docs/reference/koin-ktor/ktor-bridge

Ktor 3.4 ships its own dependency injection plugin (`dependencies { provide<T> { } }` and `by dependencies`). This page shows how to connect it to Koin with the `bridge { }` option of the Koin plugin, in one or both directions. You need the Koin plugin installed as in [Koin for Ktor](/docs/reference/koin-ktor/ktor).

The bridge is available since Koin 4.2. Its functions are marked `@KoinExperimentalAPI`.

## Configuring the bridge

```kotlin
fun Application.module() {
    install(Koin) {
        slf4jLogger()
        bridge {
            ktorToKoin()
            koinToKtor()
        }
        modules(appModule)
    }

    dependencies {
        provide<KtorSpecificService> { KtorSpecificServiceImpl() }
    }
}
```

| Option | Effect |
|--------|--------|
| `ktorToKoin()` | Ktor's `by dependencies` can resolve Koin definitions |
| `koinToKtor()` | Koin's `get()`, `inject()` and constructor injection can resolve Ktor DI dependencies |

Enable only the direction you use.

## Ktor resolving from Koin

With `ktorToKoin()`, the plugin installs Ktor's `DI` plugin with a dependency map backed by Koin:

```kotlin
fun Application.module() {
    install(Koin) {
        bridge { ktorToKoin() }
        modules(module {
            single<HelloService> { HelloServiceImpl() }
        })
    }

    routing {
        get("/hello") {
            val helloService: HelloService by dependencies // declared in Koin
            call.respondText(helloService.sayHello())
        }
    }
}
```

A Ktor dependency key with a name maps to a Koin `named()` qualifier with the same value.

## Koin resolving from Ktor DI

With `koinToKtor()`, Koin adds a resolution extension: when a type has no Koin definition, Koin asks Ktor DI for it.

```kotlin
fun Application.module() {
    install(Koin) {
        bridge { koinToKtor() }
        modules(appModule)
    }

    dependencies {
        provide<DatabaseConnection> { DatabaseConnectionImpl() }
    }

    routing {
        get("/data") {
            val database: DatabaseConnection by inject() // declared in Ktor DI
            call.respondText(database.query())
        }
    }
}
```

Koin definitions can also take Ktor DI types as constructor parameters. A Koin qualifier is passed to Ktor as the dependency name. If Ktor DI has no such dependency either, Koin logs a warning and the resolution fails as for any missing definition.

## Splitting infrastructure and application code

A common split keeps framework-level objects in Ktor DI and application classes in Koin, with `koinToKtor()` only:

```kotlin
fun Application.module() {
    // Ktor DI: infrastructure
    val database = Database(environment.config)
    dependencies {
        provide<Database> { database }
        provide<ApplicationConfig> { environment.config }
    }

    // Koin: application classes
    install(Koin) {
        slf4jLogger()
        bridge { koinToKtor() }
        modules(appModule)
    }
}

val appModule = module {
    singleOf(::CustomerRepository) // receives Database from Ktor DI
    singleOf(::CustomerService)
}
```

## Limits

- **Compile-time checks**: the Koin Compiler Plugin does not see Ktor DI declarations. If compile-time safety reports a Ktor DI type as missing, mark it `@Provided`, as described in [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety).
- **KoinIsolated**: in Koin 4.2, the `KoinIsolated` plugin accepts the `bridge { }` block but does not apply it. Use `install(Koin)` when you need the bridge.
- **Experimental**: the bridge API may change in a future release.

## Related

- [Koin for Ktor](/docs/reference/koin-ktor/ktor): install the plugin and inject in routes.
- [Isolated Context in Ktor](/docs/reference/koin-ktor/ktor-isolated): Koin outside the global context.
- [Request Scopes](/docs/reference/koin-ktor/ktor-scopes): per-call instances.
- [Ktor dependency injection](https://ktor.io/docs/server-dependency-injection.html): Ktor's own DI plugin.

---

# Isolated Context in Ktor

Source: https://insert-koin.io/docs/reference/koin-ktor/ktor-isolated

This page covers the `KoinIsolated` plugin, which starts Koin for one Ktor application without registering it in the global context. Each application then has its own container. What an isolated context is, and when to use one, is explained in [Context Isolation](/docs/reference/koin-core/context-isolation). The regular `Koin` plugin is described in [Koin for Ktor](/docs/reference/koin-ktor/ktor).

## Installing KoinIsolated

Install `KoinIsolated` instead of `Koin`. The configuration block is the same:

**Compiler Plugin DSL**
```kotlin
import org.koin.ktor.plugin.KoinIsolated

fun Application.module() {
    install(KoinIsolated) {
        slf4jLogger()
        modules(appModule)
    }
}
```

**Annotations**
```kotlin
import org.koin.ktor.plugin.KoinIsolated
import org.koin.plugin.module.dsl.withConfiguration

fun Application.module() {
    install(KoinIsolated) {
        slf4jLogger()
        withConfiguration<KoinUserApplication>()
    }
}
```

**Constructor / Classic DSL**
```kotlin
import org.koin.ktor.plugin.KoinIsolated

fun Application.module() {
    install(KoinIsolated) {
        slf4jLogger()
        modules(appModule)
    }
}
```

## What changes compared to Koin

| | `install(Koin)` | `install(KoinIsolated)` |
|---|---|---|
| Registered in the global context | Yes | No |
| `inject()` / `get()` on `Application`, `Route`, `Routing`, `ApplicationCall` | Yes | Yes, from the application's instance |
| Request scope and `call.scope` | Yes | Yes |
| Lifecycle events, close on `ApplicationStopping` | Yes | Yes |
| `bridge { }` to Ktor DI | Yes | Not applied in Koin 4.2 |
| `KoinComponent` classes, `KoinPlatform.getKoin()` | See this instance | Don't see this instance |

The Ktor extensions read the Koin instance stored in the application attributes, so injection in routes works the same:

```kotlin
fun Application.module() {
    install(KoinIsolated) {
        modules(appModule)
    }

    val userService by inject<UserService>()
    val koin = getKoin() // this application's Koin instance

    routing {
        get("/users/{id}") {
            val logger = call.scope.get<RequestLogger>()
            call.respond(userService.getUser(call.parameters["id"]!!))
        }
    }
}
```

:::warning
Code outside Ktor's receivers can't reach the isolated instance. A class implementing `KoinComponent`, or a call to `KoinPlatform.getKoin()`, uses the global context and fails with "KoinApplication has not been started". Give your classes their dependencies through constructor parameters, declared in the isolated modules. For an interop entry point that must retrieve dependencies itself, override `getKoin()` as shown in [Context Isolation](/docs/reference/koin-core/context-isolation).
:::

## Several servers in one JVM

Each embedded server gets its own container:

```kotlin
fun main() {
    val userServer = embeddedServer(Netty, port = 8080) {
        install(KoinIsolated) { modules(userServiceModule) }
        userRouting()
    }

    val orderServer = embeddedServer(Netty, port = 8081) {
        install(KoinIsolated) { modules(orderServiceModule) }
        orderRouting()
    }

    userServer.start(wait = false)
    orderServer.start(wait = true)
}
```

With `install(Koin)`, the second server would stop the global Koin of the first one, since the plugin stops a running global instance before it starts.

## Tests

Each `testApplication` that installs `KoinIsolated` has its own container, so tests don't share state through the global context and can run in parallel. Test setup is covered in [Ktor Testing](/docs/reference/koin-ktor/ktor-testing).

## When to keep the global context

Stay with `install(Koin)` when one Ktor application runs in the process and other entry points of that process (a scheduled job started from `main()`, for example) must use the same container, or when you need the Ktor DI bridge.

## Related

- [Context Isolation](/docs/reference/koin-core/context-isolation): the isolated context concept and a custom `KoinComponent`.
- [Koin for Ktor](/docs/reference/koin-ktor/ktor): the `Koin` plugin and injection in routes.
- [Ktor Testing](/docs/reference/koin-ktor/ktor-testing): test Ktor applications with Koin.
- [Ktor DI Bridge](/docs/reference/koin-ktor/ktor-bridge): share dependencies with Ktor DI.

---

# Unit Testing

Source: https://insert-koin.io/docs/reference/koin-test/testing

This guide shows how to write JVM unit tests with Koin: start and stop a container per test, retrieve instances, override definitions and replace dependencies with mocks. It is the reference for every testing technique; the platform pages ([Android instrumented](/docs/reference/koin-android/instrumented-testing), [Compose](/docs/reference/koin-compose/compose-testing), [Ktor](/docs/reference/koin-ktor/ktor-testing)) only cover what is specific to them. You should know how to [start Koin](/docs/reference/koin-core/starting-koin) and declare [definitions](/docs/reference/koin-core/definitions).

## Dependencies

Add `koin-test` and the artifact for your JUnit version to your test dependencies:

```kotlin
dependencies {
    testImplementation("io.insert-koin:koin-test")
    // pick one
    testImplementation("io.insert-koin:koin-test-junit4")
    testImplementation("io.insert-koin:koin-test-junit5")
}
```

Versions come from the Koin BOM, see [Gradle Setup](/docs/setup/gradle). `koin-test` has no dependency on a mocking library: you plug in Mockito, MockK or any other one (see [Mocking with declareMock](#mocking-with-declaremock)).

## KoinTest

Implement `KoinTest` in your test class. It makes the class a [KoinComponent](/docs/reference/koin-core/koin-component), so `get()` and `by inject()` work directly in the test:

```kotlin
import org.koin.test.KoinTest
import org.koin.test.get
import org.koin.test.inject

class UserServiceTest : KoinTest {

    // resolved on first access
    private val userService: UserService by inject()

    @Test
    fun `finds a known user`() {
        startKoin { modules(appModule) }

        val repository = get<UserRepository>()

        assertNotNull(userService.findUser("alice"))
        assertSame(repository, userService.repository)

        stopKoin()
    }
}
```

`KoinTest` works with the global Koin context, the one created by `startKoin`. It does not apply to Android instrumented tests, where the `Application` class starts Koin: see [Android Instrumented Testing](/docs/reference/koin-android/instrumented-testing).

## Start and stop Koin for each test

Each test should start its own container and stop it at the end. A container left running makes the next `startKoin` fail with `KoinApplicationAlreadyStartedException`, and leaks instances between tests.

Load the same configuration as your app:

**Compiler Plugin DSL**
```kotlin
class UserServiceTest : KoinTest {

    @Before
    fun before() {
        startKoin { modules(appModule) }
    }

    @After
    fun after() {
        stopKoin()
    }
}
```

**Annotations**
Start the `@KoinApplication` class of your app with the typed API:

```kotlin
import org.koin.plugin.module.dsl.startKoin

class UserServiceTest : KoinTest {

    @Before
    fun before() {
        startKoin<MyApp>()
    }

    @After
    fun after() {
        stopKoin()
    }
}
```

To load only some modules, use `module<DataModule>()` or `modules(DataModule::class, CacheModule::class)` inside a plain `startKoin { }`.

**Constructor / Classic DSL**
```kotlin
class UserServiceTest : KoinTest {

    @Before
    fun before() {
        startKoin { modules(appModule) }
    }

    @After
    fun after() {
        stopKoin()
    }
}
```

To stop Koin without writing `@After`, extend `AutoCloseKoinTest` or implement `ClosingKoinTest`. Both call `stopKoin()` after each test. The JUnit 5 versions live in `org.koin.test.junit5`.

The JUnit rule and extension below do the start and stop for you, and are the shorter option.

## JUnit 4: KoinTestRule

`KoinTestRule` (from `koin-test-junit4`) starts Koin before each test and stops it after:

```kotlin
import org.koin.test.KoinTestRule

class UserServiceTest : KoinTest {

    @get:Rule
    val koinTestRule = KoinTestRule.create {
        printLogger()
        modules(appModule)
    }

    private val userService: UserService by inject()

    @Test
    fun `finds a known user`() {
        assertNotNull(userService.findUser("alice"))
    }
}
```

The lambda is a regular `KoinApplication` declaration: everything you write in `startKoin { }` works here. With annotations, load your app with `withConfiguration<MyApp>()`:

```kotlin
import org.koin.plugin.module.dsl.withConfiguration

@get:Rule
val koinTestRule = KoinTestRule.create {
    withConfiguration<MyApp>()
}
```

If a Koin container is already running when the test starts, the rule closes it first. The started instance is available as `koinTestRule.koin`.

## JUnit 5: KoinTestExtension

`KoinTestExtension` (from `koin-test-junit5`) does the same for JUnit 5. Register it with `@JvmField` and `@RegisterExtension`:

```kotlin
import org.koin.test.junit5.KoinTestExtension

class UserServiceTest : KoinTest {

    @JvmField
    @RegisterExtension
    val koinTestExtension = KoinTestExtension.create {
        modules(appModule)
    }

    private val userService: UserService by inject()

    @Test
    fun `finds a known user`() {
        assertNotNull(userService.findUser("alice"))
    }
}
```

The extension can also pass the `Koin` instance as a test function parameter:

```kotlin
@Test
fun `resolves from the test container`(koin: Koin) {
    assertNotNull(koin.get<UserRepository>())
}
```

## Override definitions for a test

To replace a production definition, load a test module after the production modules. The module loaded last wins:

```kotlin
val testModule = module {
    single<ApiService> { FakeApiService() }
}

@get:Rule
val koinTestRule = KoinTestRule.create {
    modules(appModule, testModule)
}
```

A lambda definition like `single<ApiService> { FakeApiService() }` works in every style, so you can write test modules this way even if your app uses the Compiler Plugin DSL or annotations.

If your app starts Koin with `allowOverride(false)`, mark each test definition with `.override()`. Override rules are explained in [Definitions](/docs/reference/koin-core/definitions#overriding-a-definition).

## Mocking with declareMock

`declareMock<T>()` creates a mock of `T`, registers it in the running container in place of the existing definition, and returns it. Every definition that depends on `T` then receives the mock.

Koin does not create mocks itself. Register a mock provider first:

```kotlin
// JUnit 4, Mockito
@get:Rule
val mockProvider = MockProviderRule.create { clazz ->
    Mockito.mock(clazz.java)
}

// JUnit 4, MockK
@get:Rule
val mockProvider = MockProviderRule.create { clazz ->
    mockkClass(clazz)
}

// JUnit 5
@JvmField
@RegisterExtension
val mockProvider = MockProviderExtension.create { clazz ->
    mockkClass(clazz)
}
```

Then declare the mock in the test, with an optional stubbing block:

```kotlin
import org.koin.test.mock.declareMock

class UserServiceTest : KoinTest {

    @get:Rule
    val koinTestRule = KoinTestRule.create {
        modules(appModule)
    }

    @get:Rule
    val mockProvider = MockProviderRule.create { clazz -> mockkClass(clazz) }

    private val userService: UserService by inject()

    @Test
    fun `returns the user from the repository`() {
        val repository = declareMock<UserRepository> {
            every { findUser("alice") } returns User("alice")
        }

        assertEquals("alice", userService.findUser("alice")?.name)
        verify { repository.findUser("alice") }
    }
}
```

`declareMock` takes the same options as a definition:

- `qualifier`: replace a [qualified](/docs/reference/koin-core/qualifiers) definition, for example `declareMock<Database>(named("local"))`.
- `secondaryTypes`: also bind the mock to other types, for example `declareMock<UserRepositoryImpl>(secondaryTypes = listOf(UserRepository::class))`.

The mock is held as a single instance in the root scope. To mock a definition inside a scope, call `declareMock` on that scope: `scope.declareMock<CartState>()`.

:::warning
Declare the mock before the first resolution of the classes that use it. A `single` that was already created keeps the dependency it received.
:::

## Declare an instance with declare

When you need a real or hand-written instance instead of a mock, `declare` registers it in the running container:

```kotlin
import org.koin.test.mock.declare

@Test
fun `uses a fixed clock`() {
    declare<Clock> { FixedClock(at = "2026-01-01T00:00:00Z") }

    assertEquals(2026, get<ReportService>().currentYear())
}
```

`declare` overrides any existing definition for the type, accepts a `qualifier`, and returns the declared instance. It uses the global context, so call it after Koin has started.

## Test scoped definitions

Create the scope yourself, resolve from it, then close it:

```kotlin
@Test
fun `cart state lives in its scope`() {
    val scope = getKoin().createScope<CheckoutSession>("checkout-1")

    val state = scope.get<CartState>()
    assertSame(state, scope.get<CartState>())

    scope.close()
}
```

For the scope APIs, see [Scopes](/docs/reference/koin-core/scopes). On Android, scopes bound to an Activity or Fragment are tested with the component itself: see [Android Instrumented Testing](/docs/reference/koin-android/instrumented-testing#scopes).

## Check your configuration

Unit tests exercise behavior. To check that every dependency of every definition is declared, use the [Koin Compiler Plugin](/docs/reference/koin-compiler/compile-safety) at build time, or the `verify()` test API: see [Verifying your Configuration](/docs/reference/koin-test/verify).

## Limits

- Global context: `startKoin`, `KoinTestRule` and `KoinTestExtension` all use the single global context. Tests that start Koin can't run in parallel in the same JVM. For parallel tests, use an [isolated context](/docs/reference/koin-core/context-isolation). `KoinTest`'s `get()` and `inject()` read the global context unless you override `getKoin()`.
- Mock provider: `declareMock` fails if no `MockProviderRule` or `MockProviderExtension` is registered.
- Overrides stay for the whole test: a definition replaced with a test module, `declareMock` or `declare` is only reset when Koin stops.

## Related

- [Verifying your Configuration](/docs/reference/koin-test/verify): `verify()` and its relationship with compile-time safety.
- [Android Instrumented Testing](/docs/reference/koin-android/instrumented-testing): tests where the `Application` starts Koin.
- [Testing Composables](/docs/reference/koin-compose/compose-testing): Compose UI tests and previews.
- [Ktor Testing](/docs/reference/koin-ktor/ktor-testing): `testApplication` with Koin.
- [Context Isolation](/docs/reference/koin-core/context-isolation): a private Koin container for libraries and parallel tests.
- [JUnit Test Quickstart](/docs/quickstart/junit-test): a full sample project.

---

# Verifying your Configuration

Source: https://insert-koin.io/docs/reference/koin-test/verify

This page covers `verify()`, the test API that checks your Koin configuration without running it, and the deprecated `checkModules()`. It also explains how both relate to the compile-time checks of the Koin Compiler Plugin, so you know whether you still need them. You should know how to write a [unit test with Koin](/docs/reference/koin-test/testing).

## Do you still need verify()?

The [Koin Compiler Plugin](/docs/reference/koin-compiler/compile-safety) checks the full dependency graph at build time: missing definitions, qualifier mismatches, scope errors and `get()` / `inject()` call sites. When it covers your project, a `verify()` test adds nothing and you can delete it.

You still need `verify()` when:

- No Compiler Plugin: your project uses the Constructor or Classic DSL without the plugin. (The deprecated KSP processor for annotations has its own `KOIN_CONFIG_CHECK` option.)
- Graph not known at build time: the plugin can't resolve module lists built with `if` / `when` or varargs. It reports `KOIN-W003` and skips the check for that entry point.
- Library modules: a library or feature module without its own `startKoin` / `@KoinApplication` gets no missing-dependency check until an app assembles it. A `verify()` test in the library checks it on its own.
- Lazy modules: you load part of the graph with [lazy modules](/docs/reference/koin-core/lazy-modules) and want one test over the full configuration (see [Modules and lazy modules together](#modules-and-lazy-modules-together)).

## verify()

`verify()` is an extension on `Module`, available on the JVM in `koin-test`. It reads the constructor of each definition's class and checks that every parameter type has a definition in the module or in the modules it includes. It runs no definition and needs no mock.

```kotlin
val appModule = module {
    includes(dataModule, networkModule)
    viewModel<UserViewModel>()
}
```

```kotlin
import org.koin.test.verify.verify

class AppModuleCheck {

    @Test
    fun checkKoinModule() {
        appModule.verify()
    }
}
```

On a missing dependency, `verify()` throws `MissingKoinDefinitionException` and prints a suggested fix. On a dependency cycle between two constructors, it throws `CircularInjectionException`.

To check several modules that are not linked with `includes()`, use `listOf(dataModule, uiModule).verifyAll()`.

### What verify() accepts

A constructor parameter passes the check when it is:

- Declared: a definition for its type exists in the module tree.
- Optional: the parameter has a default value. `verify()` prints a warning if no definition exists.
- Wrapped: a `Lazy<T>` or `List<T>` whose `T` is declared.
- Whitelisted: its type is in `extraTypes`, or is a basic type (`String`, `Int`, `Long`, `Double`).
- Injected or provided: the parameter is annotated with `@InjectedParam` or `@Provided`, or declared with `injections`.

`verify()` reads constructors only. It does not check qualifiers, properties or `get()` calls written inside a definition lambda.

### Types provided at runtime

Some types are never declared in a module: framework objects, or values created by the platform. Add them to `extraTypes`:

```kotlin
appModule.verify(
    extraTypes = listOf(HttpClientEngine::class, Clock::class)
)
```

On Android, use `androidVerify()` from `koin-android-test`. It adds `Context`, `Activity`, `Fragment`, `Application`, `SavedStateHandle` and `WorkerParameters` for you:

```kotlin
import org.koin.android.test.verify.androidVerify

@Test
fun checkKoinModule() {
    appModule.androidVerify()
}
```

### Injected parameters

A parameter passed with `parametersOf()` has no definition, so `verify()` reports it as missing. Declare it with `injections`:

```kotlin
class UserPresenter(val userId: String, val repository: UserRepository)

val presenterModule = module {
    factory { (userId: String) -> UserPresenter(userId, get()) }
}

@Test
fun checkKoinModule() {
    presenterModule.verify(
        injections = injectedParameters(
            definition<UserPresenter>(String::class)
        )
    )
}
```

Or annotate the constructor parameter. `@InjectedParam` marks a value passed with `parametersOf()`, `@Provided` marks a type supplied outside Koin's modules:

```kotlin
class UserPresenter(@InjectedParam val userId: String, val repository: UserRepository)

class SyncWorker(@Provided val params: WorkerParameters, val repository: UserRepository)
```

Both annotations come from `koin-core-annotations` and are the same ones the Compiler Plugin reads (see [Injected Parameters](/docs/reference/koin-core/injection-parameters)).

### Modules and lazy modules together

`koin-test-coroutines` adds `verify()` on a `ModuleConfiguration`, which checks regular and [lazy modules](/docs/reference/koin-core/lazy-modules) as one graph:

```kotlin
val configuration = moduleConfiguration {
    modules(coreModule)
    lazyModules(featureModule)
}

@Test
fun checkConfiguration() {
    configuration.verify()
}
```

`moduleConfiguration` and this `verify()` are experimental (`@KoinExperimentalAPI`).

## checkModules() (deprecated)

:::warning
`checkModules()`, `checkKoinModules()` and their DSL are deprecated. Migrate to `verify()`, or to the Compiler Plugin.
:::

Unlike `verify()`, `checkModules()` starts the modules and creates every definition, so it needs values for everything resolved at runtime. You may find it in older projects:

```kotlin
@Test
fun checkAllModules() {
    koinApplication {
        modules(appModule)
        checkModules {
            withInstance<Context>()
            withParameter<UserPresenter> { "user-1" }
            withProperty("api_url", "http://localhost")
        }
    }
}

// or
@Test
fun checkAllModules() {
    checkKoinModules(listOf(appModule))
}
```

The check DSL:

- `withInstance(value)`: add `value` to the graph. `withInstance<T>()` adds a mock of `T` and needs a `MockProviderRule` (see [Mocking with declareMock](/docs/reference/koin-test/testing#mocking-with-declaremock)).
- `withParameter<T> { value }`: the injected parameter used to create `T`. `withParameters<T> { parametersOf(a, b) }` for several.
- `withProperty(key, value)`: add a Koin property.
- `withScopeLink(scope, targetScope)`: [link](/docs/reference/koin-core/scopes) two scopes for the check.

To migrate to `verify()`: remove `withInstance` for framework types (use `extraTypes` or `androidVerify()`), and replace `withParameter` with `injections` or `@InjectedParam`.

## Related

- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): what the Compiler Plugin checks at build time.
- [Unit Testing](/docs/reference/koin-test/testing): start Koin in tests, override and mock definitions.
- [Injected Parameters](/docs/reference/koin-core/injection-parameters): `parametersOf` and `@InjectedParam`.
- [Lazy Modules](/docs/reference/koin-core/lazy-modules): load part of the graph in the background.
- [Troubleshooting](/docs/reference/koin-core/troubleshooting): runtime errors such as `NoDefinitionFoundException`.

---

# Android Instrumented Testing

Source: https://insert-koin.io/docs/reference/koin-android/instrumented-testing

Instrumented tests run on a device or emulator, inside your real `Application`. Koin is already started by `Application.onCreate()` when the test begins, so the question is how to replace production definitions with test ones. This guide covers the setups for that, then Activity, Fragment and scope tests. The generic techniques (`KoinTest`, `KoinTestRule`, `declareMock`) are explained in [Unit Testing](/docs/reference/koin-test/testing).

## Dependencies

```kotlin
dependencies {
    androidTestImplementation("io.insert-koin:koin-test-junit4")
}
```

`koin-test-junit4` brings `koin-test`. Versions come from the Koin BOM, see [Gradle Setup](/docs/setup/gradle).

## Choose a setup

| Setup | Koin is started by | Use it when |
|-------|--------------------|-------------|
| [Test Application](#use-a-test-application) | A test `Application` class | All tests share the same test configuration |
| [Test rule](#restart-koin-with-a-test-rule) | `KoinTestRule`, before each test | Each test class needs its own modules |
| [Load overrides](#load-overrides-into-the-running-container) | Your production `Application` | You only replace a few definitions |

## Use a test Application

Create an `Application` in `androidTest` that starts Koin with your production modules plus a test module. The test module is loaded last, so its definitions replace the production ones:

**Compiler Plugin DSL**
```kotlin
// in src/androidTest
class TestApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidContext(this@TestApplication)
            modules(appModule, instrumentedTestModule)
        }
    }
}
```

**Annotations**
```kotlin
// in src/androidTest
class TestApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin<MyApp> {
            androidContext(this@TestApplication)
            modules(instrumentedTestModule)
        }
    }
}
```

`startKoin<MyApp>` loads the modules of your `@KoinApplication` class first, then the modules declared in the lambda.

**Constructor / Classic DSL**
```kotlin
// in src/androidTest
class TestApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidContext(this@TestApplication)
            modules(appModule, instrumentedTestModule)
        }
    }
}
```

```kotlin
val instrumentedTestModule = module {
    single<ApiService> { FakeApiService() }
}
```

A lambda definition like `single<ApiService> { FakeApiService() }` works in every style.

To run tests with this `Application`, create a custom [AndroidJUnitRunner](https://developer.android.com/training/testing/instrumented-tests/androidx-test-libraries/runner):

```kotlin
class InstrumentationTestRunner : AndroidJUnitRunner() {
    override fun newApplication(
        classLoader: ClassLoader?,
        className: String?,
        context: Context?
    ): Application {
        return super.newApplication(classLoader, TestApplication::class.java.name, context)
    }
}
```

Register it in `build.gradle.kts`:

```kotlin
android {
    defaultConfig {
        testInstrumentationRunner = "com.example.app.InstrumentationTestRunner"
    }
}
```

## Restart Koin with a test rule

`KoinTestRule` closes the running Koin container, starts a new one before each test and stops it after. Pass the Android context yourself, since your `Application` is not the one starting this container:

```kotlin
import androidx.test.core.app.ApplicationProvider
import org.koin.android.ext.koin.androidContext
import org.koin.test.KoinTestRule

@RunWith(AndroidJUnit4::class)
class LoginActivityTest : KoinTest {

    @get:Rule
    val koinTestRule = KoinTestRule.create {
        androidContext(ApplicationProvider.getApplicationContext())
        modules(appModule, loginTestModule)
    }
}
```

With annotations, use `withConfiguration<MyApp>()` in place of `modules(appModule)`, as in [Unit Testing](/docs/reference/koin-test/testing#junit-4-kointestrule).

The production `Application` still runs `startKoin` once when the process starts. The rule replaces that container, so anything the `Application` resolved in `onCreate()` holds instances from the closed one. If your `Application` resolves dependencies at startup, prefer a [test Application](#use-a-test-application) that does not.

## Load overrides into the running container

To keep the production `Application` and change only a few definitions, load a test module into the running container before the screen under test starts:

```kotlin
@RunWith(AndroidJUnit4::class)
class ProfileFragmentTest : KoinTest {

    private val profileTestModule = module {
        single<UserRepository> { FakeUserRepository() }
    }

    @Before
    fun before() {
        loadKoinModules(profileTestModule)
    }
}
```

This is the lightest setup, and the one with the most pitfalls:

- No reset: the override stays for every following test in the process.
- Unloading removes, it does not restore: `unloadKoinModules(profileTestModule)` deletes the `UserRepository` definition. The production one does not come back.
- Created instances are kept: a `single` that already received the production `UserRepository` keeps it.

If you need a clean graph per test, use the [test rule](#restart-koin-with-a-test-rule) instead.

## Mocks and fakes

`declareMock` works in instrumented tests as in unit tests: implement `KoinTest` and register a `MockProviderRule` (see [Mocking with declareMock](/docs/reference/koin-test/testing#mocking-with-declaremock)). With MockK, use the `io.mockk:mockk-android` artifact on the device.

Fakes are often simpler on a device: they need no mocking library and behave like the real class. Declare them in the test module. For Room, use an in-memory database so each test starts empty:

```kotlin
val testDatabaseModule = module {
    single {
        Room.inMemoryDatabaseBuilder(androidContext(), AppDatabase::class.java).build()
    }
    single { get<AppDatabase>().userDao() }
}
```

## Activity and Fragment tests

Activities and Fragments resolve their dependencies with `by inject()` and `by viewModel()` (see [Entry Points](/docs/reference/koin-android/entry-points)). In a test, they receive whatever the test container holds, so launch them after Koin is configured:

```kotlin
@RunWith(AndroidJUnit4::class)
class LoginActivityTest {

    @get:Rule
    val koinTestRule = KoinTestRule.create {
        androidContext(ApplicationProvider.getApplicationContext())
        modules(appModule, module {
            single<AuthService> { FakeAuthService(acceptedEmail = "user@example.com") }
        })
    }

    @Test
    fun successfulLoginShowsWelcomeMessage() {
        ActivityScenario.launch(LoginActivity::class.java).use {
            onView(withId(R.id.email)).perform(typeText("user@example.com"))
            onView(withId(R.id.loginButton)).perform(click())

            onView(withId(R.id.successMessage)).check(matches(isDisplayed()))
        }
    }
}
```

The same works for a Fragment with `launchFragmentInContainer<ProfileFragment>()` from `androidx.fragment:fragment-testing`. The `LoginViewModel` that `LoginActivity` gets with `by viewModel()` is created by Koin with the `FakeAuthService`.

To read a ViewModel or a dependency from the running component, use `scenario.onActivity { activity -> ... }` and access it there. Outside of that block, the Activity may not exist yet.

## Scopes

An [Android scope](/docs/reference/koin-android/scope) exists only while its Activity or Fragment is alive. Test it through the component:

```kotlin
val checkoutTestModule = module {
    activityScope {
        scoped { CheckoutState() }
    }
}

@Test
fun fragmentSharesTheActivityScope() {
    ActivityScenario.launch(CheckoutActivity::class.java).use { scenario ->
        scenario.onActivity { activity ->
            val activityState = activity.scope.get<CheckoutState>()

            activity.supportFragmentManager.commitNow {
                replace(R.id.container, PaymentFragment())
            }
            val fragment = activity.supportFragmentManager
                .findFragmentById(R.id.container) as PaymentFragment

            assertSame(activityState, fragment.scope.get<CheckoutState>())
        }
    }
}
```

`activity.scope` and `fragment.scope` are available when the components implement `AndroidScopeComponent` (for example `ScopeActivity` and `ScopeFragment`). Calling `scope.get()` before the Activity is created, or after it is destroyed, fails: the scope does not exist yet, or is closed.

For scopes that are not tied to an Android component, a JVM unit test is enough: see [Unit Testing](/docs/reference/koin-test/testing#test-scoped-definitions).

## Multi-module apps

In a [multi-module app](/docs/reference/koin-android/multi-module), load the feature modules under test with the core modules they need, then your test overrides last:

```kotlin
@get:Rule
val koinTestRule = KoinTestRule.create {
    androidContext(ApplicationProvider.getApplicationContext())
    modules(
        networkModule,
        databaseModule,
        loginModule,
        homeModule,
        module { single<ApiService> { FakeApiService() } }
    )
}
```

A shared `androidTest` source set or a `:core:testing` Gradle module is a good place for fakes and test modules used by several features.

If you load only part of the app, a definition may miss a dependency that the full app provides. The [Compiler Plugin](/docs/reference/koin-compiler/compile-safety) checks the production graph at build time, not your test modules. To check a test configuration, use [verify()](/docs/reference/koin-test/verify) in a JVM test.

## Espresso and rule order

`ActivityScenarioRule` launches the Activity before the test method runs. If it runs before `KoinTestRule`, the Activity resolves its dependencies from the wrong container. Set the order explicitly:

```kotlin
@RunWith(AndroidJUnit4::class)
@LargeTest
class CheckoutFlowTest {

    @get:Rule(order = 0)
    val koinTestRule = KoinTestRule.create {
        androidContext(ApplicationProvider.getApplicationContext())
        modules(appModule, module {
            single<CartRepository> { FakeCartRepository() }
            single<PaymentService> { FakePaymentService() }
        })
    }

    @get:Rule(order = 1)
    val activityRule = ActivityScenarioRule(MainActivity::class.java)

    @Test
    fun completeCheckout() {
        onView(withId(R.id.cartButton)).perform(click())
        onView(withId(R.id.checkoutButton)).perform(click())
        onView(withId(R.id.completeOrderButton)).perform(click())

        onView(withId(R.id.confirmationMessage)).check(matches(isDisplayed()))
    }
}
```

`@get:Rule(order = ...)` needs JUnit 4.13 or later. With older versions, use `RuleChain.outerRule(koinTestRule).around(activityRule)`.

## Compose UI tests

For Compose screens, see [Testing Composables](/docs/reference/koin-compose/compose-testing).

## Isolation between tests

Tests that pass alone but fail together usually share state through Koin:

- Restart per test: `KoinTestRule` gives each test a new container, with new `single` instances.
- Reset fakes: with a [test Application](#use-a-test-application), the container lives for the whole run. A fake declared as `single` keeps its data between tests, so give it a `reset()` method and call it in `@Before`.
- Don't stack overrides: modules loaded with `loadKoinModules` stay loaded (see [Load overrides into the running container](#load-overrides-into-the-running-container)).

```kotlin
@RunWith(AndroidJUnit4::class)
class UserListTest : KoinTest {

    private val fakeRepository: FakeUserRepository by inject()

    @Before
    fun before() {
        fakeRepository.reset()
    }
}
```

`by inject<FakeUserRepository>()` only works if the test module binds the fake to its own type too: `single { FakeUserRepository() } bind UserRepository::class`.

## Troubleshooting

### KoinApplicationAlreadyStartedException

A second `startKoin` call ran while a container was running. In instrumented tests, your `Application` has already started Koin. Use `KoinTestRule`, which closes the running container first, or a [test Application](#use-a-test-application). Do not call `startKoin` in `@Before`.

### The test definition is not used

- Load order: the test module must be loaded after the production module that declares the same type.
- Overrides disabled: if Koin starts with `allowOverride(false)`, mark test definitions with `.override()` (see [Definitions](/docs/reference/koin-core/definitions#overriding-a-definition)).
- Instance already created: a `single` created before the override keeps the old dependency. Restart Koin with the test rule.
- Rule order: the Activity was launched before Koin was configured (see [Espresso and rule order](#espresso-and-rule-order)).

### NoDefinitionFoundException for a scoped definition

The scope was not open when you resolved it. Resolve scoped definitions inside `scenario.onActivity { }` while the Activity is alive, and check that the definition is declared in the right scope (`activityScope`, `fragmentScope`).

## Related

- [Unit Testing](/docs/reference/koin-test/testing): `KoinTest`, `KoinTestRule`, `declareMock` and overrides.
- [Testing Composables](/docs/reference/koin-compose/compose-testing): Compose UI tests and previews.
- [Verifying your Configuration](/docs/reference/koin-test/verify): `verify()` and `androidVerify()`.
- [Android Scopes](/docs/reference/koin-android/scope): Activity, Fragment and ViewModel scopes.
- [Starting Koin on Android](/docs/reference/koin-android/start): `startKoin` in your `Application`.

---

# Testing Composables

Source: https://insert-koin.io/docs/reference/koin-compose/compose-testing

This page covers what is specific to Compose when you test with Koin: previews with `KoinApplicationPreview`, UI tests with a `ComposeTestRule`, and multiplatform UI tests. It assumes you know how to inject in Composables with `koinInject()` and `koinViewModel()` (see [Koin for Compose](/docs/reference/koin-compose/compose)). Test setup, overrides and `declareMock` are explained in [Unit Testing](/docs/reference/koin-test/testing).

## Previews with KoinApplicationPreview

Previews do not run your `Application` class, so no Koin container exists. `KoinApplicationPreview` creates one for the preview:

```kotlin
import org.koin.compose.KoinApplicationPreview

val previewModule = module {
    single<UserRepository> { FakeUserRepository(sampleUsers) }
    viewModel { UserViewModel(get()) }
}

@Preview
@Composable
fun UserScreenPreview() {
    KoinApplicationPreview(application = { modules(previewModule) }) {
        UserScreen()
    }
}
```

`KoinApplicationPreview` creates a local container with `koinApplication`, not the global one started by `startKoin`. Each preview gets its own instance, so Android Studio can render several previews in parallel.

A lambda definition like `single<UserRepository> { FakeUserRepository(sampleUsers) }` works in every style. The `application` lambda accepts anything you write in `startKoin { }`, so you can also load production modules and override only what the preview needs.

To preview several states, give each preview a module with a different fake:

```kotlin
@Preview(name = "Error")
@Composable
fun UserScreenErrorPreview() {
    KoinApplicationPreview(application = {
        modules(previewModule, module {
            single<UserRepository> { FailingUserRepository() }
        })
    }) {
        UserScreen()
    }
}
```

Several `@Preview` annotations on the same function (light and dark mode, font scale) share the same module.

## UI tests with ComposeTestRule

`koinInject()` and `koinViewModel()` resolve from the global context when no Koin instance is provided by the composition. Start Koin with `KoinTestRule` and set the content:

```kotlin
class UserScreenTest : KoinTest {

    @get:Rule(order = 0)
    val koinTestRule = KoinTestRule.create {
        modules(module {
            single<UserRepository> { FakeUserRepository(sampleUsers) }
            viewModel { UserViewModel(get()) }
        })
    }

    @get:Rule(order = 1)
    val composeTestRule = createComposeRule()

    @Test
    fun displaysUserList() {
        composeTestRule.setContent {
            UserScreen()
        }

        composeTestRule.onNodeWithText("Alice").assertIsDisplayed()
    }
}
```

If the Composable you test contains `KoinApplication(configuration = ...)`, it attaches to the container started by the rule and ignores its own configuration. Your test modules are used.

`KoinContext { }` is deprecated and not needed: do not wrap test content with it.

On Android, these tests run as instrumented tests (or with Robolectric). If the graph needs a `Context`, add `androidContext(...)` in the rule, as shown in [Android Instrumented Testing](/docs/reference/koin-android/instrumented-testing#restart-koin-with-a-test-rule).

### Fakes and mocks

Use a fake to drive the screen into each state:

```kotlin
class UserScreenStatesTest : KoinTest {

    private val fakeRepository = FakeUserRepository()

    @get:Rule(order = 0)
    val koinTestRule = KoinTestRule.create {
        modules(module {
            single<UserRepository> { fakeRepository }
            viewModel { UserViewModel(get()) }
        })
    }

    @get:Rule(order = 1)
    val composeTestRule = createComposeRule()

    @Test
    fun showsErrorMessage() {
        fakeRepository.shouldFail = true

        composeTestRule.setContent { UserScreen() }

        composeTestRule.waitUntil(timeoutMillis = 5_000) {
            composeTestRule.onAllNodesWithText("Network error")
                .fetchSemanticsNodes().isNotEmpty()
        }
    }
}
```

Change the fake before `setContent`: the ViewModel is created on first composition and loads its data from there.

To use a mocking library instead, call `declareMock<UserRepository> { ... }` before `setContent` (see [Mocking with declareMock](/docs/reference/koin-test/testing#mocking-with-declaremock)).

### Screens using an isolated context

If the screen gets its Koin instance from `KoinIsolatedContext` (see [Isolated Context](/docs/reference/koin-compose/isolated-context)), the test doesn't need the global context. Build a test container and provide it the same way:

```kotlin
@Test
fun sdkScreenUsesTestContainer() {
    val testKoin = koinApplication {
        modules(module { single<SdkApi> { FakeSdkApi() } })
    }

    composeTestRule.setContent {
        KoinIsolatedContext(context = testKoin) {
            SdkScreen()
        }
    }

    composeTestRule.onNodeWithText("Connected").assertIsDisplayed()
    testKoin.close()
}
```

No global state is involved, so these tests can run in parallel.

## Multiplatform UI tests

In `commonTest`, JUnit rules are not available. Use `runComposeUiTest` from the Compose Multiplatform test library, and start and stop Koin with `kotlin.test` annotations:

```kotlin
// commonTest
@OptIn(ExperimentalTestApi::class)
class UserScreenCommonTest : KoinTest {

    @BeforeTest
    fun before() {
        startKoin {
            modules(module {
                single<UserRepository> { FakeUserRepository(sampleUsers) }
                viewModel { UserViewModel(get()) }
            })
        }
    }

    @AfterTest
    fun after() {
        stopKoin()
    }

    @Test
    fun displaysUserList() = runComposeUiTest {
        setContent { UserScreen() }

        onNodeWithText("Alice").assertIsDisplayed()
    }
}
```

`KoinTest`, `startKoin` and `declareMock` are multiplatform. `KoinTestRule` and `MockProviderRule` are JVM only. Set up the test dependencies as described in the [Compose Multiplatform testing guide](https://kotlinlang.org/docs/multiplatform/compose-test.html), and add `io.insert-koin:koin-test` to `commonTest`.

## Pitfalls

- Rule order: Koin must start before the content is set. With `createAndroidComposeRule<MainActivity>()`, the Activity is launched by the rule, so give `KoinTestRule` the lower `order`.
- ViewModel already created: a ViewModel created in an earlier composition keeps its dependencies. Change fakes or mocks before `setContent`.
- Preview containers are local: code that reads the global context (`KoinPlatform.getKoin()`, a `KoinComponent` outside Compose) does not see the `KoinApplicationPreview` container.

## Related

- [Unit Testing](/docs/reference/koin-test/testing): `KoinTestRule`, overrides and `declareMock`.
- [Android Instrumented Testing](/docs/reference/koin-android/instrumented-testing): test Application, rule order with Activities.
- [Koin for Compose](/docs/reference/koin-compose/compose): `koinInject()` and `KoinApplication`.
- [ViewModel in Compose](/docs/reference/koin-compose/compose-viewmodel): how `koinViewModel()` creates and keeps ViewModels.
- [Isolated Context](/docs/reference/koin-compose/isolated-context): `KoinIsolatedContext` for SDKs and libraries.

---

# Ktor Testing

Source: https://insert-koin.io/docs/reference/koin-ktor/ktor-testing

This page covers testing a Ktor server that uses Koin: running your routes with `testApplication`, replacing definitions with test modules, and isolating tests from each other. It assumes you know how to [install Koin in Ktor](/docs/reference/koin-ktor/ktor). For tests of plain classes, with no HTTP layer, use the techniques of [Unit Testing](/docs/reference/koin-test/testing).

## Dependencies

```kotlin
dependencies {
    testImplementation("io.ktor:ktor-server-test-host")
    testImplementation("io.insert-koin:koin-test")
    testImplementation("io.insert-koin:koin-test-junit4") // or koin-test-junit5
}
```

## Run routes with testApplication

`install(Koin)` works inside `testApplication` as in production. Install it with your test modules, then add your routes:

**Compiler Plugin DSL**
```kotlin
class UserRoutesTest {

    @Test
    fun `returns a user`() = testApplication {
        application {
            install(Koin) {
                modules(appModule, testModule)
            }
            configureRouting()
        }

        val response = client.get("/users/1")
        assertEquals(HttpStatusCode.OK, response.status)
    }
}
```

**Annotations**
```kotlin
import org.koin.plugin.module.dsl.withConfiguration

class UserRoutesTest {

    @Test
    fun `returns a user`() = testApplication {
        application {
            install(Koin) {
                withConfiguration<MyApp>()
                modules(testModule)
            }
            configureRouting()
        }

        val response = client.get("/users/1")
        assertEquals(HttpStatusCode.OK, response.status)
    }
}
```

**Constructor / Classic DSL**
```kotlin
class UserRoutesTest {

    @Test
    fun `returns a user`() = testApplication {
        application {
            install(Koin) {
                modules(appModule, testModule)
            }
            configureRouting()
        }

        val response = client.get("/users/1")
        assertEquals(HttpStatusCode.OK, response.status)
    }
}
```

```kotlin
val testModule = module {
    single<UserRepository> { InMemoryUserRepository(User("1", "Alice")) }
}
```

The test module is loaded last, so its `UserRepository` replaces the production one (see [Definitions](/docs/reference/koin-core/definitions#overriding-a-definition)). A lambda definition like this one works in every style.

Routes resolve dependencies with `inject()` and `get()` from `org.koin.ktor.ext`, as in production. When `testApplication` ends, Ktor stops the application and the Koin plugin closes its container.

## Reuse your application module

If your production `Application.module()` installs Koin, call it in the test and add overrides with `koinModules()`:

```kotlin
// production
fun Application.module() {
    install(Koin) {
        modules(appModule)
    }
    configureRouting()
}

// test
@Test
fun `returns a user`() = testApplication {
    application {
        module()
        koinModules(testModule)
    }

    assertEquals(HttpStatusCode.OK, client.get("/users/1").status)
}
```

`koinModules()` loads modules into the container created by `install(Koin)`. Ktor plugins can only be installed once, so a second `install(Koin)` in the test would fail.

`koinModules()` loads the overrides after `install(Koin)`. A definition created at install time (for example with `createdAtStart`) keeps the production dependencies.

## Isolate tests

`install(Koin)` starts Koin in the global context. If a container is already running, the plugin stops it first. Tests in sequence are fine, but two tests that run at the same time share the global context and break each other.

Extend `AutoCloseKoinTest` to stop Koin after each test, even when a test fails before the application shuts down:

```kotlin
class UserRoutesTest : AutoCloseKoinTest() {
    // tests
}
```

For parallel tests, install `KoinIsolated` instead. Each application gets its own container, outside the global context:

```kotlin
@Test
fun `returns a user`() = testApplication {
    application {
        install(KoinIsolated) {
            modules(appModule, testModule)
        }
        configureRouting()
    }

    assertEquals(HttpStatusCode.OK, client.get("/users/1").status)
}
```

With `KoinIsolated`, resolve dependencies through the Ktor extensions (`inject()`, `get()`, `call.scope`). A `KoinComponent` or `GlobalContext.get()` does not see the isolated container. See [Isolated Context in Ktor](/docs/reference/koin-ktor/ktor-isolated).

## Mock a dependency

Put the mock in the test module:

```kotlin
@Test
fun `returns 404 for an unknown user`() = testApplication {
    val repository = mockk<UserRepository> {
        every { findById(any()) } returns null
    }

    application {
        install(Koin) {
            modules(appModule, module { single { repository } })
        }
        configureRouting()
    }

    assertEquals(HttpStatusCode.NotFound, client.get("/users/999").status)
    verify { repository.findById("999") }
}
```

`declareMock` (see [Mocking with declareMock](/docs/reference/koin-test/testing#mocking-with-declaremock)) also works with `install(Koin)`, since it uses the global context. It does not work with `KoinIsolated`.

## Request scope

Definitions declared in `requestScope { }` are created for each call and closed when the response is sent (see [Request Scopes in Ktor](/docs/reference/koin-ktor/ktor-scopes)). Test them through a request:

```kotlin
@Test
fun `each call gets its own request logger`() = testApplication {
    application {
        install(Koin) {
            modules(module {
                requestScope {
                    scoped { RequestLogger() }
                }
            })
        }
        routing {
            get("/id") {
                call.respondText(call.scope.get<RequestLogger>().id)
            }
        }
    }

    val first = client.get("/id").bodyAsText()
    val second = client.get("/id").bodyAsText()
    assertNotEquals(first, second)
}
```

`call.scope` exists only while a call is processed. Resolving a request-scoped definition outside a route fails.

## Ktor DI bridge

When the [Ktor DI bridge](/docs/reference/koin-ktor/ktor-bridge) is enabled, provide test values with Ktor's `dependencies { }` in the test application, the same way as in production. `koinToKtor()` lets Koin definitions resolve them:

```kotlin
@Test
fun `uses the Ktor-provided database`() = testApplication {
    application {
        dependencies {
            provide<Database> { InMemoryDatabase() }
        }
        install(Koin) {
            bridge { koinToKtor() }
            modules(appModule)
        }
        configureRouting()
    }

    assertEquals(HttpStatusCode.OK, client.get("/users").status)
}
```

## Check your configuration

To check that every definition's dependencies are declared, without starting a server, see [Verifying your Configuration](/docs/reference/koin-test/verify). Types provided by Ktor at runtime, such as `ApplicationCall` in a request scope, go in `extraTypes`.

## Related

- [Koin for Ktor](/docs/reference/koin-ktor/ktor): install the plugin and inject in routes.
- [Isolated Context in Ktor](/docs/reference/koin-ktor/ktor-isolated): `KoinIsolated` and when to use it.
- [Request Scopes in Ktor](/docs/reference/koin-ktor/ktor-scopes): definitions bound to a call.
- [Unit Testing](/docs/reference/koin-test/testing): `KoinTest`, overrides and `declareMock`.
- [Verifying your Configuration](/docs/reference/koin-test/verify): check modules in a test.

---

# Production & Tooling

Source: https://insert-koin.io/docs/tooling

This page maps each stage of a Koin project to the tool that covers it. Koin itself covers build time, development and tests. For production, Kotzilla (the company that builds Koin) offers an optional monitoring platform.

Everything in Koin works without any of the tools on this page except the ones that ship with Koin. Pick what matches your need.

## Which tool for which need

| Stage | Need | Tool | Ships with Koin |
|-------|------|------|-----------------|
| Build time | Fail the build on a missing dependency or a wrong qualifier | [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety) with the Koin Compiler Plugin | Yes |
| Development | See what Koin creates and resolves | [Logging](/docs/reference/koin-core/starting-koin#logging) with `printLogger()` or a platform logger | Yes |
| Development | Navigate between definitions and injection points, see issues in the editor | [IDE Plugin](/docs/tooling/ide-plugin) for Android Studio and IntelliJ IDEA | No, free plugin by Kotzilla |
| Development | Let your AI coding agent set up, write, migrate and diagnose Koin code | [Koin Skills](/docs/tooling/ai-agents) for Claude Code, Cursor, Codex, Copilot | No, free skills by the Koin team |
| Tests | Check a module configuration without running the app | [Verifying Modules](/docs/reference/koin-test/verify) with `verify()` | Yes |
| Tests | Replace definitions with fakes or mocks | [Testing](/docs/reference/koin-test/testing) with `KoinTest` | Yes |
| Production | Trace the execution time of chosen functions | [@Monitor](/docs/tooling/monitor), with the Kotzilla SDK | Annotation yes, tracing needs the SDK |
| Production | See startup, main thread and background performance issues and crashes from real user sessions | [Production Monitoring](/docs/tooling/production-monitoring) with the Kotzilla platform | No, Kotzilla service |

## Build time

The Koin Compiler Plugin checks your dependency graph during compilation. A missing definition, a missing qualifier or an unknown scope fails the build with a `KOIN-Dxxx` diagnostic instead of crashing at runtime. This is the first line of defense: see [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety) for what is validated and how to set it up.

## Development

The Koin logger prints module loading and instance creation. Turn it on with `printLogger(Level.DEBUG)` or a platform logger (`androidLogger()`, SLF4J). It writes raw text to the console or Logcat, so it is a debugging aid, not a monitoring tool. See [Logging](/docs/reference/koin-core/starting-koin#logging).

The [IDE Plugin](/docs/tooling/ide-plugin) adds navigation, a tree view of modules and definitions, and configuration checks in the editor.

The [Koin skills](/docs/tooling/ai-agents) give your AI coding agent the Koin rules: setup, definitions, migration from another DI framework, and diagnosis of Koin errors.

## Tests

`verify()` checks that every definition in a module can be built, from a plain JUnit test. If you use the Compiler Plugin, compile-time safety already covers most of what `verify()` checks. See [Verifying Modules](/docs/reference/koin-test/verify) and [Testing](/docs/reference/koin-test/testing).

## Production

Compile-time safety and tests catch configuration errors. They don't tell you how the graph behaves on real devices: how long resolutions take at startup, which dependency blocks the main thread, which crash comes from a Koin resolution.

Koin has no production monitoring of its own. The Kotzilla platform covers this need, through the Kotzilla SDK that plugs into the Koin container. See [Production Monitoring](/docs/tooling/production-monitoring). The [@Monitor](/docs/tooling/monitor) annotation extends it to your own functions.

## Related

- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): what the Compiler Plugin checks at build time.
- [Starting Koin](/docs/reference/koin-core/starting-koin#logging): enable and configure the Koin logger.
- [Verifying Modules](/docs/reference/koin-test/verify): check a configuration from a test.
- [IDE Plugin](/docs/tooling/ide-plugin): navigation and checks in Android Studio and IntelliJ IDEA.
- [Production Monitoring](/docs/tooling/production-monitoring): the Kotzilla platform for Koin apps.

---

# IDE Plugin

Source: https://insert-koin.io/docs/tooling/ide-plugin

The Koin plugin for Android Studio and IntelliJ IDEA shows your Koin configuration inside the IDE: where each definition is declared, where it is used, and what is missing. It is built by Kotzilla and is free on the JetBrains Marketplace. It doesn't need the Kotzilla platform, except for the application issues described below.

## Installation

Install the plugin from the [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/26131-koin-dependency-injection-official-), or from the IDE: open Settings, then Plugins, then Marketplace, search for "Koin", then restart the IDE.

The plugin requires an IDE based on IntelliJ Platform 2024.2 or later. It works with Android, JVM and Kotlin Multiplatform projects.

## Configuration tree view

The plugin adds a tree view of your Koin configuration:

- **Modules**: every declared module, including test modules, modules declared inline in `startKoin` or `koinApplication`, and start entries.
- **Definitions**: each module's singletons, factories, ViewModels, scoped definitions and injected parameters.

You can search the tree by typing, and selecting an entry opens it in the editor.

The tree reads the Constructor and Classic DSL (`singleOf(::T)`, `single { }`), the Ktor DSL, the Compose API and Koin Annotations, including qualifiers and generic types.

## Navigation

Gutter icons mark definitions, injection points and parameters. From them you can:

- jump from an injection point (`get()`, `by inject()`, `koinViewModel()`, a constructor parameter) to the definition that provides it,
- jump from a definition to the places that use it,
- open the definition in the configuration tree.

The plugin reads the argument types of a definition to find what it depends on, including injected parameters. You can change which gutter icons are shown in the plugin settings.

## Configuration checks

The plugin checks your configuration while you edit and reports problems in the "Configuration issues" tab of the Koin Insights view: a dependency with no definition, a usage of a type nobody declares, a definition nobody uses, and other misconfigurations.

Each inspection can be turned on or off in the IDE settings.

:::note
These checks run in the editor. They are a fast feedback loop, not a replacement for build-time validation. With the [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin), the same kind of error fails the build: see [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety).
:::

## Application issues

If your app sends data to the Kotzilla platform through the Kotzilla SDK, the "Application issues" tab shows the issues detected in real user sessions (slow startup, main thread blocking, background bottlenecks, crashes) next to your code. The "Kotzilla Flight Check" tab shows your Koin version and whether the SDK is configured.

This part needs a Kotzilla account and the SDK. See [Production Monitoring](/docs/tooling/production-monitoring).

For a detected issue, the plugin can generate a prompt with its context (impacted components, dependency chain, performance data) to paste into an AI coding assistant such as GitHub Copilot, Gemini, Claude Code or Junie.

## Limits

- **In active development**: features change from release to release. Check the Marketplace page for the current version and changelog.
- **Editor only**: the plugin doesn't run in CI. For checks that block a merge, use [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety) or [Verifying Modules](/docs/reference/koin-test/verify).

The plugin's own documentation is on [doc.kotzilla.io](https://doc.kotzilla.io/docs/discover/idePlugin).

## Related

- [Production & Tooling](/docs/tooling): which tool for which need.
- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): the same errors, caught at build time.
- [Verifying Modules](/docs/reference/koin-test/verify): check a configuration from a test.
- [Troubleshooting](/docs/reference/koin-core/troubleshooting): read and fix Koin errors.
- [Production Monitoring](/docs/tooling/production-monitoring): the data behind the application issues tab.

---

# AI Agents and Koin Skills

Source: https://insert-koin.io/docs/tooling/ai-agents

The Koin skills teach a coding agent how to work with Koin 4.x and the Koin Compiler Plugin: which style to use, how to declare and wire definitions, how to migrate from another DI framework and how to diagnose a Koin error. They are maintained by the Koin team in the [koin-skills repository](https://github.com/InsertKoinIO/koin-skills) on GitHub, and published as the `koin` plugin for Claude Code and as standard agent skills for other agents. This page shows how to install them and what each one does.

## Install in Claude Code

```
/plugin marketplace add InsertKoinIO/koin-skills
/plugin install koin@koin-skills
```

The first command adds the Koin skills repository as a plugin marketplace, the second installs the `koin` plugin from it. Update later with `/plugin marketplace update koin-skills`.

The skills load on their own when a task touches dependency injection in a Kotlin, Android, Compose, KMP or Ktor project. You don't need to call them by name.

## Install in other agents

For Cursor, Codex, Copilot, Windsurf, Gemini and other agents that read agent skills, use the [skills](https://skills.sh) CLI (Node.js 22 or later):

```bash
npx skills add InsertKoinIO/koin-skills
```

It reads the skills from the [koin-skills repository](https://github.com/InsertKoinIO/koin-skills) (the full URL `https://github.com/InsertKoinIO/koin-skills` works too), lists the four skills and installs the ones you pick, for the agents you pick. To install all of them without prompts: `npx skills add InsertKoinIO/koin-skills --skill '*' -y`. Each [GitHub release](https://github.com/InsertKoinIO/koin-skills/releases) also attaches one `.skill` archive per skill and the full plugin as `koin-plugin.zip`.

## What the skills do

| Skill | Use it to |
|---|---|
| `koin-setup` | Add Koin to a new or existing project, or next to a DI container you keep |
| `koin` | Write Koin code in the project's style: definitions, modules, entry points, scopes, tests |
| `di-migration` | Migrate from Hilt, Dagger, Toothpick, Kodein, Metro, Koin 3.x, Koin DSL or Koin KSP, module by module |
| `koin-diagnose` | Fix Koin errors and crashes, and check how the app behaves at runtime |

The skills follow the rules of these docs. They use [constructor injection](/docs/reference/koin-core/dsl), the Compiler Plugin DSL or Koin Annotations, and never Koin KSP for new code. A migration is progressive: the old container keeps running until the last binding has moved.

## Kotzilla MCP Server

The skills can use the [Kotzilla](https://kotzilla.io) MCP Server to diagnose Koin errors and to measure how definitions behave at runtime (lifetime, scopes, startup cost). It needs a free Kotzilla account. The skills propose it when it helps and never require it.

In Claude Code, the `koin` plugin includes the server. It stays inactive until you sign in: run `/mcp`, select `plugin:koin:kotzilla` and sign in. In other agents, add the endpoint `https://mcp.kotzilla.io/mcp` (HTTP transport, OAuth) to the agent's MCP configuration.

## Limits

- The skills target Koin 4.2.2 or later with Kotlin 2.3.20 or later. On an older Koin, they work in the current setup and propose the upgrade once.
- The skills guide the agent, they don't replace review. Read the changes before you merge them.
- Runtime checks (startup, memory, instances created twice) need the Kotzilla SDK in the app. Without it, the skills point out likely causes from the code, not measurements.

## Related

- [Compiler Plugin setup](/docs/setup/compiler-plugin): the build-time checks the skills rely on.
- [Koin vs Hilt](/docs/intro/koin-vs-hilt): what changes when you migrate from Hilt.
- [Monitoring](/docs/tooling/monitor): the Kotzilla SDK behind the runtime checks.
- [Koin skills on GitHub](https://github.com/InsertKoinIO/koin-skills): sources, issues and releases.

---

# @Monitor

Source: https://insert-koin.io/docs/tooling/monitor

`@Monitor` marks a class or a function for tracing. At build time, the Koin Compiler Plugin wraps each monitored function in a Kotzilla SDK trace call, so its execution time and errors show up in the Kotzilla platform. This page covers what the annotation does with and without the Kotzilla SDK. It assumes the [Koin Compiler Plugin](/docs/setup/compiler-plugin) is set up.

## Built-in monitoring without Kotzilla

Koin's built-in way to see what happens at runtime is the logger. It prints module loading and instance creation to the console or Logcat. See [Logging](/docs/reference/koin-core/starting-koin#logging).

`@Monitor` adds nothing on its own. Without the Kotzilla SDK on the compile classpath, the Compiler Plugin leaves monitored functions unchanged and reports one warning per compilation:

```
KOIN-M001: @Monitor: Kotzilla SDK not found on classpath - monitoring disabled
```

The code compiles and runs as if the annotation were not there. You can keep `@Monitor` in shared code and only add the SDK in the builds you want to trace.

## Annotating a class or a function

`@Monitor` is in `org.koin.core.annotation`, next to the other Koin annotations. Put it on a class to trace all its public functions, or on a single function:

```kotlin
import org.koin.core.annotation.Monitor

@Monitor
class UserService(private val userRepository: UserRepository) {

    fun findUser(id: String): User? = userRepository.findById(id)

    suspend fun createUser(userData: UserData): User = userRepository.save(userData)

    private fun audit(user: User) { ... } // private: not traced
}

class SyncService(private val api: ApiService) {

    @Monitor
    suspend fun sync() { ... }
}
```

The annotation works the same whatever style declares the class: annotations or any DSL form (Compiler Plugin, Constructor or Classic DSL). ViewModels can be monitored too:

```kotlin
@Monitor
class DetailViewModel(private val repository: Repository) : ViewModel() {
    fun loadData(id: String): StateFlow<Data> = repository.getData(id)
}
```

## What the Compiler Plugin generates

With the Kotzilla SDK on the classpath, the Compiler Plugin rewrites the body of each monitored function. `findUser` from the `UserService` class compiles as if you had written:

```kotlin
fun findUser(id: String): User? =
    KotzillaCore.getDefaultInstance().trace("UserService.findUser") {
        userRepository.findById(id)
    }
```

Rules:

- **Label**: `ClassName.functionName`, or the function name for a top-level function.
- **Suspend functions**: wrapped with `suspendTrace` instead of `trace`.
- **Class-level `@Monitor`**: only public functions are traced. Private, protected and internal functions, constructors and default property accessors are not.
- **No proxy, no `allOpen`**: the body is rewritten in place. The class stays final and Koin creates it as usual.

During the build, the plugin reports each monitored class:

```
@Monitor: UserService - tracing enabled (2 functions)
```

This message is a warning by default. If your build uses `allWarningsAsErrors`, set `logSeverity = "info"` in the `koinCompiler { }` block: see [Compiler Plugin Options](/docs/reference/koin-annotations/options).

## With the Kotzilla SDK

`@Monitor` needs the Kotzilla SDK twice:

- **At build time**: the class `io.kotzilla.sdk.KotzillaCore` must be on the compile classpath. The `io.kotzilla:kotzilla-sdk` dependency brings it, through `io.kotzilla:kotzilla-core`.
- **At runtime**: the SDK must be started in your Koin configuration so that traces are recorded and sent.

Both are part of the standard Kotzilla setup described in [Production Monitoring](/docs/tooling/production-monitoring). Once the SDK runs, each call to a monitored function is recorded with its duration and, if it throws, its error. You see them in the Kotzilla console.

:::warning
The generated code calls `KotzillaCore.getDefaultInstance()`. Start the Kotzilla SDK at app startup, before any monitored function can run.
:::

## With Koin Annotations (KSP)

With the KSP processor (`koin-ksp-compiler`, Koin Annotations 2.2.0 and later), `@Monitor` works differently. KSP can't rewrite a function body, so it generates a subclass named `<ClassName>Proxy` that overrides each public function with the trace call, and the Koin definition uses this proxy. Two consequences:

- **Open classes**: the monitored class must be open. Configure the `allOpen` Gradle plugin with `annotation("org.koin.core.annotation.Monitor")`.
- **Definitions only**: only classes that are Koin definitions are proxied.

The Compiler Plugin replaces this mechanism. See [Migrating from KSP to the Compiler Plugin](/docs/migration/from-ksp-to-compiler-plugin).

## Limits

- **No transitive tracing**: only the annotated class or function is traced. Dependencies injected into a monitored class are not, unless they carry `@Monitor` too.
- **No local data**: without the Kotzilla SDK nothing is recorded. For local debugging, use the [Koin logger](/docs/reference/koin-core/starting-koin#logging).
- **Overhead**: every monitored call goes through a trace call. Annotate the functions you want to measure, not every class.

## Related

- [Production Monitoring](/docs/tooling/production-monitoring): set up the Kotzilla SDK that records the traces.
- [Production & Tooling](/docs/tooling): which tool for which need.
- [Starting Koin](/docs/reference/koin-core/starting-koin#logging): the Koin logger for local debugging.
- [Compiler Plugin Options](/docs/reference/koin-annotations/options): `logSeverity` and other plugin settings.
- [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): every Koin annotation.

---

# Production Monitoring

Source: https://insert-koin.io/docs/tooling/production-monitoring

The Kotzilla platform monitors Koin apps in production. The Kotzilla SDK plugs into the Koin container, records how dependencies are resolved in real user sessions, and the Kotzilla console turns this data into performance issues and crash reports. Kotzilla is the company that builds Koin. The platform is a separate, optional service: Koin works fully without it.

Before production, Koin's own tools catch most configuration errors: [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety), [logging](/docs/reference/koin-core/starting-koin#logging) and [module verification](/docs/reference/koin-test/verify). This page covers what happens after release. For an overview of all tools, see [Production & Tooling](/docs/tooling).

## What it detects

The console groups session data into issues:

| Issue | What it means |
|-------|---------------|
| Startup Performance | Delays during app initialization |
| Main Thread Performance | Work on the main thread that freezes the screen. A dependency resolution of 100 ms or more on the main thread is reported here |
| Background Performance | Bottlenecks in background thread processing |
| Crashes | Crashes from real user sessions |

The console gives graphical views to investigate performance bottlenecks, crashes and architectural issues. The same issues appear in the [IDE Plugin](/docs/tooling/ide-plugin).

## How it works

The SDK hooks into the Koin container at startup. From then on, it records two kinds of data:

- **Structure**: the dependency graph, with modules, definitions and bindings.
- **Runtime behavior**: resolution timings, lifecycle events and crashes.

You don't add tracing code to your classes: the data comes from the container. To also trace your own functions, add [@Monitor](/docs/tooling/monitor).

Platforms supported by the SDK: Android, and Kotlin Multiplatform targets including iOS, JVM desktop, JS and Wasm.

## Setup overview

The detailed, current steps are in the official Kotzilla guides. Use them, the outline below only shows the shape of the setup:

1. Create an account and register your app, from the [Kotzilla console](https://console.kotzilla.io), the [IDE Plugin](/docs/tooling/ide-plugin) or the MCP server. You get a `kotzilla.json` file with your app keys.
2. Add the Kotzilla Gradle plugin (`io.kotzilla.kotzilla-plugin`) and the SDK dependency (`io.kotzilla:kotzilla-sdk`).
3. Put `kotzilla.json` in the app module (Android) or the shared module (KMP).
4. Call `monitoring()` last in your `startKoin` block.

On Android:

```kotlin
import io.kotzilla.generated.monitoring

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidContext(this@MainApplication)
            modules(appModule)
            monitoring()
        }
    }
}
```

`monitoring()` is generated at build time by the Kotzilla Gradle plugin from your `kotzilla.json`. Call it once per platform entry point, not from a composable.

Platform guides:

- [Android](https://doc.kotzilla.io/docs/getstartedCustom/setupAndroid)
- [Android Compose](https://doc.kotzilla.io/docs/getstartedCustom/setupAndroidCompose)
- [Kotlin Multiplatform](https://doc.kotzilla.io/docs/getstartedCustom/setupKMP)
- [Compose Multiplatform](https://doc.kotzilla.io/docs/getstartedCustom/setupCMP)
- [SDK for libraries](https://doc.kotzilla.io/docs/getstartedCustom/setupSDKLibrary)

:::note
On iOS, crash symbolication needs a dSYM upload step. The Kotlin Multiplatform guide covers it.
:::

## AI assistant integration

The Kotzilla MCP server connects an AI coding assistant (Claude Code, Cursor, Windsurf, Android Studio and other MCP clients) to Koin diagnostics. Paste a Koin error into the assistant and the server classifies it, then returns a step-by-step fix workflow. It recognizes:

- **Compile-time diagnostics** from the Koin Compiler Plugin, from `KOIN-D001` to `KOIN-M001`.
- **Runtime exceptions** such as `NoBeanDefFoundException`, `InstanceCreationException` and circular dependency errors.

The endpoint is `https://mcp.kotzilla.io/mcp` (streamable HTTP). With Claude Code:

```bash
claude mcp add kotzilla --transport http https://mcp.kotzilla.io/mcp
```

The server asks you to sign in with a Kotzilla account on first use. Fixing compile errors works without the SDK. Analyzing runtime behavior needs the SDK and session data.

When a build reports a Koin diagnostic, the Koin Compiler Plugin prints one hint pointing to the MCP server. To turn it off, set `aiAssist = false` in the `koinCompiler { }` block.

See the [MCP server guide](https://doc.kotzilla.io/docs/fixIssues/koinMcp) for other clients.

## Data and privacy

The SDK sends technical session data: the dependency graph and the runtime data listed in [How it works](#how-it-works). The MCP server sends only the error text and structured queries from your assistant. Your source files stay on your machine.

For the full policy, see the [Kotzilla privacy policy](https://kotzilla.io/privacy).

## Cost

The developer plan is free, with no time limit and a limited quota of events. Enterprise plans add team collaboration features. See [kotzilla.io](https://kotzilla.io) for current plans.

## What it does not do

- **It doesn't validate your configuration at build time.** That is the job of [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety).
- **It doesn't replace tests.** Use [Testing](/docs/reference/koin-test/testing) to check behavior before release.
- **It doesn't change how Koin resolves dependencies.** The SDK observes the container, your definitions stay the same.
- **It doesn't trace your own code by default.** Only Koin resolutions are recorded, unless you add [@Monitor](/docs/tooling/monitor).

## Related

- [Production & Tooling](/docs/tooling): which tool for which need.
- [@Monitor](/docs/tooling/monitor): trace your own functions with the Kotzilla SDK.
- [IDE Plugin](/docs/tooling/ide-plugin): see production issues next to your code.
- [Troubleshooting](/docs/reference/koin-core/troubleshooting): read and fix Koin errors.
- [Kotzilla documentation](https://doc.kotzilla.io): full platform and SDK documentation.

---

# Koin vs Hilt

Source: https://insert-koin.io/docs/intro/koin-vs-hilt

This page compares Koin with Hilt (and Dagger, which Hilt is built on) for Android developers who know one and want to understand the other. It covers how each framework builds the dependency graph, what the code looks like, and where each one has the advantage. To move a project from Hilt to Koin, see [Migrating from Hilt](/docs/reference/koin-android/hilt-migration).

Koin samples below use annotations, because they are closest to Hilt. The same definitions can be written with the Koin DSL (see [Choosing your style](/docs/intro/choosing-your-style)).

## How each one builds the graph

**Hilt** generates the dependency graph as Java source code at build time, with annotation processing (KSP or kapt). Every binding, component and scope is known when the app compiles. At runtime, the app calls generated factories directly, with no lookup.

**Koin** keeps the graph in a runtime container. Definitions are registered when Koin starts, and instances are resolved by type when requested. With the [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin), the graph assembled at `startKoin` is also checked at build time, and the plugin generates the constructor wiring. Without the plugin, a missing definition is found at runtime or in a [verification test](/docs/reference/koin-test/verify).

This difference explains most of the tradeoffs below.

## At a glance

| Aspect | Koin | Hilt |
|--------|------|------|
| Graph built | At runtime, checked at build time with the Compiler Plugin | At build time, generated code |
| Missing binding detected | Build time with the Compiler Plugin, otherwise at runtime or in a test | Build time, always |
| Build tooling | Kotlin compiler plugin, optional with the Constructor or Classic DSL | KSP or kapt, Hilt Gradle plugin |
| Platforms | Kotlin Multiplatform: Android, iOS, desktop, web, JVM server | Android (Dagger alone runs on the JVM) |
| Languages | Kotlin | Java and Kotlin |
| Load or unload modules at runtime | Yes (`loadKoinModules`, `unloadKoinModules`, lazy modules) | No |
| Component hierarchy | Root container plus scopes you declare, with Android scope archetypes | Fixed hierarchy of standard components (`SingletonComponent`, `ActivityComponent`, ...) |
| Android entry points | `by inject()`, `by viewModel()` in any Activity or Fragment | `@AndroidEntryPoint` on each class |
| Jetpack integration | ViewModel, WorkManager, Navigation, Compose, through Koin libraries | ViewModel, WorkManager, Navigation, Compose, through AndroidX Hilt libraries |

## Where Hilt is stronger

- **Complete graph at build time**: Hilt generates the whole graph, so every binding is verified on every build, for every module and scope. The Koin Compiler Plugin validates the graph at entry points, but modules loaded at runtime and library modules alone are outside its view.
- **No runtime lookup**: generated factories are called directly. Koin resolves each request through its container, which costs a lookup per resolution and registration work at startup.
- **Java support**: Dagger and Hilt work in Java codebases. Koin's API is designed for Kotlin.
- **Ecosystem and guidance**: Hilt is the DI library documented in the official Android guides, and many AndroidX libraries and samples ship Hilt integration first.
- **Detailed errors**: a Dagger error shows the full path from the entry point to the missing binding.

## Where Koin is stronger

- **Kotlin Multiplatform**: the same modules run on Android, iOS, desktop, web and Ktor servers. Hilt is Android only.
- **Runtime flexibility**: modules can be loaded, unloaded or loaded in the background after start, which fits feature flags, dynamic features and plugin architectures.
- **Less setup**: no annotation processor, no generated sources, no `@AndroidEntryPoint`. With the Constructor or Classic DSL, the build plugin is optional.
- **Less declaration code**: constructors need no `@Inject`, and interfaces are bound to their implementation without a separate `@Binds` module.
- **Your choice of style**: DSL or annotations, which can be mixed.

## Code side by side

### A class with dependencies

Koin:

```kotlin
@Singleton
class UserRepositoryImpl(private val api: ApiService) : UserRepository
```

Koin binds `UserRepositoryImpl` to `UserRepository` because it implements it.

Hilt:

```kotlin
@Singleton
class UserRepositoryImpl @Inject constructor(private val api: ApiService) : UserRepository

@Module
@InstallIn(SingletonComponent::class)
abstract class RepositoryModule {
    @Binds
    abstract fun bindUserRepository(impl: UserRepositoryImpl): UserRepository
}
```

### Third-party classes

Koin:

```kotlin
@Module
class NetworkModule {
    @Singleton
    fun retrofit(): Retrofit = Retrofit.Builder()
        .baseUrl("https://api.example.com")
        .build()

    @Singleton
    fun apiService(retrofit: Retrofit): ApiService =
        retrofit.create(ApiService::class.java)
}
```

Hilt:

```kotlin
@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {
    @Provides
    @Singleton
    fun retrofit(): Retrofit = Retrofit.Builder()
        .baseUrl("https://api.example.com")
        .build()

    @Provides
    @Singleton
    fun apiService(retrofit: Retrofit): ApiService =
        retrofit.create(ApiService::class.java)
}
```

The two are close. Koin needs no `@InstallIn` because the module is not tied to a component, and no `@Provides` because `@Singleton` on a function already declares a definition.

### ViewModel

Koin:

```kotlin
@KoinViewModel
class UserViewModel(
    private val repository: UserRepository,
    private val savedStateHandle: SavedStateHandle,
) : ViewModel()

// Activity or Fragment
val viewModel: UserViewModel by viewModel()

// Compose
val viewModel: UserViewModel = koinViewModel()
```

Hilt:

```kotlin
@HiltViewModel
class UserViewModel @Inject constructor(
    private val repository: UserRepository,
    private val savedStateHandle: SavedStateHandle,
) : ViewModel()

// Activity or Fragment annotated with @AndroidEntryPoint
val viewModel: UserViewModel by viewModels()

// Compose
val viewModel: UserViewModel = hiltViewModel()
```

### Several Gradle modules

Koin:

```kotlin
// feature-auth
@Module
@ComponentScan
@Configuration
class AuthModule

// app
@KoinApplication
class MyApp
```

Hilt:

```kotlin
// feature-auth
@Module
@InstallIn(SingletonComponent::class)
class AuthModule { ... }

// app
@HiltAndroidApp
class MyApp : Application()
```

Both discover feature modules on the classpath: Koin through `@Configuration`, Hilt through `@InstallIn`. In Koin, `@ComponentScan` also collects every annotated class of the package, so a feature module often needs no provider functions.

## Concept mapping

| Hilt | Koin |
|------|------|
| `@HiltAndroidApp` | `@KoinApplication` with `startKoin<MyApp>()`, or `startKoin { }` |
| `@AndroidEntryPoint` | Not needed: `by inject()` and `by viewModel()` work in any Activity or Fragment |
| `@Inject constructor` | Not needed: the constructor is read by the Compiler Plugin |
| `@Binds` | Automatic for annotations, `bind` in the DSL |
| `@Provides` | `@Singleton` or `@Factory` on a function, or a DSL definition |
| `@InstallIn(SingletonComponent::class)` | `@Configuration` |
| `@HiltViewModel` | `@KoinViewModel` |
| `@Named` | `@Named` |
| `@ActivityScoped`, `@ViewModelScoped` | `@ActivityScope`, `@ViewModelScope` |
| `@AssistedInject` | `@InjectedParam` |

The migration guide has the full mapping, a step-by-step process, and how to run both frameworks side by side during the move: see [Migrating from Hilt](/docs/reference/koin-android/hilt-migration).

## Related

- [Migrating from Hilt](/docs/reference/koin-android/hilt-migration): move a project step by step.
- [JSR-330 Compatibility](/docs/reference/koin-android/jsr330): keep `javax.inject` annotations.
- [What is Koin?](/docs/intro/what-is-koin): Koin's runtime and compile-time model.
- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): what Koin checks at build time.
- [Choosing your style](/docs/intro/choosing-your-style): DSL or annotations.

---

# Migrating from Hilt

Source: https://insert-koin.io/docs/reference/koin-android/hilt-migration

This guide moves an Android app from Dagger Hilt to Koin, one step at a time: Gradle, the `Application` class, modules, bindings, ViewModels, entry points, qualifiers, Compose and tests. Each Koin sample comes in the three Koin styles; if you are not sure which one to pick, read [Choosing your style](/docs/intro/choosing-your-style). For a comparison of the two frameworks, see [Koin vs Hilt](/docs/intro/koin-vs-hilt).

:::note
For a full real-world migration, read [Migrating Now in Android to Koin](https://blog.insert-koin.io/migrating-now-in-android-to-koin-annotations-2-3-67d252dbb97d): Google's sample app with 30 Gradle modules, moved from Hilt to Koin Annotations.
:::

## Concept mapping

| Hilt | Compiler Plugin DSL | Annotations | Constructor / Classic DSL |
|------|---------------------|-------------|-------------|
| `@HiltAndroidApp` | `startKoin { }` in `Application.onCreate()` | `@KoinApplication` + `startKoin<T>()` | `startKoin { }` in `Application.onCreate()` |
| `@AndroidEntryPoint` | Not needed: `by inject()`, `by viewModel()` | Not needed | Not needed |
| `@Inject constructor` | `single<T>()` / `factory<T>()` | `@Singleton` / `@Factory` on the class | `singleOf(::T)` / `factoryOf(::T)` |
| `@Module` + `@InstallIn` | `module { }` | `@Module` + `@ComponentScan` | `module { }` |
| `@Provides` | `single { create(::fn) }` | `@Singleton` / `@Factory` on a function | `single { ... }` |
| `@Binds` | `bind Interface::class` | Automatic (supertypes) or `binds = [...]` | `bind Interface::class` |
| `@Singleton` | `single` | `@Singleton` / `@Single` | `single` |
| `@HiltViewModel` | `viewModel<T>()` | `@KoinViewModel` | `viewModelOf(::T)` |
| `@HiltWorker` | `worker<T>()` | `@KoinWorker` | `workerOf(::T)` |
| `@Named`, custom `@Qualifier` | `named("x")`, `@Named` on parameters | `@Named`, custom `@Qualifier` | `named("x")` |
| `@ApplicationContext` | `Context` parameter, provided by `androidContext()` | Same | `androidContext()` |
| `@AssistedInject` | Injected parameters | `@InjectedParam` | Injected parameters |
| `@Inject` field in a class you own | Constructor parameter | Constructor parameter | Constructor parameter |
| `@EntryPoint` (framework class Hilt can't inject) | `KoinComponent` at that entry point only | Same | Same |
| `@HiltAndroidTest` | `KoinTestRule` | `KoinTestRule` | `KoinTestRule` |

### Scope mapping

| Hilt | Koin DSL | Annotations | Lifetime |
|------|----------|-------------|----------|
| `@Singleton` (`SingletonComponent`) | `single` | `@Singleton` | Application |
| `@ActivityRetainedScoped` | `activityRetainedScope { }` | `@ActivityRetainedScope` | Survives configuration changes |
| `@ViewModelScoped` | `viewModelScope { }` | `@ViewModelScope` | ViewModel |
| `@ActivityScoped` | `activityScope { }` | `@ActivityScope` | Activity |
| `@FragmentScoped` | `fragmentScope { }` | `@FragmentScope` | Fragment |

Scope DSL and annotations are explained in [Android Scopes](/docs/reference/koin-android/scope).

## Step 1: Gradle

Remove the Hilt plugin, `hilt-android`, and `hilt-compiler` (kapt or KSP). Then add Koin:

```kotlin
dependencies {
    implementation(platform("io.insert-koin:koin-bom:$koin_version"))
    implementation("io.insert-koin:koin-android")
    implementation("io.insert-koin:koin-androidx-compose") // if you use Compose
}
```

To use the Compiler Plugin DSL or annotations, also apply the [Koin Compiler Plugin](/docs/setup/compiler-plugin). It runs inside the Kotlin compiler and replaces kapt or KSP for Koin. The full list of artifacts is in [Gradle Setup](/docs/setup/gradle).

## Step 2: Application class

Hilt:

```kotlin
@HiltAndroidApp
class MyApplication : Application()
```

Koin:

**Compiler Plugin DSL**
```kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidLogger()
            androidContext(this@MyApplication)
            modules(appModule)
        }
    }
}
```

**Annotations**
```kotlin
import org.koin.plugin.module.dsl.startKoin

@KoinApplication
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin<MyApplication> {
            androidLogger()
            androidContext(this@MyApplication)
        }
    }
}
```

`@KoinApplication` loads every module tagged `@Configuration`. To list modules explicitly, use `@KoinApplication(modules = [AppModule::class])`.

**Constructor / Classic DSL**
```kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidLogger()
            androidContext(this@MyApplication)
            modules(appModule)
        }
    }
}
```

`androidContext()` makes the `Context` available to every definition. See [Starting Koin on Android](/docs/reference/koin-android/start).

## Step 3: Modules and @Provides

Hilt:

```kotlin
@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {

    @Provides
    @Singleton
    fun provideOkHttpClient(): OkHttpClient = OkHttpClient.Builder().build()

    @Provides
    @Singleton
    fun provideApiService(client: OkHttpClient): ApiService =
        Retrofit.Builder()
            .baseUrl("https://api.example.com")
            .client(client)
            .build()
            .create(ApiService::class.java)
}
```

Koin:

**Compiler Plugin DSL**
```kotlin
import org.koin.plugin.module.dsl.create

fun okHttpClient(): OkHttpClient = OkHttpClient.Builder().build()

fun apiService(client: OkHttpClient): ApiService =
    Retrofit.Builder()
        .baseUrl("https://api.example.com")
        .client(client)
        .build()
        .create(ApiService::class.java)

val networkModule = module {
    single { create(::okHttpClient) }
    single { create(::apiService) }
}
```

**Annotations**
```kotlin
@Module
class NetworkModule {

    @Singleton
    fun okHttpClient(): OkHttpClient = OkHttpClient.Builder().build()

    @Singleton
    fun apiService(client: OkHttpClient): ApiService =
        Retrofit.Builder()
            .baseUrl("https://api.example.com")
            .client(client)
            .build()
            .create(ApiService::class.java)
}
```

**Constructor / Classic DSL**
```kotlin
val networkModule = module {
    single { OkHttpClient.Builder().build() }
    single {
        Retrofit.Builder()
            .baseUrl("https://api.example.com")
            .client(get())
            .build()
            .create(ApiService::class.java)
    }
}
```

There is no `@InstallIn`: a definition's lifetime comes from its type (`single`, `factory`, `scoped`), not from the component it is installed in. Classes with an `@Inject constructor` become `single<T>()` / `factory<T>()`, an annotation on the class, or `singleOf(::T)`. More on library objects in [Definitions](/docs/reference/koin-core/definitions#classes-you-dont-own).

## Step 4: Interface bindings

Hilt:

```kotlin
@Module
@InstallIn(SingletonComponent::class)
abstract class DataModule {
    @Binds
    @Singleton
    abstract fun bindUserRepository(impl: UserRepositoryImpl): UserRepository
}
```

Koin:

**Compiler Plugin DSL**
```kotlin
val dataModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class
}
```

**Annotations**
```kotlin
@Singleton
class UserRepositoryImpl(private val api: ApiService) : UserRepository
```

The class is bound to all its supertypes. To bind only some, use `@Singleton(binds = [UserRepository::class])`.

**Constructor / Classic DSL**
```kotlin
val dataModule = module {
    singleOf(::UserRepositoryImpl) bind UserRepository::class
}
```

## Step 5: ViewModels

Hilt:

```kotlin
@HiltViewModel
class UserViewModel @Inject constructor(
    private val repository: UserRepository,
    private val savedStateHandle: SavedStateHandle,
) : ViewModel()
```

Koin:

**Compiler Plugin DSL**
```kotlin
class UserViewModel(
    private val repository: UserRepository,
    private val savedStateHandle: SavedStateHandle,
) : ViewModel()

val appModule = module {
    viewModel<UserViewModel>()
}
```

**Annotations**
```kotlin
@KoinViewModel
class UserViewModel(
    private val repository: UserRepository,
    private val savedStateHandle: SavedStateHandle,
) : ViewModel()
```

**Constructor / Classic DSL**
```kotlin
class UserViewModel(
    private val repository: UserRepository,
    private val savedStateHandle: SavedStateHandle,
) : ViewModel()

val appModule = module {
    viewModelOf(::UserViewModel)
}
```

Koin provides `SavedStateHandle` to ViewModel definitions. In an Activity or Fragment, replace `by viewModels()` with `by viewModel()`. In Compose, replace `hiltViewModel()` with `koinViewModel()`. See [Android ViewModel](/docs/reference/koin-android/viewmodel).

## Step 6: Activities, Fragments and other entry points

Hilt:

```kotlin
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
    @Inject lateinit var analytics: Analytics
}
```

Koin:

```kotlin
class MainActivity : ComponentActivity() {
    private val analytics: Analytics by inject()
}
```

Remove `@AndroidEntryPoint`. In Activities, Fragments and other Android components, which the framework creates, fields with `@Inject lateinit var` become `by inject()` (lazy) or `get()` (immediate). This is the same in every style. Services, BroadcastReceivers and other components are covered in [Entry Points](/docs/reference/koin-android/entry-points).

In your own classes (repositories, services, use cases, ViewModels), move `@Inject` fields to constructor parameters and declare the class as in [Step 3](#step-3-modules-and-provides). These classes never call `get()` or `by inject()`:

```kotlin
// Hilt: field injection in a class you own
class SyncService @Inject constructor() {
    @Inject lateinit var repository: UserRepository
}

// Koin: constructor injection
class SyncService(private val repository: UserRepository)
```

Hilt's `@EntryPoint` exists for framework classes Hilt can't inject, such as a `ContentProvider` or a library callback. Only at such an entry point, implement [KoinComponent](/docs/reference/koin-core/koin-component) and call `by inject()`. Do not use `KoinComponent` to replace `@Inject` fields in app classes.

## Step 7: Qualifiers

Hilt:

```kotlin
@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class IoDispatcher

@Provides
@IoDispatcher
fun provideIoDispatcher(): CoroutineDispatcher = Dispatchers.IO

class SyncRepository @Inject constructor(
    @IoDispatcher private val dispatcher: CoroutineDispatcher,
)
```

Koin:

**Compiler Plugin DSL**
```kotlin
import org.koin.core.annotation.Named

class SyncRepository(
    @Named("io") private val dispatcher: CoroutineDispatcher,
)

val dispatcherModule = module {
    single<CoroutineDispatcher>(named("io")) { Dispatchers.IO }
    single<SyncRepository>()
}
```

**Annotations**
Keep your qualifier annotation. Koin reads custom annotations marked with `@Qualifier` (Koin's, `jakarta.inject` or `javax.inject`):

```kotlin
import javax.inject.Qualifier

@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class IoDispatcher

@Module
class DispatcherModule {
    @Singleton
    @IoDispatcher
    fun ioDispatcher(): CoroutineDispatcher = Dispatchers.IO
}

@Singleton
class SyncRepository(
    @IoDispatcher private val dispatcher: CoroutineDispatcher,
)
```

**Constructor / Classic DSL**
```kotlin
val dispatcherModule = module {
    single<CoroutineDispatcher>(named("io")) { Dispatchers.IO }
    single { SyncRepository(get(named("io"))) }
}
```

Type qualifiers (`named<IoDispatcher>()`) and all other options are in [Qualifiers](/docs/reference/koin-core/qualifiers). Hilt's `@ApplicationContext` needs no qualifier: a `Context` parameter receives the context passed to `androidContext()`.

## Step 8: Compose

Hilt needs an entry point to reach a non-ViewModel dependency from a Composable. Koin resolves it directly:

```kotlin
@Composable
fun UserScreen(viewModel: UserViewModel = koinViewModel()) {
    val analytics: Analytics = koinInject()
}
```

See [Koin for Compose](/docs/reference/koin-compose/compose).

## Step 9: Tests

Hilt:

```kotlin
@HiltAndroidTest
class UserRepositoryTest {
    @get:Rule
    val hiltRule = HiltAndroidRule(this)

    @Inject lateinit var repository: UserRepository

    @Before
    fun init() = hiltRule.inject()
}
```

Koin:

```kotlin
class UserRepositoryTest : KoinTest {

    @get:Rule
    val koinTestRule = KoinTestRule.create {
        modules(appModule, testModule)
    }

    private val repository: UserRepository by inject()
}
```

Hilt's `@TestInstallIn` and `@UninstallModules` become a test module loaded after the production modules. Remove `HiltTestApplication` and the Hilt test runner. See [Unit Testing](/docs/reference/koin-test/testing) and [Android Instrumented Testing](/docs/reference/koin-android/instrumented-testing).

## Migrate gradually with @Inject

With annotations, the Compiler Plugin reads JSR-330 annotations: in a package covered by `@ComponentScan`, a class with an `@Inject constructor` becomes a factory, and a class annotated with `@Singleton` (from `jakarta.inject` or `javax.inject`) a single. You can keep these classes unchanged and migrate Gradle module by Gradle module. See [JSR-330 Annotations](/docs/reference/koin-android/jsr330).

## Multi-module projects

Each Gradle module declares its own Koin module, and the app module loads them all in `startKoin`. There is no component hierarchy to configure and no `@EntryPoint` for cross-module access: a definition in `:feature:home` can use any definition loaded by the app.

With annotations, tag each feature module class with `@Module`, `@ComponentScan` and `@Configuration`. `@KoinApplication` in the app module finds them without listing them.

Module organization, visibility and feature modules are covered in [Multi-Module Apps](/docs/reference/koin-android/multi-module).

## Common patterns

### Assisted injection

Hilt's `@AssistedInject` and `@AssistedFactory` become injected parameters. The caller passes the runtime value:

**Compiler Plugin DSL**
```kotlin
class UserDetailViewModel(
    @InjectedParam private val userId: String,
    private val repository: UserRepository,
) : ViewModel()

val appModule = module {
    viewModel<UserDetailViewModel>()
}
```

**Annotations**
```kotlin
@KoinViewModel
class UserDetailViewModel(
    @InjectedParam private val userId: String,
    private val repository: UserRepository,
) : ViewModel()
```

**Constructor / Classic DSL**
```kotlin
class UserDetailViewModel(
    private val userId: String,
    private val repository: UserRepository,
) : ViewModel()

val appModule = module {
    viewModel { (userId: String) -> UserDetailViewModel(userId, get()) }
}
```

```kotlin
val viewModel: UserDetailViewModel by viewModel { parametersOf("user-42") }
```

See [Injected Parameters](/docs/reference/koin-core/injection-parameters).

### Lazy and Provider

- `dagger.Lazy<T>`: use a Kotlin `Lazy<T>` constructor parameter, or `by inject()` in an Android entry point (see [Injection](/docs/reference/koin-core/injection)).
- `Provider<T>`: to create a new instance on each call from a class you own, use the provider pattern in [Advanced Patterns](/docs/reference/koin-core/advanced-patterns).

### WorkManager

`@HiltWorker` workers become `worker` definitions, and `HiltWorkerFactory` becomes `workManagerFactory()` in `startKoin`. See [WorkManager](/docs/reference/koin-android/workmanager).

## Checklist

- [ ] Gradle: remove the Hilt plugin, `hilt-android` and `hilt-compiler`. Add Koin, and the Compiler Plugin if you use it. Remove kapt if nothing else needs it.
- [ ] Application: remove `@HiltAndroidApp`, start Koin in `onCreate()` with `androidContext()`.
- [ ] Modules: convert `@Module` / `@InstallIn` / `@Provides` / `@Binds` to Koin modules.
- [ ] ViewModels: remove `@HiltViewModel`, declare them, use `by viewModel()` / `koinViewModel()`.
- [ ] Entry points: remove `@AndroidEntryPoint`, use `by inject()` in Android components. Move `@Inject` fields of your own classes to constructor parameters. Replace `@EntryPoint` with `KoinComponent` only in framework classes Koin can't create.
- [ ] Qualifiers: keep custom `@Qualifier` annotations (annotations style) or switch to `named()`.
- [ ] Workers: replace `@HiltWorker` and `HiltWorkerFactory`.
- [ ] Tests: remove `@HiltAndroidTest`, `HiltAndroidRule` and the Hilt test runner, use `KoinTestRule`.
- [ ] Build: with the Compiler Plugin, a successful build means the graph is complete. Without it, add a [verify()](/docs/reference/koin-test/verify) test.
- [ ] Run: launch the app and the test suite.

## Troubleshooting

### NoDefinitionFoundException

Koin has no definition for the requested type. Check that the module declaring it is loaded in `startKoin` (or found by `@Configuration`), and that the requested type matches the declared or bound type. A class that only had `@Inject constructor` and was injected by Hilt needs a Koin definition too, unless a `@ComponentScan` picks it up through its JSR-330 annotations.

### Wrong instance with two definitions of the same type

With Hilt, a missing qualifier is a build error. With Koin, the last loaded definition wins, unless you start Koin with `allowOverride(false)`. Add a [qualifier](/docs/reference/koin-core/qualifiers) to both definitions and to the injection points.

### Circular dependency

Two classes depend on each other. Refactor to break the cycle, or make one side lazy with a `Lazy<T>` parameter. The Compiler Plugin reports cycles at build time. More in [Troubleshooting](/docs/reference/koin-core/troubleshooting).

## Related

- [Koin vs Hilt](/docs/intro/koin-vs-hilt): how the two frameworks differ.
- [JSR-330 Annotations](/docs/reference/koin-android/jsr330): keep `@Inject` and `@Singleton` during the migration.
- [Starting Koin on Android](/docs/reference/koin-android/start): `startKoin`, `androidContext()` and logging.
- [Android Scopes](/docs/reference/koin-android/scope): Activity, Fragment and ViewModel scopes.
- [Unit Testing](/docs/reference/koin-test/testing): replace Hilt test rules.
- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): what the Compiler Plugin checks.

---

# JSR-330 Annotations

Source: https://insert-koin.io/docs/reference/koin-android/jsr330

The Koin Compiler Plugin reads the standard JSR-330 annotations from `jakarta.inject` and `javax.inject`. A class with `@Singleton` or an `@Inject constructor` becomes a Koin definition, with no Koin annotation on it. This page lists what is supported and how to set it up. It applies to the annotations style: you need the [Compiler Plugin](/docs/setup/compiler-plugin) and a module with `@ComponentScan` (see [Modules](/docs/reference/koin-core/modules)).

The main use is code shared with another JSR-330 framework, or a migration from Hilt or Dagger where you keep existing classes unchanged (see [Migrating from Hilt](/docs/reference/koin-android/hilt-migration)).

## Setup

On the JVM and Android, keep the JSR-330 artifact you already use:

```kotlin
dependencies {
    implementation("jakarta.inject:jakarta.inject-api:2.0.1")
    // or the legacy package
    implementation("javax.inject:javax.inject:1")
}
```

In Kotlin Multiplatform code, these Java artifacts are not available. Add `koin-jsr330`, which provides the `jakarta.inject` annotations for every Kotlin target:

```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.insert-koin:koin-jsr330:$koin_annotations_version")
        }
    }
}
```

:::note
`koin-jsr330` is published with Koin Annotations, not with the Koin BOM. Use the Koin Annotations version.
:::

## Supported annotations

| JSR-330 annotation | Koin equivalent | Applies to |
|--------------------|-----------------|------------|
| `@Singleton` | `@Singleton` / `@Single` | Class, function in a `@Module` |
| `@Inject` on a constructor | `@Factory` | Class |
| `@Named("x")` | `@Named("x")` | Class, function, parameter |
| `@Qualifier` | `@Qualifier` | Your own qualifier annotation class |

Both packages work: `jakarta.inject.*` and `javax.inject.*`. Koin annotations on the same class take precedence. For example `@KoinViewModel` on a class with an `@Inject constructor` declares a ViewModel, not a factory.

JSR-330 `@Scope` has no effect on Koin scopes. Use Koin's `@Scope` and `@Scoped`, or a scope archetype such as `@ActivityScope` (see [Scopes](/docs/reference/koin-core/scopes)).

## Definitions

`@Singleton` declares a single. A class with an `@Inject constructor` and no other annotation declares a factory:

```kotlin
import jakarta.inject.Inject
import jakarta.inject.Singleton

@Singleton
class UserRepository @Inject constructor(
    private val api: ApiService,
    private val database: UserDatabase,
)

// a new instance for each request
class GetUserUseCase @Inject constructor(
    private val repository: UserRepository,
)
```

`@Inject` is optional when the class has a `@Singleton` annotation: Koin uses the primary constructor. When a class has several constructors, Koin uses the one annotated with `@Inject`.

These classes must be in a package covered by `@ComponentScan`, like any annotated class:

```kotlin
@Module
@ComponentScan("com.example.data")
class DataModule
```

`@Singleton` also works on provider functions in a `@Module` class, for objects you build yourself:

```kotlin
@Module
class NetworkModule {

    @Singleton
    fun retrofit(): Retrofit = Retrofit.Builder()
        .baseUrl("https://api.example.com")
        .build()
}
```

Binding to supertypes works as with Koin annotations: the class is bound to its interfaces (see [Definitions](/docs/reference/koin-core/definitions#interface-binding)).

## Qualifiers

`@Named` works on the declaration and on the injection point:

```kotlin
import jakarta.inject.Inject
import jakarta.inject.Named
import jakarta.inject.Singleton

@Singleton
@Named("inMemory")
class InMemoryCache @Inject constructor() : Cache

@Singleton
@Named("disk")
class DiskCache @Inject constructor(private val context: Context) : Cache

@Singleton
class ImageLoader @Inject constructor(
    @Named("inMemory") private val memoryCache: Cache,
    @Named("disk") private val diskCache: Cache,
)
```

Custom qualifier annotations marked with JSR-330 `@Qualifier` work like Koin's custom qualifiers:

```kotlin
import jakarta.inject.Qualifier

@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class IoDispatcher

@Module
class DispatcherModule {

    @Singleton
    @IoDispatcher
    fun ioDispatcher(): CoroutineDispatcher = Dispatchers.IO
}

@Singleton
class SyncManager @Inject constructor(
    @IoDispatcher private val dispatcher: CoroutineDispatcher,
)
```

See [Qualifiers](/docs/reference/koin-core/qualifiers) for how qualifiers are resolved.

## Mixing with Koin annotations

You can use JSR-330 and Koin annotations in the same project, and on the same class:

```kotlin
@Singleton // jakarta.inject
@Named("local")
class LocalDatabase @Inject constructor() : Database

@Single // Koin
@Named("remote")
class RemoteDatabase(private val api: ApiService) : Database

@Factory // Koin, with a JSR-330 constructor
class DatabaseManager @Inject constructor(
    @Named("local") private val local: Database,
    @Named("remote") private val remote: Database,
)
```

JSR-330 has no annotation for ViewModels, workers or injected parameters. Use the Koin annotations for them: `@KoinViewModel`, `@KoinWorker`, `@InjectedParam`. A `Context` parameter needs no qualifier: Koin passes the context given to `androidContext()`.

```kotlin
@KoinViewModel
class UserViewModel @Inject constructor(
    private val repository: UserRepository,
    private val savedStateHandle: SavedStateHandle,
) : ViewModel()
```

## Limits

- Field and method injection: `@Inject lateinit var` fields and `@Inject` methods are not supported. Inject through the constructor, or use `by inject()` in Android components (see [Entry Points](/docs/reference/koin-android/entry-points)).
- `Provider<T>`: a `jakarta.inject.Provider<T>` parameter is not resolved. Use a `Lazy<T>` parameter, or the provider pattern in [Advanced Patterns](/docs/reference/koin-core/advanced-patterns).
- Annotations style only: `@Singleton` and `@Inject` declare definitions only through `@ComponentScan`. In a DSL module you still write `single<T>()`. The Compiler Plugin DSL then reads `@Named` on parameters and uses the `@Inject` constructor.
- Compile-time safety: JSR-330 definitions are checked by the Compiler Plugin like Koin annotations (see [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety)).

## Related

- [Migrating from Hilt](/docs/reference/koin-android/hilt-migration): step-by-step migration, where JSR-330 lets you keep existing classes.
- [Definitions](/docs/reference/koin-core/definitions): definition types and interface binding.
- [Qualifiers](/docs/reference/koin-core/qualifiers): named, type and custom qualifiers.
- [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): every Koin annotation.
- [Compiler Plugin Setup](/docs/setup/compiler-plugin): install the plugin.

---

# Migrating from KSP to the Compiler Plugin

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

This guide moves a Koin Annotations project from the KSP processor (`koin-ksp-compiler`) to the Koin Compiler Plugin. Your annotated classes stay the same: only the Gradle configuration, the way you start Koin, and a few imports change. For what the Compiler Plugin is and how it works, see [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin).

## What changes

| Aspect | KSP processor | Compiler Plugin |
|--------|---------------|-----------------|
| Processing | KSP, a separate step before compilation | Inside the Kotlin K2 compiler |
| Generated files | Visible in `build/generated/ksp` | None, code is generated in the compiler |
| KMP setup | One KSP configuration per target | One plugin for all targets |
| `koin-annotations` version | Separate version (`koin-ksp`) | Same version as `koin-core` |
| Starting Koin | `modules(AppModule().module)` | `startKoin<MyApp>()` |
| Compile-time checks | `KOIN_CONFIG_CHECK` option | On by default, full graph and call sites |
| Status | Deprecated | Active development |

## Requirements

- Kotlin 2.3.20 or later (K2 compiler).
- Gradle 8 or later.
- Koin 4.2 or later.

## Step 1: Update Kotlin

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

## Step 2: Update the version catalog

Before (KSP):

```toml
[versions]
koin = "4.0.0"
koin-ksp = "2.0.0"
ksp = "2.0.0-1.0.22"

[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin-ksp" }
koin-ksp-compiler = { module = "io.insert-koin:koin-ksp-compiler", version.ref = "koin-ksp" }

[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
```

After (Compiler Plugin):

```toml
[versions]
koin = "4.2.0"
koin-plugin = "1.2.1"

[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```

`koin-annotations` is now part of the main Koin project and uses the `koin-core` version. Check the latest plugin version in [Compiler Plugin Setup](/docs/setup/compiler-plugin).

## Step 3: Update the build configuration

Before (KSP):

```kotlin
plugins {
    alias(libs.plugins.ksp)
}

dependencies {
    implementation(libs.koin.core)
    implementation(libs.koin.annotations)
    ksp(libs.koin.ksp.compiler)
}

ksp {
    arg("KOIN_CONFIG_CHECK", "true")
}
```

After (Compiler Plugin):

```kotlin
plugins {
    alias(libs.plugins.koin.compiler)
}

dependencies {
    implementation(libs.koin.core)
    implementation(libs.koin.annotations)
}

// optional
koinCompiler {
    userLogs = true // log detected components
}
```

Remove the `ksp { }` block: compile-time checks are on by default. All plugin options are in [Compiler Plugin Options](/docs/reference/koin-annotations/options).

### Kotlin Multiplatform

With KSP, each target needs its own processor configuration:

```kotlin
dependencies {
    add("kspAndroid", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
    add("kspIosX64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
    add("kspIosArm64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
    add("kspIosSimulatorArm64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
}
```

With the Compiler Plugin, apply the plugin once in the shared module and remove all `ksp...` entries:

```kotlin
// shared/build.gradle.kts
plugins {
    kotlin("multiplatform")
    alias(libs.plugins.koin.compiler)
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.koin.core)
            implementation(libs.koin.annotations)
        }
    }
}
```

## Step 4: Update how Koin starts

KSP generates a `.module` extension for each `@Module` class. The Compiler Plugin has no such extension: you declare a `@KoinApplication` class and start it with a typed API.

Before (KSP):

```kotlin
import org.koin.ksp.generated.*

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

fun main() {
    startKoin {
        modules(AppModule().module)
    }
}
```

After (Compiler Plugin):

```kotlin
import org.koin.plugin.module.dsl.startKoin

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

@KoinApplication(modules = [AppModule::class])
class MyApp

fun main() {
    startKoin<MyApp>()
}
```

On Android, pass the usual options in the lambda:

```kotlin
@KoinApplication(modules = [AppModule::class])
class MyApp

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin<MyApp> {
            androidContext(this@MyApplication)
        }
    }
}
```

The other typed APIs are `koinApplication<T>()`, `koinConfiguration<T>()` and `withConfiguration<T>()` inside an existing `startKoin { }` or test rule. To load a single module class, use `module<AppModule>()` inside a plain `startKoin { }`. See [Starting Koin](/docs/reference/koin-core/starting-koin).

## Step 5: Update imports

`@KoinViewModel` moved to the core annotation package:

```kotlin
// before (KSP)
import org.koin.android.annotation.KoinViewModel

// after (Compiler Plugin)
import org.koin.core.annotation.KoinViewModel
```

Remove every `import org.koin.ksp.generated.*`.

## Step 6: Clean and rebuild

Delete the files generated by KSP, then rebuild:

```bash
rm -rf build/generated/ksp
./gradlew clean build
```

The first build runs the full compile-time check. A missing definition that KSP did not report now fails the build: see [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety) for the error messages and for `@Provided`.

## What stays the same

Your annotated classes don't change:

```kotlin
@Singleton
class UserRepository(private val database: Database)

@Factory
class GetUserUseCase(private val repository: UserRepository)

@KoinViewModel
class UserViewModel(private val useCase: GetUserUseCase) : ViewModel()
```

Every annotation is listed in the [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory).

## What you can use after migrating

These features need the Compiler Plugin:

- Top-level functions: `@Singleton fun database(): Database` is found by `@ComponentScan` like a class (see [Definitions](/docs/reference/koin-core/definitions#classes-you-dont-own)).
- Module discovery: modules tagged `@Configuration` in any Gradle module are loaded by `@KoinApplication` without listing them.
- Configuration labels: `@Configuration("test")` with `@KoinApplication(configurations = ["test"])` loads only the modules with that label (see [Modules](/docs/reference/koin-core/modules)).
- Compiler Plugin DSL: if you also have DSL modules, you can switch them to the Compiler Plugin DSL:

| Constructor / Classic DSL | Compiler Plugin DSL |
|---------------------------|---------------------|
| `singleOf(::MyService)` | `single<MyService>()` |
| `factoryOf(::MyRepository)` | `factory<MyRepository>()` |
| `viewModelOf(::MyViewModel)` | `viewModel<MyViewModel>()` |
| `scopedOf(::MyScoped)` | `scoped<MyScoped>()` |
| `workerOf(::MyWorker)` | `worker<MyWorker>()` |
| `single { build(get()) }` | `single { create(::build) }` |

The Compiler Plugin DSL is in `org.koin.plugin.module.dsl`. The Constructor DSL stays in `org.koin.core.module.dsl` and the Classic DSL in `org.koin.dsl`. Both keep working and are checked by the plugin: you don't have to migrate them.

## Troubleshooting

### The build fails after removing KSP

Stale generated code is still on the classpath. Run `./gradlew clean`, delete `build/generated/ksp`, invalidate the IDE caches, then rebuild.

### Annotated classes are not detected

Turn on plugin logs to see which classes are found:

```kotlin
koinCompiler {
    userLogs = true
}
```

Check that the packages in `@ComponentScan` match the packages of your classes.

### A dependency is missing at runtime

- Check that the module is listed in `@KoinApplication(modules = [...])`, or tagged `@Configuration`.
- Check the `@ComponentScan` packages.
- For a type created outside Koin, mark it `@Provided` (see [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety)).

## Checklist

- [ ] Update Kotlin to 2.3.20 or later
- [ ] Update Koin to 4.2.0 or later
- [ ] Remove the KSP plugin
- [ ] Remove the `koin-ksp-compiler` dependency and the `ksp { }` block
- [ ] Use the main Koin version for `koin-annotations` (`io.insert-koin:koin-annotations:$koin_version`)
- [ ] Apply the Koin Compiler Plugin (`io.insert-koin.compiler.plugin`)
- [ ] Change the `@KoinViewModel` import to `org.koin.core.annotation`
- [ ] Create a `@KoinApplication` class and replace `modules(X().module)` with `startKoin<MyApp>()`
- [ ] Remove `import org.koin.ksp.generated.*`
- [ ] Optional: switch DSL modules to `org.koin.plugin.module.dsl.*` and `single<X>()`
- [ ] Clean and rebuild (`rm -rf build/generated/ksp && ./gradlew clean build`)

## Related

- [Compiler Plugin Setup](/docs/setup/compiler-plugin): install the plugin and pick its version.
- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): what the plugin checks and its error codes.
- [Starting Koin](/docs/reference/koin-core/starting-koin): `startKoin<T>()` and the other typed APIs.
- [Compiler Plugin Options](/docs/reference/koin-annotations/options): every Gradle option.
- [KSP Processor Setup](/docs/setup/annotations-ksp): the deprecated KSP setup, for reference.

---

# DSL Reference

Source: https://insert-koin.io/docs/reference/koin-core/dsl

This page lists every Koin DSL keyword in tables, with the package to import and a link to the page that explains it. It covers the three DSL forms: the Compiler Plugin DSL, the Constructor DSL (constructor references) and the Classic DSL (lambdas). For annotations, see the [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory).

## DSL styles

| Style | Example | Import |
|-------|---------|--------|
| Compiler Plugin DSL | `single<UserRepository>()` | `org.koin.plugin.module.dsl.*` |
| Constructor DSL | `singleOf(::UserRepository)` | `org.koin.core.module.dsl.*` |
| Classic DSL | `single { UserRepository(get()) }` | `org.koin.dsl.*` |

The Compiler Plugin DSL needs the [Koin Compiler Plugin](/docs/setup/compiler-plugin). The plugin reads the constructor, generates the `get()` calls and checks the graph at build time. Without the plugin, a call such as `single<T>()` throws at runtime: `Error while using 'single<T>()'. The Koin Compiler plugin is missing. Please fix your setup to use 'io.insert-koin.compiler.plugin' Koin Gradle Plugin.`

The constructor-reference form (`singleOf(::T)`) is also checked by the Compiler Plugin when it is applied. A hand-written lambda is not: the plugin tracks the type it provides, not what the lambda body does. To pick a style, see [Choosing your style](/docs/intro/choosing-your-style).

## Application DSL

Functions that create and start a Koin container. See [Starting Koin](/docs/reference/koin-core/starting-koin).

| Function | Package | What it does |
|----------|---------|--------------|
| `startKoin { }` | `org.koin.core.context` | Creates a `KoinApplication` and registers it in the global context. Throws `KoinApplicationAlreadyStartedException` if one is already started |
| `startKoin<T>()` | `org.koin.plugin.module.dsl` | Compiler Plugin: starts Koin with the modules of the `@KoinApplication` class `T` |
| `koinApplication { }` | `org.koin.dsl` | Creates a standalone `KoinApplication`, not registered globally. See [Context Isolation](/docs/reference/koin-core/context-isolation) |
| `koinApplication<T>()` | `org.koin.plugin.module.dsl` | Compiler Plugin: standalone application with the modules of `T` |
| `koinConfiguration { }` | `org.koin.dsl` | Declares a reusable `KoinConfiguration` without starting Koin |
| `koinConfiguration<T>()` | `org.koin.plugin.module.dsl` | Compiler Plugin: configuration with the modules of `T` |
| `stopKoin()` | `org.koin.core.context` | Closes the global container and all its instances |
| `loadKoinModules(module)` | `org.koin.core.context` | Loads modules into the started global container |
| `unloadKoinModules(module)` | `org.koin.core.context` | Unloads modules and drops their instances |

### Inside `startKoin { }` and `koinApplication { }`

| Function | What it does |
|----------|--------------|
| `modules(...)` | Loads modules: one `Module`, a vararg or a `List<Module>` |
| `modules(UserModule::class, ...)` | Compiler Plugin: loads the modules generated from `@Module` classes |
| `module<UserModule>()` | Compiler Plugin: loads the module generated from one `@Module` class |
| `withConfiguration<T>()` | Compiler Plugin: adds the modules of `@KoinApplication` class `T` to an existing application |
| `includes(configuration)` | Applies one or more `KoinConfiguration` or `KoinAppDeclaration` blocks |
| `printLogger(level)` | Logs to standard output. Default level `Level.INFO` |
| `logger(logger)` | Uses your own `Logger` implementation. The default is `EmptyLogger` (no output) |
| `properties(map)` | Loads properties from a `Map<String, Any>` |
| `fileProperties(fileName)` | JVM only. Loads properties from a file, default `/koin.properties` |
| `environmentProperties()` | JVM only. Loads system properties and environment variables |
| `allowOverride(Boolean)` | Allows or forbids definition override. Default `true`. See [Definitions](/docs/reference/koin-core/definitions#overriding-a-definition) |
| `createEagerInstances()` | Creates `createdAtStart` definitions. `startKoin` and `koinApplication` already call it |
| `options(...)` | Sets Koin options, such as `viewModelScopeFactory()`. See [ViewModel](/docs/reference/koin-core/viewmodel) |
| `lazyModules(...)` | Loads lazy modules in the background (`koin-core-coroutines`). See [Lazy Modules](/docs/reference/koin-core/lazy-modules) |

`modules(A::class)`, `module<T>()` and `withConfiguration<T>()` go in a plain `startKoin { }` or `koinApplication { }`, not inside `startKoin<T> { }`.

Platform extensions add more functions to this block:

| Function | Artifact | See |
|----------|----------|-----|
| `androidContext(context)`, `androidLogger(level)`, `androidFileProperties()` | `koin-android` | [Android Start](/docs/reference/koin-android/start) |
| `fragmentFactory()` | `koin-android` | [Fragment Factory](/docs/reference/koin-android/fragment-factory) |
| `workManagerFactory()` | `koin-androidx-workmanager` | [WorkManager](/docs/reference/koin-android/workmanager) |
| `slf4jLogger(level)` | `koin-logger-slf4j` | [Ktor](/docs/reference/koin-ktor/ktor) |

## Module DSL

See [Modules](/docs/reference/koin-core/modules) and [Lazy Modules](/docs/reference/koin-core/lazy-modules).

| Function | Package | What it does |
|----------|---------|--------------|
| `module { }` | `org.koin.dsl` | Declares a module |
| `module(createdAtStart = true) { }` | `org.koin.dsl` | Every `single` of the module is created at start |
| `lazyModule { }` | `org.koin.dsl` | Declares a module loaded later, in the background (`koin-core-coroutines`) |
| `includes(otherModule, ...)` | `org.koin.dsl` | Includes other modules, as vararg or `Collection<Module>` |
| `moduleA + moduleB` | `org.koin.dsl` | Builds a `List<Module>` |

## Definitions

What each keyword creates is explained in [Definitions](/docs/reference/koin-core/definitions).

| Definition | Compiler Plugin DSL | Constructor DSL | Classic DSL |
|------------|---------------------|-----------------|-------------|
| Single | `single<T>()` | `singleOf(::T)` | `single { T(get()) }` |
| Factory | `factory<T>()` | `factoryOf(::T)` | `factory { T(get()) }` |
| Scoped (in a scope block) | `scoped<T>()` | `scopedOf(::T)` | `scoped { T(get()) }` |
| ViewModel | `viewModel<T>()` | `viewModelOf(::T)` | `viewModel { T(get()) }` |
| Worker (Android) | `worker<T>()` | `workerOf(::T)` | `worker { T(get(), get()) }` |
| Fragment (Android) | Not available | `fragmentOf(::T)` | `fragment { T(get()) }` |
| Function or builder | `single { create(::buildT) }` | `singleOf(::buildT)` | `single { buildT(get()) }` |

Packages:

| Keywords | Compiler Plugin DSL | Constructor / Classic DSL |
|----------|---------------------|---------------------------|
| `single`, `factory`, `scoped`, `create` | `org.koin.plugin.module.dsl` | `org.koin.dsl` (lambda), `org.koin.core.module.dsl` (`singleOf`, `factoryOf`, `scopedOf`, `new`) |
| `viewModel`, `viewModelOf` (artifact `koin-core-viewmodel`) | `org.koin.plugin.module.dsl` | `org.koin.core.module.dsl` |
| `worker`, `workerOf` (artifact `koin-androidx-workmanager`) | `org.koin.plugin.module.dsl` | `org.koin.androidx.workmanager.dsl` |
| `fragment`, `fragmentOf` (artifact `koin-android`) | | `org.koin.androidx.fragment.dsl` |

`viewModel` and `viewModelOf` in `org.koin.androidx.viewmodel.dsl` and `org.koin.compose.viewmodel.dsl` are deprecated: import them from `org.koin.core.module.dsl`.

`create(::buildT)` must be the only instruction in its lambda. Otherwise the Compiler Plugin reports `create(::buildT) must be the only instruction in the lambda.` See [Definitions](/docs/reference/koin-core/definitions#classes-you-dont-own).

### Lambda parameters

The lambda definitions have this signature:

| Keyword | Parameters |
|---------|------------|
| `single(qualifier, createdAtStart) { }` | `qualifier: Qualifier? = null`, `createdAtStart: Boolean = false` |
| `factory(qualifier) { }` | `qualifier: Qualifier? = null` |
| `scoped(qualifier) { }` | `qualifier: Qualifier? = null` |
| `viewModel(qualifier) { }` | `qualifier: Qualifier? = null` |
| `worker(qualifier) { }` | `qualifier: Qualifier = named<T>()` |

### Inside a definition lambda

The lambda runs with a `Scope` receiver and a `ParametersHolder` argument (`params`):

| Function | Returns | See |
|----------|---------|-----|
| `get<T>()`, `get<T>(qualifier)` | The instance. Throws `NoDefinitionFoundException` if missing | [Injection](/docs/reference/koin-core/injection) |
| `getOrNull<T>()` | The instance or `null` | [Injection](/docs/reference/koin-core/injection) |
| `inject<T>()` | `Lazy<T>` | [Injection](/docs/reference/koin-core/injection) |
| `getAll<T>()` | All instances bound to `T` | [Advanced Patterns](/docs/reference/koin-core/advanced-patterns#collections-of-dependencies) |
| `getProperty(key)`, `getProperty(key, default)`, `getPropertyOrNull(key)` | A Koin property | [Starting Koin](/docs/reference/koin-core/starting-koin) |
| `params.get<T>()`, `(id) -> ...` destructuring | An injected parameter | [Injected Parameters](/docs/reference/koin-core/injection-parameters) |
| `new(::T)` | A new `T` with every constructor parameter resolved by `get()` | |
| `create(::T)` | Compiler Plugin: the same, with build-time checks | [Definitions](/docs/reference/koin-core/definitions#classes-you-dont-own) |
| `getSource<T>()` | The scope source object | [Scopes](/docs/reference/koin-core/scopes) |
| `androidContext()`, `androidApplication()` | The Android `Context` or `Application` | [Android Start](/docs/reference/koin-android/start) |

## Definition options

Options apply after a definition, with an infix operator or in a `withOptions { }` block. They work on every definition keyword.

| Option | Form | What it does | See |
|--------|------|--------------|-----|
| `bind` | `single<T>() bind I::class` | Adds a secondary type | [Definitions](/docs/reference/koin-core/definitions#interface-binding) |
| `binds` | `single<T>() binds arrayOf(I::class, J::class)` | Adds several secondary types | [Definitions](/docs/reference/koin-core/definitions#interface-binding) |
| `onClose` | `single<T>() onClose { it?.close() }` | Callback when the instance is released | [Definitions](/docs/reference/koin-core/definitions#release-callback) |
| `withOptions { }` | `single<T>() withOptions { ... }` | Opens the option block below | |
| `.override()` | `single<T> { ... }.override()` | Marks an allowed override when `allowOverride(false)` is set | [Definitions](/docs/reference/koin-core/definitions#overriding-a-definition) |

In `withOptions { }`, or in the trailing block of `singleOf(::T) { }`, `factoryOf`, `scopedOf` and `viewModelOf`:

| Option | What it does |
|--------|--------------|
| `named("name")` | String qualifier. See [Qualifiers](/docs/reference/koin-core/qualifiers) |
| `named<Type>()` | Type qualifier |
| `bind<I>()` | Adds a secondary type |
| `binds(listOf(I::class, J::class))` | Adds several secondary types |
| `createdAtStart()` | Creates the `single` when Koin starts |
| `onClose { }` | Release callback |

```kotlin
val appModule = module {
    single<UserRepositoryImpl>() withOptions {
        named("local")
        bind<UserRepository>()
        createdAtStart()
    }

    // Constructor DSL
    singleOf(::UserRepositoryImpl) {
        named("local")
        bind<UserRepository>()
    }
}
```

## Scope DSL

A scope block groups the definitions that live as long as a scope. See [Scopes](/docs/reference/koin-core/scopes).

| Function | Package | What it does |
|----------|---------|--------------|
| `scope<T> { }` | `Module` member | Scope identified by the type `T`, usually the type of the scope source |
| `scope(named("session")) { }` | `Module` member | Scope identified by a qualifier |

Inside a scope block:

| Definition | Compiler Plugin DSL | Constructor DSL | Classic DSL |
|------------|---------------------|-----------------|-------------|
| Scoped | `scoped<T>()` | `scopedOf(::T)` | `scoped { T(get()) }` |
| Factory | `factory<T>()` | `factoryOf(::T)` | `factory { T(get()) }` |
| ViewModel | `viewModel<T>()` | `viewModelOf(::T)` | `viewModel { T(get()) }` |
| Worker (Android) | `worker<T>()` | `workerOf(::T)` | `worker { T(get(), get()) }` |

```kotlin
val sessionModule = module {
    scope<UserSession> {
        scoped<SessionCache>()
        factory<SessionPresenter>()
    }
}
```

### Scope archetypes

An archetype is a scope block for a type of scope source rather than one class. Every source of that kind gets the definitions.

| Function | Artifact | Scope of | See |
|----------|----------|----------|-----|
| `viewModelScope { }` | `koin-core-viewmodel` | Each ViewModel | [ViewModel](/docs/reference/koin-core/viewmodel) |
| `activityScope { }` | `koin-android` | Each Activity | [Android Scopes](/docs/reference/koin-android/scope) |
| `activityRetainedScope { }` | `koin-android` | Each Activity, kept across configuration changes | [Android Scopes](/docs/reference/koin-android/scope) |
| `fragmentScope { }` | `koin-android` | Each Fragment | [Android Scopes](/docs/reference/koin-android/scope) |
| `navigationScope { }` | `koin-compose-viewmodel-navigation` | Each navigation destination (`NavBackStackEntry`) | [Compose Scopes](/docs/reference/koin-compose/compose-scopes) |
| `requestScope { }` | `koin-ktor` | Each Ktor call | [Ktor Scopes](/docs/reference/koin-ktor/ktor-scopes) |

## Related

- [Definitions](/docs/reference/koin-core/definitions): what each definition type does and when to use it.
- [Modules](/docs/reference/koin-core/modules): organize and compose modules.
- [Scopes](/docs/reference/koin-core/scopes): scope lifecycle, linking and closing.
- [Annotations Reference](/docs/reference/koin-annotations/annotations-inventory): the annotation equivalent of this page.
- [Compiler Plugin Setup](/docs/setup/compiler-plugin): install the plugin that the Compiler Plugin DSL needs.

---

# Annotations Reference

Source: https://insert-koin.io/docs/reference/koin-annotations/annotations-inventory

This page lists every Koin annotation, with its package, where it can be placed, its parameters, and one example. Each entry links to the page that explains the concept. To set up annotations, see [Compiler Plugin Setup](/docs/setup/compiler-plugin). To compare annotations with the DSL, see [Choosing your style](/docs/intro/choosing-your-style).

The annotations come from the `io.insert-koin:koin-annotations` artifact (same version as Koin). The Koin Compiler Plugin reads them at build time and generates the definitions. Most live in `org.koin.core.annotation`, Android-only ones in `org.koin.android.annotation`.

## At a glance

| Annotation | Package | Declares |
|------------|---------|----------|
| [`@Singleton` / `@Single`](#singleton--single) | `org.koin.core.annotation` | A `single` definition |
| [`@Factory`](#factory) | `org.koin.core.annotation` | A `factory` definition |
| [`@Scoped`](#scoped) | `org.koin.core.annotation` | A `scoped` definition |
| [`@KoinViewModel`](#koinviewmodel) | `org.koin.core.annotation` | A `viewModel` definition |
| [`@KoinWorker`](#koinworker) | `org.koin.android.annotation` | A WorkManager `worker` definition |
| [`@Scope`](#scope) | `org.koin.core.annotation` | The scope a definition belongs to |
| [`@ViewModelScope`](#viewmodelscope) | `org.koin.core.annotation` | A definition in the ViewModel scope |
| [`@ActivityScope`](#activityscope) | `org.koin.android.annotation` | A definition in the Activity scope |
| [`@ActivityRetainedScope`](#activityretainedscope) | `org.koin.android.annotation` | A definition in the retained Activity scope |
| [`@FragmentScope`](#fragmentscope) | `org.koin.android.annotation` | A definition in the Fragment scope |
| [`@ScopeId`](#scopeid) | `org.koin.core.annotation` | A parameter resolved from a given scope |
| [`@Named`](#named) | `org.koin.core.annotation` | A string qualifier |
| [`@Qualifier`](#qualifier) | `org.koin.core.annotation` | A type or string qualifier |
| [`@InjectedParam`](#injectedparam) | `org.koin.core.annotation` | A parameter passed by the caller |
| [`@Property`](#property) | `org.koin.core.annotation` | A parameter read from a Koin property |
| [`@PropertyValue`](#propertyvalue) | `org.koin.core.annotation` | A default value for a property |
| [`@Provided`](#provided) | `org.koin.core.annotation` | A type provided outside the checked graph |
| [`@Module`](#module) | `org.koin.core.annotation` | A module class |
| [`@ComponentScan`](#componentscan) | `org.koin.core.annotation` | Packages to scan for definitions |
| [`@Configuration`](#configuration) | `org.koin.core.annotation` | Configuration labels for a module |
| [`@KoinApplication`](#koinapplication) | `org.koin.core.annotation` | The application entry point |
| [`@Monitor`](#monitor) | `org.koin.core.annotation` | Functions traced by the Kotzilla SDK |

## Definitions

A definition annotation goes on a class (Koin calls its constructor) or on a function (Koin calls the function, top-level or inside a `@Module` class). Constructor and function parameters are resolved from the container. How each parameter type is resolved: [Definitions](/docs/reference/koin-core/definitions#constructor-parameters).

When `binds` is empty, the definition is bound to its class and all its supertypes. List types in `binds` to bind only those.

### @Singleton / @Single

Target: `CLASS`, `FUNCTION`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `binds` | `Array<KClass<*>>` | `[]` | Types to bind. Empty binds all supertypes |
| `createdAtStart` | `Boolean` | `false` | Create the instance when Koin starts |

```kotlin
@Singleton(binds = [UserRepository::class])
class UserRepositoryImpl(private val api: ApiService) : UserRepository
```

`@Singleton` and `@Single` are equivalent; prefer `@Singleton`, the JSR-330 name. One instance is kept for the lifetime of the container. Concept: [Definitions](/docs/reference/koin-core/definitions).

### @Factory

Target: `CLASS`, `FUNCTION`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `binds` | `Array<KClass<*>>` | `[]` | Types to bind. Empty binds all supertypes |

```kotlin
@Factory
class UserPresenter(private val repository: UserRepository)
```

A new instance is created for each request. Concept: [Definitions](/docs/reference/koin-core/definitions).

### @Scoped

Target: `CLASS`, `FUNCTION`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `binds` | `Array<KClass<*>>` | `[]` | Types to bind. Empty binds all supertypes |

```kotlin
@Scope(UserSession::class)
@Scoped
class SessionCache(private val repository: UserRepository)
```

One instance per scope, released when the scope closes. Use it with `@Scope` or a scope archetype (`@ViewModelScope`, `@ActivityScope`, ...). Concept: [Scopes](/docs/reference/koin-core/scopes).

### @KoinViewModel

Target: `CLASS`, `FUNCTION`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `binds` | `Array<KClass<*>>` | `[]` | Types to bind. Empty binds all supertypes |

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

Works on Android and Compose Multiplatform targets. Requires `io.insert-koin:koin-core-viewmodel` on the classpath (the build fails with `KOIN-A001` otherwise). Concept: [ViewModel](/docs/reference/koin-core/viewmodel).

:::note
With the Compiler Plugin, `@KoinViewModel` is in `org.koin.core.annotation`. The KSP processor used `org.koin.android.annotation.KoinViewModel`: update the import when you migrate (see [Migrating from KSP](/docs/migration/from-ksp-to-compiler-plugin)).
:::

### @KoinWorker

Package: `org.koin.android.annotation` (Android only). Target: `CLASS`, `FUNCTION`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `binds` | `Array<KClass<*>>` | `[]` | Types to bind |

```kotlin
@KoinWorker
class SyncWorker(
    context: Context,
    params: WorkerParameters,
    private val repository: UserRepository,
) : CoroutineWorker(context, params)
```

Requires `io.insert-koin:koin-android-workmanager` (the build fails with `KOIN-A002` otherwise). Concept: [WorkManager](/docs/reference/koin-android/workmanager).

## Scopes

### @Scope

Target: `CLASS`, `FUNCTION`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `value` | `KClass<*>` | `Unit::class` | Scope type |
| `name` | `String` | `""` | Scope name, instead of a type |

```kotlin
@Scope(UserSession::class)
class SessionCache(private val repository: UserRepository)

@Scope(name = "checkout")
class CheckoutState
```

Puts the definition in the given scope. On its own, `@Scope` declares a `scoped` definition. Add `@Scoped`, `@Factory` or `@KoinViewModel` to choose another kind or to set `binds`. Concept: [Scopes](/docs/reference/koin-core/scopes).

### @ViewModelScope

Target: `CLASS`, `FUNCTION`. No parameters.

```kotlin
@ViewModelScope
class UserSessionCache(private val repository: UserRepository)
```

Declares a scoped definition in the scope of a ViewModel, created with the ViewModel and closed when it is cleared. Concept: [Scopes](/docs/reference/koin-core/scopes).

### @ActivityScope

Package: `org.koin.android.annotation` (Android only). Target: `CLASS`, `FUNCTION`. No parameters.

```kotlin
@ActivityScope
class ScreenTracker(private val analytics: Analytics)
```

Declares a scoped definition in the Activity scope. The Activity must provide that scope (see [Android Scopes](/docs/reference/koin-android/scope)).

### @ActivityRetainedScope

Package: `org.koin.android.annotation` (Android only). Target: `CLASS`, `FUNCTION`. No parameters.

```kotlin
@ActivityRetainedScope
class FormState
```

Declares a scoped definition in the retained Activity scope, which survives configuration changes. See [Android Scopes](/docs/reference/koin-android/scope).

### @FragmentScope

Package: `org.koin.android.annotation` (Android only). Target: `CLASS`, `FUNCTION`. No parameters.

```kotlin
@FragmentScope
class ListAdapterFactory
```

Declares a scoped definition in the Fragment scope. See [Android Scopes](/docs/reference/koin-android/scope).

### @ScopeId

Target: `VALUE_PARAMETER`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `value` | `KClass<*>` | `Unit::class` | Scope type. The scope ID is the class full name |
| `name` | `String` | `""` | Scope ID |

```kotlin
@Factory
class ProfileService(@ScopeId(name = "user_session") val session: UserSession)
```

Resolves the parameter from the scope with that ID instead of the current scope (generated as `getScope("user_session").get()`). Compile-time safety does not check it, since the scope exists only at runtime. Concept: [Scopes](/docs/reference/koin-core/scopes).

## Qualifiers

### @Named

Target: `CLASS`, `FUNCTION`, `VALUE_PARAMETER`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `value` | `String` | `""` | String qualifier |
| `type` | `KClass<*>` | `Unit::class` | Type qualifier. Use `@Qualifier(Type::class)` instead with the Compiler Plugin |

```kotlin
@Singleton
@Named("local")
class LocalDatabase : Database

@Singleton
class UserRepository(@Named("local") private val database: Database)
```

The same string on the definition and on the parameter links them. `jakarta.inject.Named` and `javax.inject.Named` are read the same way. Concept: [Qualifiers](/docs/reference/koin-core/qualifiers).

### @Qualifier

Target: `CLASS`, `FUNCTION`, `VALUE_PARAMETER`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `value` | `KClass<*>` | `Unit::class` | Type qualifier |
| `name` | `String` | `""` | String qualifier |

```kotlin
@Singleton
@Qualifier(Remote::class)
class RemoteDataSource : DataSource

@Singleton
class UserRepository(@Qualifier(Remote::class) private val source: DataSource)
```

`@Qualifier` also marks your own qualifier annotations. Every annotation class annotated with `@Qualifier` or `@Named` (or `jakarta.inject.Qualifier`, `javax.inject.Qualifier`) becomes a qualifier:

```kotlin
@Qualifier
annotation class IoDispatcher

@Singleton
@IoDispatcher
fun ioDispatcher(): CoroutineDispatcher = Dispatchers.IO
```

A custom qualifier with no argument is a type qualifier on the annotation class. With a string or enum argument (`@Dispatcher(AppDispatchers.IO)`), the argument value is the qualifier. Concept: [Qualifiers](/docs/reference/koin-core/qualifiers).

## Parameters

### @InjectedParam

Target: `VALUE_PARAMETER`. No parameters.

```kotlin
@Factory
class UserPresenter(@InjectedParam val userId: String, private val repository: UserRepository)

// caller
val presenter: UserPresenter = get { parametersOf("user-42") }
```

The value comes from `parametersOf(...)` at the call site, not from the container. Compile-time safety checks that call sites pass the right number and types of values (`KOIN-D005`, `KOIN-D006`). Concept: [Injected Parameters](/docs/reference/koin-core/injection-parameters).

### @Property

Target: `VALUE_PARAMETER`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `value` | `String` | required | Property key |

```kotlin
@Factory
class ApiClient(@Property("api_url") val url: String)
```

Resolves the parameter with `getProperty("api_url")`. If a `@PropertyValue` with the same key exists, it is the fallback value. Without one, the build shows warning `KOIN-P001` and the property must be set at startup. Concept: [Properties](/docs/reference/koin-core/starting-koin#properties).

### @PropertyValue

Target: `FIELD`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `value` | `String` | required | Property key |

```kotlin
@PropertyValue("api_url")
val defaultApiUrl = "https://api.example.com"

@Factory
class ApiClient(@Property("api_url") val url: String)
```

Declares the default value used when the property is not set (generated as `getProperty("api_url", defaultApiUrl)`).

### @Provided

Target: `CLASS`, `FUNCTION`, `VALUE_PARAMETER`. No parameters.

```kotlin
@Singleton
class AnalyticsService(@Provided val firebase: FirebaseAnalytics)
```

Tells compile-time safety that the type is available at runtime without a declaration it can see (platform object, SDK, module loaded later). On a class, every use of the type is skipped. On a parameter, only that parameter. Runtime resolution is unchanged. Common Android types (`Context`, `Activity`, `Fragment`, `SavedStateHandle`, `WorkerParameters`, ...) don't need it. Concept: [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety#external-types-provided).

## Modules and application

### @Module

Target: `CLASS`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `includes` | `Array<KClass<*>>` | `[]` | Other `@Module` classes to include |
| `createdAtStart` | `Boolean` | `false` | Create the module's `single` definitions when Koin starts |

```kotlin
@Module(includes = [NetworkModule::class])
class DataModule {

    @Singleton
    fun database(context: Context): AppDatabase =
        Room.databaseBuilder(context, AppDatabase::class.java, "app-db").build()
}
```

Groups definitions: annotated functions inside the class, plus annotated classes found by `@ComponentScan`. Concept: [Modules](/docs/reference/koin-core/modules).

### @ComponentScan

Target: `CLASS`, `FIELD`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `value` | `vararg String` | empty | Packages to scan. Empty scans the package of the annotated class |

```kotlin
@Module
@ComponentScan("com.myapp.data", "com.myapp.domain")
class AppModule
```

Adds to the module every annotated class and top-level function in the given packages and their subpackages, across Gradle modules. Concept: [Modules](/docs/reference/koin-core/modules).

:::note
The Compiler Plugin matches a package name and its subpackages. The glob patterns of the KSP processor (`com.example.**`, `com.*.service`) are not supported: list the packages instead.
:::

### @Configuration

Target: `CLASS`, `FIELD`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `value` | `vararg String` | empty | Configuration labels. Empty means `"default"` |

```kotlin
@Module
@ComponentScan
@Configuration
class CoreModule            // label "default"

@Module
@Configuration("default", "test")
class FakeDataModule        // labels "default" and "test"
```

A `@KoinApplication` loads every module that carries one of its configuration labels, including modules from other Gradle modules, without listing them. `@Configuration("default")` is the same as `@Configuration`. Concept: [Modules](/docs/reference/koin-core/modules).

### @KoinApplication

Target: `CLASS`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `configurations` | `Array<String>` | `[]` | Configuration labels to load. Empty loads `"default"` |
| `modules` | `Array<KClass<*>>` | `[Unit::class]` (none) | `@Module` classes to load in addition |

```kotlin
@KoinApplication(modules = [AppModule::class])
object MyApp

fun main() {
    startKoin<MyApp> {
        printLogger()
    }
}
```

Marks the entry point. Start it with `startKoin<MyApp>()`, `koinApplication<MyApp>()` or `koinConfiguration<MyApp>()` (package `org.koin.plugin.module.dsl`). This is where compile-time safety checks the full graph. Modules from `@Configuration` load first, then the `modules` list in its order, so the explicit list wins on overrides. Concept: [Starting Koin](/docs/reference/koin-core/starting-koin).

## Monitoring

### @Monitor

Target: `CLASS`, `FUNCTION`. No parameters.

```kotlin
@Monitor
class UserService(private val repository: UserRepository) {
    fun findUser(id: String): User? = repository.findById(id)
}
```

The Compiler Plugin wraps the function body (or every public function of the class) with a Kotzilla SDK trace. It requires the Kotzilla SDK (`io.kotzilla:kotzilla-core`) on the classpath. Without it, the build shows warning `KOIN-M001` and nothing is traced. Setup and data collected: [Monitor](/docs/tooling/monitor).

## JSR-330 annotations

The Compiler Plugin also reads `jakarta.inject` and `javax.inject` annotations: `@Singleton`, `@Named`, `@Inject` and `@Qualifier`. See [JSR-330](/docs/reference/koin-android/jsr330).

## Removed annotations

`@ExternalDefinition`, `@MetaDefinition`, `@MetaModule` and `@MetaApplication` (package `org.koin.meta.annotations`) were generated by the KSP processor for its own use. The Compiler Plugin does not use them, and you never write them by hand.

## Related

- [Definitions](/docs/reference/koin-core/definitions): definition types, binding, constructor parameters.
- [Modules](/docs/reference/koin-core/modules): `@Module`, `@ComponentScan` and `@Configuration` in practice.
- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): what the plugin checks from these annotations.
- [Compiler Plugin Options](/docs/reference/koin-annotations/options): Gradle options of the plugin.
- [DSL Reference](/docs/reference/koin-core/dsl): the DSL equivalent of each annotation.

---

# Compiler Plugin Options

Source: https://insert-koin.io/docs/reference/koin-annotations/options

This page lists every option of the Koin Compiler Plugin, set in the `koinCompiler { }` block of your `build.gradle.kts`. It assumes the plugin is installed (see [Compiler Plugin Setup](/docs/setup/compiler-plugin)). The options apply to the Compiler Plugin DSL and to annotations alike.

## All options

```kotlin
// build.gradle.kts
plugins {
    alias(libs.plugins.koin.compiler)
}

koinCompiler {
    compileSafety = true
    skipDefaultValues = true
    unsafeDslChecks = true
    userLogs = false
    debugLogs = false
}
```

| Option | Type | Default | Effect |
|--------|------|---------|--------|
| `compileSafety` | Boolean | `true` | Validates the dependency graph at build time |
| `strictSafety` | Boolean | Auto-detected | Re-runs the full-graph check on every build of the aggregator module |
| `strictSafetyForceOff` | Boolean | `false` | Confirms a wrong `strictSafety` auto-detection and turns it off |
| `skipDefaultValues` | Boolean | `true` | Uses Kotlin default values instead of resolving those parameters |
| `unsafeDslChecks` | Boolean | `true` | Requires `create()` to be the only instruction in its lambda |
| `userLogs` | Boolean | `false` | Logs the components the plugin detects |
| `debugLogs` | Boolean | `false` | Logs the plugin internals |
| `logSeverity` | String | `"warning"` | Severity of the plugin's informational output |
| `versionCheckSeverity` | String | `"warning"` | Severity of the Kotlin version compatibility warning |
| `aiAssist` | Boolean | `true` | Adds one help line at the end of a build that has Koin diagnostics |

## compileSafety

When enabled, the plugin checks at build time that every dependency in the graph can be resolved: missing definitions, qualifier mismatches, circular dependencies, and `get()` or `inject()` call sites with no matching definition. A problem fails the build instead of crashing at runtime.

```kotlin
koinCompiler {
    compileSafety = false
}
```

Keep it enabled. Turning it off removes every compile-time check and makes `strictSafety` have no effect. What gets checked is described in [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety).

## strictSafety

The full-graph check runs in the module that starts Koin (the aggregator: the Gradle module that contains `startKoin`, `koinApplication` or `@KoinApplication`). Kotlin incremental compilation can mark that module up to date when the graph changed elsewhere, for example after an edit inside a `module { }` lambda body. The check would then not run again, and the error would show up at runtime.

`strictSafety` makes the aggregator's `compileKotlin` task re-run on every build, with no build cache and no up-to-date skip. Library and feature modules stay incremental.

You don't need to set it. When the option is unset, the Gradle plugin scans the module sources for `startKoin`, `koinApplication` or `@KoinApplication` and turns it on for that module. A lifecycle log line announces the decision:

```
[Koin] Auto-enabling strictSafety on :app (detected startKoin / @KoinApplication / koinApplication).
```

Set `strictSafety = true` to force it on a module the detection misses:

```kotlin
koinCompiler {
    strictSafety = true
}
```

Setting `strictSafety = false` has no effect on a module where an entry point is detected (since Compiler Plugin 1.1.0). It only matters on modules without a detected entry point. The option has no effect when `compileSafety = false`.

The cost is one full recompilation of the aggregator module per build. Background on the incremental compilation gap is in [koin-compiler-plugin issue #32](https://github.com/InsertKoinIO/koin-compiler-plugin/issues/32).

## strictSafetyForceOff

The detection is a text match. It also matches `startKoin` in a comment or a string literal, and then turns `strictSafety` on for a module that is not an aggregator. If you have checked that the match is wrong, set both options:

```kotlin
koinCompiler {
    strictSafety = false
    strictSafetyForceOff = true
}
```

Both are needed: `strictSafetyForceOff` only applies together with `strictSafety = false`. Use it only on a confirmed misfire. On a real entry point it disables the re-run, and a graph error can then reach runtime after an incremental build.

## skipDefaultValues

When enabled, a non-nullable parameter with a Kotlin default value keeps its default and is not resolved from Koin:

```kotlin
@Singleton
class ApiClient(
    val repository: UserRepository,                         // resolved from Koin
    val timeout: Int = 30_000,                              // Kotlin default
    @Property("api_url") val url: String = "https://...",   // resolved, it is annotated
    val logger: Logger? = null,                             // resolved with getOrNull()
)
```

Nullable parameters are still resolved with `getOrNull()`. Parameters with `@Named`, `@Qualifier`, `@InjectedParam` or `@Property` are always resolved, whatever their default value. Set `skipDefaultValues = false` to resolve every parameter from Koin.

## unsafeDslChecks

When enabled, a `create(::T)` call must be the only instruction in its definition lambda. This keeps the lambda something the plugin can analyze and validate. A violation fails the build:

```
[Koin][KOIN-S001] create(::UserRepository) must be the only instruction in the lambda. Other statements are not allowed when using create(). To disable this check, set koinCompiler { unsafeDslChecks = false } in your build.gradle.kts
```

Set it to `false` while you migrate Classic DSL code that runs other statements inside a `create()` lambda, then turn it back on.

## userLogs and debugLogs

`userLogs = true` prints what the plugin detects and processes: DSL definitions it intercepts (`single<T>()`, `factory<T>()`), annotated classes (`@Singleton`, `@Module`) and the generated modules. Use it when a definition is not picked up.

`debugLogs = true` prints the plugin internals (FIR and IR phases, module discovery). Use it when you report a plugin bug.

Both print lines prefixed with `[Koin]` at the severity set by `logSeverity`.

## logSeverity and versionCheckSeverity

Both accept `"warning"` (default) or `"info"`.

```kotlin
koinCompiler {
    logSeverity = "info"
    versionCheckSeverity = "info"
}
```

- **logSeverity**: severity of informational output (`userLogs`, `debugLogs`, the "no Koin entry point" notice, `@Monitor` summaries). Set it to `"info"` if your build uses `allWarningsAsErrors`, so this output does not fail the build.
- **versionCheckSeverity**: severity of the warning shown when you build with a Kotlin version the plugin has not been verified against. It is separate so that muting log output does not also hide a compatibility risk. Set it to `"info"` only after you have checked that your Kotlin version works.

Neither option changes real diagnostics (`KOIN-D001`, `KOIN-W003` and so on): they keep their own severity.

## aiAssist

When a build reports at least one Koin diagnostic, the plugin adds one line at the end of the compilation, pointing to the Kotzilla MCP Server, which an AI coding assistant can use to classify the error and propose a fix:

```
[Koin] → Fix with AI: set up Kotzilla MCP at https://kotzilla.io/koin-mcp
```

The line appears once per build, not per error. Set `aiAssist = false` to hide it.

## Related

- [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety): what `compileSafety` checks and the diagnostics it reports.
- [Compiler Plugin Setup](/docs/setup/compiler-plugin): install the plugin and its dependencies.
- [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin): what the plugin does and how it works.
- [Troubleshooting](/docs/reference/koin-core/troubleshooting): runtime errors and debugging.

---

# Releases & Upgrade Guides

Source: https://insert-koin.io/docs/support/releases

This page lists every main Koin release, so you can plan an upgrade and check compatibility. Each version follows the same structure:

- **Kotlin**: the Kotlin version Koin is built with.
- **New**: new features and improvements.
- **Experimental**: APIs marked `@KoinExperimentalAPI`, which may still change.
- **Deprecated**: APIs marked for removal, with their replacement.
- **Breaking**: changes that need an update in your code when you upgrade.
- **Bug fixes**, **Improvements**, **Library updates**: present when the release has them.

What experimental and deprecated mean is defined in [API Stability](/docs/support/api-stability).

## Versions

| Version | Kotlin | Status | Main changes |
|---------|--------|--------|--------------|
| [4.2.2](#422) | 2.3.20 | Stable | Resolver regression fixes, ViewModel and scope fixes, tvOS, R8/ProGuard rules |
| [4.2.1](#421) | 2.3.20 | Previous stable | Scope resolution fixes, ABI restore, performance |
| [4.2.0](#420) | 2.3.20 | Previous stable | `@KoinApplication` and `@Configuration`, Ktor 3.4 DI bridge, Navigation 3, Dagger bridge |
| [4.1.1](#411) | 2.1.21 | Previous stable | Navigation improvements, resolver performance |
| [4.1.0](#410) | 2.1.20 | Previous stable | Scope archetypes, feature options, Ktor KMP |
| [4.0.4](#404) | 2.0.21 | Previous stable | Stable ViewModel API, UUID generation |
| [3.5.6](#356) | 1.9.22 | LTS | Long-term support line for Kotlin 1.x, isolated contexts |
| [3.4.3](#343) | 1.8.21 | Legacy | Verification API, ExtensionManager |

Current versions: Koin 4.2.2, and Koin Compiler Plugin 1.2.1 (see [Koin Compiler Plugin](#koin-compiler-plugin)).

:::note
Two LTS lines are maintained in parallel: Koin 3.5.6 for Kotlin 1.x projects and Koin 4.2.x for Kotlin 2.x projects. Pick the one that matches your Kotlin baseline. See [Long-Term Support](/docs/support/#long-term-support-lts) for the support policy.
:::

## 4.2.2

Kotlin `2.3.20`.

Maintenance release for the 4.2.x line: fixes for resolver regressions introduced by the `CoreResolverV2` rewrite in 4.2.0, ViewModel and scope fixes, a Ktor request scope fix, tvOS support and R8/ProGuard rules.

:::warning
If you hit resolver issues on 4.2.0 or 4.2.1, upgrade to 4.2.2.
:::

### New

`koin-core-viewmodel`
- tvOS targets (`tvosArm64`, `tvosX64`, `tvosSimulatorArm64`), so ViewModels can be used on tvOS.

`koin-android` / `koin-core-viewmodel`
- Consumer R8/ProGuard rules are now shipped in the AARs, with a new R8/ProGuard guide.

### Bug fixes

`koin-core`
- Fix #2370, #2408: stacked parameters (`parametersOf`) could shadow a qualified `get(named(...))` request. Qualified lookups now read only the registry, never the parameter stack.
- Fix #2379: a non-`single` factory defined in the root scope had its scoped dependencies resolved against `_root_` instead of the requesting scope, when resolved from a child scope. Linked-scope resolution now runs the factory against the requesting scope.
- Fix #2299: a scope created with `viewModelScopeFactory()` wasn't linked to its originating scope, so dependencies declared in the parent couldn't be resolved. The created scope is now linked to its parent (except when the parent is root).
- Fix #2348: loading environment or system properties with non-`String` values threw `ClassCastException` because of an unchecked map cast. Non-`String` values are now kept as `Any`.
- Fix #2044, #2417: resolving `SavedStateHandle` without the proper extras, or using `viewModelScope { }` without the `viewModelScopeFactory()` option, now gives an actionable error message.

`koin-ktor`
- Fix #2410: concurrent requests could collide on request scope ids. Ids are now generated from a monotonic counter seeded once at startup (contributed by @lfavreli-betclic).

### Improvements

`koin-core`
- `bind()` and `binds()` now append secondary types in O(1) instead of reallocating the type list for each binding. This removes a quadratic cost when a definition declares many bindings.

### Documentation

- Guidance on using Koin with the typed `entryProvider` in the [Navigation 3 reference](/docs/reference/koin-compose/navigation3) (#2336).

## 4.2.1

Kotlin `2.3.20`.

Patch release on top of 4.2.0: scope resolution fixes, ABI restoration and better diagnostics.

### New

`koin-core`
- Clearer scope resolution error messages.

### Bug fixes

`koin-core`
- Fix #2387: `CoreResolverV2` lost the stacked parameters lookup on linked scopes.
- ABI compatibility restored for `runOnKoinStarted`. An API check now runs in CI to prevent regressions.
- Concurrency fix on closed scopes (volatile flag), contributed by @inemtsev.
- Tests added for scoped `ViewModel` and `SavedStateHandle` ViewModels.

## 4.2.0

Kotlin `2.3.20`. All library versions are in [libs.versions.toml](https://github.com/InsertKoinIO/koin/blob/4.2.0/projects/gradle/libs.versions.toml).

### New

`koin-core`
- New `CoreResolverV2`: faster access to stacked parameters, child scope and ViewModel scope resolution, optimized `ThreadLocal` loading per scope.
- `KoinApplication.withConfiguration<T>()` extension: connects a `KoinApplication` with the modules discovered from a `@KoinApplication` class by the [Koin Compiler Plugin](#koin-compiler-plugin).
- `koinConfiguration<T>()` DSL: Compiler Plugin entry point to build a `KoinConfiguration` from an annotated class.
- Performance optimizations on scope resolution and thread safety.

`koin-android`
- `koinActivityInject`: retrieve a dependency from the current `Activity` scope.

`koin-androidx-startup`
- `onKoinStartup { }`: start Koin through the AndroidX Startup `Initializer` API.
- `KoinConfiguration` type and `KoinStartup` update (`KoinInitializer` stays experimental).

`koin-ktor`: Ktor 3.4 integration
- New Koin and Ktor DI bridge, built on the official Ktor 3.4 DI API.
- `KoinDependencyMap`: Koin resolves instances directly through Ktor DI.
- `KoinKtorApplication`: DSL bridge with explicit options for Ktor to Koin and Koin to Ktor wiring.
- `Application.koinModule` and `Application.koinModules` extensions are now the recommended way to declare modules.

`koin-compose-navigation3` (new module)
- Support for Jetpack Navigation 3 (stable 1.0.0).
- Generic `EntryProvider`: pass metadata parameters (animations and others) to navigation entries.
- Navigation scope helpers for Compose Navigation 2.

`koin-dagger-bridge` (new module)
- Inject Koin components from the Dagger side, for a gradual migration from Dagger to Koin.

`koin-core-annotations` (used by the Compiler Plugin)
- `@KoinApplication`: marks a class as the Koin application entry point. `startKoin<MyApp>()` then assembles all discovered `@Configuration` modules.
- `@Configuration("name")`: groups `@Module` classes into configurations (for example `prod`, `test`, `default`). Modules with the same configuration label see each other's definitions.
- `@PropertyValue("key")`: default value for a `@Property` injection.
- `@ScopeId(name = "...")` and `@ScopeId(MyScope::class)`: inject a value from a named Koin scope.
- `@Monitor`: wraps the annotated functions with Kotzilla SDK tracing (execution time). See [@Monitor](/docs/tooling/monitor).
- `@Provided` is recognized by the whole safety graph: it skips compile-time validation for types supplied from outside.

### Experimental

`koin-core`
- `@KoinApplication(modules = [...])`: an explicit `modules` array lets an entry point bypass discovery and use a fixed module list.

`koin-androidx-startup`
- The whole `koin-androidx-startup` API stays experimental. `KoinInitializer` is marked `@KoinExperimentalAPI`.

### Deprecated

`koin-android` / `koin-android-annotation`
- `org.koin.android.annotation.KoinViewModel` is deprecated. Use `org.koin.core.annotation.KoinViewModel`.

`koin-ktor`
- The `koin-ktor3` artifact is merged into `koin-ktor` (deprecated in 4.1.0, fully merged in 4.2.0).

### Breaking

`koin-android`
- Min SDK raised from 21 to 23, to align with the AndroidX libraries Koin uses.

`koin-compose-navigation3`
- Min API level 23.

`koin-core`
- `Module.getAll(...)` no longer sorts results. Instances come back in declaration order. If you rely on a specific order, sort explicitly.

## Koin Compiler Plugin

Current version: `1.2.1`. Requires Koin `4.2.0` or later and the Kotlin K2 compiler (verified on `2.3.20`, `2.4.0`, `2.4.10`, `2.4.20`).

The Koin Compiler Plugin is a native Kotlin compiler plugin. It replaces the KSP-based Koin Annotations processor and runs as part of Kotlin compilation, with no KSP step. Installation and Gradle options are on [Compiler Plugin Setup](/docs/setup/compiler-plugin) and [Compiler Plugin Options](/docs/reference/koin-annotations/options). What it validates is on [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety). It supports all Kotlin Multiplatform targets: JVM, JS, Wasm, iOS, macOS, watchOS, tvOS, Linux and Windows.

To migrate from `koin-ksp-compiler`, see [Migrating from KSP to the Compiler Plugin](/docs/migration/from-ksp-to-compiler-plugin).

### 1.2.1

Kotlin 2.4.20 support, plus two fixes found on real KMP apps.

- **Kotlin 2.4.20**: on 1.2.0, any project on Kotlin 2.4.20 failed with `NoSuchMethodError` during IR generation (#89, #99). Kotlin 2.4.20 removed or changed the signature of four compiler APIs the plugin used. All four are fixed.
- **KLIB fix**: wasmJs, JS and Kotlin/Native builds failed with `Different declarations with the same signatures were detected` on `componentscan_*` hints when a `@Configuration` module was relayed through a dependency. JVM and Android were not affected.
- **Qualifier fix**: two `@Named` providers of one type collapsed into one when read across modules, giving a false `KOIN-D001`. If you turned `compileSafety` off because of false D001 errors, check again with it on.
- **Strict Kotlin version check**: a Kotlin version now counts as verified only when that exact version was checked. Unverified versions warn and proceed, they never block.

See the [1.2.1 release notes](https://github.com/InsertKoinIO/koin-compiler-plugin/releases/tag/1.2.1).

### 1.2.0

Compile-time safety now covers the whole Koin DSL, and cross-module `includes` no longer hides definitions.

- **Constructor DSL validated**: `singleOf(::T)`, `factoryOf(::T)`, `scopedOf(::T)`, `viewModelOf(::T)` and `Scope.new(::T)` get the same missing-dependency and qualifier checks as `single<T>()`. Code that relied on an unchecked missing dependency here now fails to compile. This is the gap closing, not a regression.
- **New entry points**: `KoinApplication.withConfiguration<T>()` and Ktor's `install(Koin) { modules(...) }`.
- **Module lists**: `startKoin { modules(myList) }` resolves `listOf`, `+`, `.toList()` and functions returning `List<Module>`. Lists that branch at runtime stay unresolved, and `KOIN-W003` points at the call.
- **Module functions**: `fun myModule(): Module = module { ... }` is tracked like a top-level `val`.
- **Cross-module fixes**: definitions two or more `implementation` hops away were invisible through `@Module(includes)` (#82), `@Configuration` auto-discovery and DSL `includes(...)`. Plural `binds(...)` is now recognized, and `@Module(includes)` no longer merges providers that differ only by qualifier (#94).
- **Hand-written lambdas**: `single { X(get()) }` is validated through its own `get()` calls instead of guessing from the constructor. This removes false `KOIN-D004` cycles.

See the [1.2.0 release notes](https://github.com/InsertKoinIO/koin-compiler-plugin/releases/tag/1.2.0).

### 1.1.0

Full-graph validation only. Per-module validation is removed in favor of one full-graph check at each Koin entry point (`startKoin`, `koinApplication`, `@KoinApplication`). This removes real cross-module false positives. The tradeoff: a leaf or library module with no entry point of its own in its compilation gets no compile-time safety diagnostics until something assembles a real graph around it.

See the [1.1.0 release notes](https://github.com/InsertKoinIO/koin-compiler-plugin/releases/tag/1.1.0).

## 4.1.1

Kotlin `2.1.21`.

### New

`koin-compose-viewmodel-navigation`
- `sharedKoinViewModel` has an optional `navGraphRoute` parameter, for Compose Navigation.

`koin-core`
- Core resolver optimization: no unnecessary flattening when resolving in a single scope.
- Scope debugging shows linked scope ids.

### Library updates

- Kotlin: 2.1.21 (from 2.1.20)
- Ktor: 3.2.3 (from 3.1.3)
- JetBrains Compose: 1.8.2 (from 1.8.0)
- AndroidX: Fragment 1.8.9, WorkManager 2.10.3, Lifecycle 2.9.3, Navigation 2.9.3
- Testing: Robolectric 4.15.1, Benchmark 0.4.14
- Build: Binary Validator 0.18.1, NMCP 1.1.0

### Bug fixes

`koin-core`
- Reverted a logger constraint that caused compatibility errors.
- Fixed Compose scope resolution, with better `LocalKoinApplication` and `LocalKoinScope` context handling.

`koin-build`
- Fixed Maven Central publication issues.

## 4.1.0

Kotlin `2.1.20`.

### New

`koin-core`
- `KoinConfiguration` API, to wrap a Koin configuration.
- Scope archetypes: a dedicated scope type qualifier for a category of scope. Instances can now be resolved against a scope category (the archetype).
- Feature options: feature flags for new behaviors inside Koin. Activate an option in the `options` block of your Koin configuration:
```kotlin
startKoin {
    options(
        // activate a new feature
        viewModelScopeFactory()
    )
}
```
- New `CoreResolver`, with `ResolutionExtension` to let Koin resolve from external systems or resources (used to wire Ktor DI).

`koin-android`
- Upgraded libraries (`androidx.appcompat:appcompat:1.7.0`, `androidx.activity:activity-ktx:1.10.1`) raise the min SDK from 14 to 21.
- Module DSL extensions `activityScope`, `activityRetainedScope` and `fragmentScope`, to declare a scope for an Activity or a Fragment.
- The `activityScope()`, `activityRetainedScope()` and `fragmentScope()` functions now use scope archetypes.

`koin-androidx-compose`
- Aligned with Koin Compose Multiplatform, Compose 1.8 and Lifecycle 2.9.

`koin-compose`
- Aligned with Compose 1.8 and Lifecycle 2.9.
- `KoinApplicationPreview`, to render previews in parallel in Android Studio and IntelliJ IDEA.

`koin-compose-viewmodel`
- `koinActivityViewModel`, to use the parent Activity as the ViewModel host.

`koin-ktor`
- Multiplatform: the module is now built for Kotlin Multiplatform. You can use `koin-ktor` from a multiplatform project.
- The previous `koin-ktor3` module is merged into `koin-ktor`.
- `Application.koinModule { }` and `Application.koinModules()`, to declare Koin modules directly in a Ktor module:
```kotlin
fun Application.customerDataModule() {
    koinModule {
        singleOf(::CustomerRepositoryImpl) bind CustomerRepository::class
    }
}
```
- `Module.requestScope`: declare definitions inside a Ktor request scope, without declaring `scope<RequestScope>` by hand. The request scope can also inject `ApplicationCall` in a constructor.

`koin-core-coroutines`
- `ModuleConfiguration`: gather a module configuration in one structure, so it can be verified later.
```kotlin
val m1 = module {
    single { Simple.ComponentA() }
}
val lm1 = lazyModule {
    single { Simple.ComponentB(get()) }
}
val conf = moduleConfiguration {
    modules(m1)
    lazyModules(lm1)
}
```
- A Koin configuration can load modules from a `ModuleConfiguration`:
```kotlin
startKoin {
    moduleConfiguration {
        modules(m1)
        lazyModules(lm1)
    }
}

// or even
val conf = moduleConfiguration {
    modules(m1)
    lazyModules(lm1)
}

startKoin {
    moduleConfiguration(conf)
}
```

`koin-test-coroutines`
- New `koin-test-coroutines` module, for coroutines-related test APIs.
- The Verify API can check a `moduleConfiguration`, mixing modules and lazy modules:
```kotlin
val conf = moduleConfiguration {
    modules(m1)
    lazyModules(lm1)
}

conf.verify()

// if you want Android types (koin-android-test)
conf.verify(extraTypes = androidTypes)
```

`koin-core-annotations`
- `@InjectedParam` and `@Provided` mark a property as an injected parameter or as dynamically provided. Used by the `Verify` API for now.

### Experimental

`koin-core`
- Wasm: uses the Kotlin 2.1.20 UUID generation.

`koin-core-viewmodel`
- Module DSL extension `viewModelScope`, to declare components scoped to the ViewModel scope archetype.
- `viewModelScope()` function, to create a scope tied to a ViewModel class. It uses `ViewModelScopeAutoCloseable` (the `AutoCloseable` API) to close the scope, so you no longer close a ViewModel scope by hand.
- `ScopeViewModel` class updated: a ready-to-use ViewModel-scoped class that handles scope creation and closing.
- Constructor injection from the ViewModel's scope, with the `viewModelScopeFactory` option:
```kotlin
startKoin {
    options(
        // activate a new ViewModel scope creation
        viewModelScopeFactory()
    )
}

// will inject Session from MyScopeViewModel's scope
class MyScopeViewModel(val session: Session) : ViewModel()

module {
    viewModelOf(::MyScopeViewModel)
    viewModelScope {
        scopedOf(::Session)
    }
}
```

`koin-compose`
- `KoinMultiplatformApplication` function: a Compose Multiplatform entry point.

`koin-core-viewmodel-navigation`
- `sharedViewModel` extension, to reuse a ViewModel instance from the navigation `NavBackStackEntry`.

`koin-test`
- The `Verify` API now checks nullable, lazy and list parameters. Mark a property with `@InjectedParam` or `@Provided` to declare it as an injected parameter or as dynamically provided, instead of declaring it in the Verify call.
```kotlin
// now detected in Verify
class ComponentB(val a: ComponentA? = null)
class ComponentBParam(@InjectedParam val a: ComponentA)
class ComponentBProvided(@Provided val a: ComponentA)
```

### Deprecated

`koin-android`
- `ScopeViewModel` is deprecated. Use the `ScopeViewModel` class from `koin-core-viewmodel`.

`koin-compose`
- `KoinContext` is deprecated and can be removed: the Koin context is now prepared on the current default context.

`koin-androidx-compose`
- `KoinAndroidContext` is deprecated and can be removed: the Koin context is now prepared on the current default context.

`koin-androidx-compose-navigation`
- `koinNavViewModel` is no longer needed after the Lifecycle library update. Replace it with `koinViewModel`.

`koin-core-viewmodel-navigation`
- `koinNavViewModel` is no longer needed after the Lifecycle library update. Replace it with `koinViewModel`.

`koin-ktor`
- `Application.koin` is deprecated in favor of `Application.koinModules` and `Application.koinModule`.

### Breaking

`koin-android`
- The old state ViewModel APIs are removed:
  - `stateViewModel()`, `getStateViewModel()`: use `viewModel()`.
  - `getSharedStateViewModel()`, `sharedStateViewModel()`: use `viewModel()`, or `activityViewModel()` for a shared instance.

`koin-compose`
- Old Compose API functions are removed:
  - `inject()`: use `koinInject()`.
  - `getViewModel()`: use `koinViewModel()`.
  - `rememberKoinInject()`: merged into `koinInject()`.
- `rememberKoinApplication` is marked `@KoinInternalApi`.

## 4.0.4

Kotlin `2.0.21`.

All library versions are in [libs.versions.toml](https://github.com/InsertKoinIO/koin/blob/4.0.4/projects/gradle/libs.versions.toml).

### New

`koin-core`
- `KoinPlatformTools.generateId()` now uses the Kotlin `kotlin.uuid` API, and generates real UUIDs on all platforms.

`koin-viewmodel`
- Koin 4.0 introduces a ViewModel DSL and API shared across the Google and JetBrains KMP APIs. To avoid duplication, the ViewModel API now lives in `koin-core-viewmodel` and `koin-core-viewmodel-navigation`.
- The ViewModel DSL import is `org.koin.core.module.dsl.*`.

`koin-core-coroutines`: the whole API is now stable
- all `lazyModules`
- `awaitAllStartJobs`, `onKoinStarted`, `isAllStartedJobsDone`
- `waitAllStartJobs`, `runOnKoinStarted`
- `KoinApplication.coroutinesEngine`
- `Module.includes(lazy)`
- `lazyModule()`
- `KoinPlatformCoroutinesTools`

### Experimental

`koin-test`
- `ParameterTypeInjection`: declare dynamic parameter injection for the `Verify` API.

`koin-androidx-startup`
- Start Koin with AndroidX Startup, through the `androidx.startup.Initializer` API. The whole `koin-androidx-startup` API is experimental.

`koin-compose`
- `rememberKoinModules`: load and unload Koin modules with a `@Composable`.
- `rememberKoinScope`: load and unload a Koin scope with a `@Composable`.
- `KoinScope`: load a Koin scope for all child composables.

### Deprecated

`koin-test`
- The whole `checkModules` API. Migrate to the `Verify` API.

`koin-android`
- The Android ViewModel DSL, in favor of the shared DSL in `koin-core`.
- The state ViewModel APIs, at error level:
  - `stateViewModel()`, `getStateViewModel()`: use `viewModel()`.
  - `getSharedStateViewModel()`, `sharedStateViewModel()`: use `viewModel()`, or `activityViewModel()` for a shared instance.

`koin-compose`
- Old Compose API functions, at error level:
  - `inject()`: use `koinInject()`.
  - `getViewModel()`: use `koinViewModel()`.
  - `rememberKoinInject()`: use `koinInject()`.

`koin-compose-viewmodel`
- The ViewModel DSL, in favor of the shared DSL in `koin-core`.
- `koinNavViewModel`, in favor of `koinViewModel`.

### Breaking

The following APIs are removed, after their deprecation in the previous milestone. All APIs annotated with `@KoinReflectAPI` are removed too.

`koin-core`
- `ApplicationAlreadyStartedException` is renamed `KoinApplicationAlreadyStartedException`.
- `KoinScopeComponent.closeScope()` is removed (no longer used internally).
- Internal `ResolutionContext` replaces `InstanceContext`.
- `KoinPlatformTimeTools`, `Timer` and `measureDuration` are removed. Use the Kotlin Time API.
- `KoinContextHandler` is removed in favor of `GlobalContext`.

`koin-android`
- `Fragment.createScope()` is removed.
- The ViewModel factory APIs (mostly internal) are reworked for the new internals.

`koin-compose`
- `StableParametersDefinition` is removed (no longer used internally).
- The lazy ViewModel API (old `viewModel()`) is removed.
- `rememberStableParametersDefinition()` is removed (no longer used internally).

## 3.5.6

Kotlin `1.9.22`.

All library versions are in [libs.versions.toml](https://github.com/InsertKoinIO/koin/blob/3.5.6/projects/gradle/libs.versions.toml).

### New

`koin-core`
- `KoinContext` has new functions:
  - `fun loadKoinModules(module: Module, createEagerInstances: Boolean = false)`
  - `fun loadKoinModules(modules: List<Module>, createEagerInstances: Boolean = false)`
- `koinApplication()` has several signatures:
  - `koinApplication(createEagerInstances: Boolean = true, appDeclaration: KoinAppDeclaration? = null)`
  - `koinApplication(appDeclaration: KoinAppDeclaration?)`
  - `koinApplication(createEagerInstances: Boolean)`
- `KoinAppDeclaration`, to open declaration styles.
- `KoinPlatformTimeTools`, to use the Time API on JS.
- iOS: the `synchronized` API uses the Touchlab Lockable API.

`koin-androidx-compose`
- `KoinAndroidContext`, to bind to the current Koin context from the Android environment.

`koin-compose`
- `KoinContext`, to start with the current default context.

`koin-ktor`
- Uses an isolated context for the Ktor instance (`Application.getKoin()` instead of the default context).
- New monitoring in the Koin Ktor plugin.
- `RequestScope`, to scope instances to a Ktor request.

### Experimental

`koin-android`
- `ViewModelScope`: experimental API for a ViewModel scope.

`koin-core-coroutines`
- New API to load modules in the background.

### Deprecated

`koin-android`
- `getLazyViewModelForClass()`: complex, and calls the default global context. Use the Activity and Fragment APIs.
- `resolveViewModelCompat()`, in favor of `resolveViewModel()`.

`koin-compose`
- `get()` and `inject()`, in favor of `koinInject()`.
- `getViewModel()`, in favor of `koinViewModel()`.
- `rememberKoinInject()`, in favor of `koinInject()`.

### Breaking

`koin-core`
- `Koin.loadModules(modules: List<Module>, allowOverride: Boolean = true, createEagerInstances: Boolean = false)` replaces `Koin.loadModules(modules: List<Module>, allowOverride: Boolean = true)`.
- The `KoinExtension.koin` property is replaced by the `KoinExtension.onRegister()` function.
- iOS: `internal fun globalContextByMemoryModel(): KoinContext` uses `MutableGlobalContext`.

`koin-compose`
- `KoinApplication(moduleList: () -> List<Module>, content: @Composable () -> Unit)` is removed in favor of `KoinContext` and `KoinAndroidContext`.

## 3.4.3

Kotlin `1.8.21`.

### New

`koin-core`
- `ExtensionManager` API, to write extension engines for Koin (`ExtensionManager` and `KoinExtension`).
- Parameters API: `parameterArrayOf` and `parameterSetOf`.

`koin-test`
- `Verification` API, to run `verify()` on a module.

`koin-android`
- Reworked internals for ViewModel injection.
- `AndroidScopeComponent.onCloseScope()` callback.

`koin-android-test`
- `Verification` API, to run `androidVerify()` on a module.

`koin-androidx-compose`
- `get()`.
- `getViewModel()`.
- Scopes `KoinActivityScope` and `KoinFragmentScope`.

`koin-androidx-compose-navigation` (new module)
- `koinNavViewModel()`.

`koin-compose` (new Multiplatform API for Compose)
- `koinInject` and `rememberKoinInject`.
- `KoinApplication`.

### Experimental

`koin-compose`
- `rememberKoinModules`.
- `KoinScope` and `rememberKoinScope`.

### Deprecated

`koin-compose`
- `inject()`, in favor of `get()`, to avoid the lazy function.
- `viewModel()`, in favor of `getViewModel()`, to avoid the lazy function.

### Breaking

`koin-android`
- `LifecycleScopeDelegate` is removed.

`koin-androidx-compose`
- `getStateViewModel` is removed in favor of `koinViewModel`.

## Related

- [API Stability](/docs/support/api-stability): what experimental, deprecated and internal mean.
- [Versions, Roadmap & Support](/docs/support/): release cycle and LTS lines.
- [Compiler Plugin Setup](/docs/setup/compiler-plugin): install or upgrade the Koin Compiler Plugin.
- [Migrating from KSP to the Compiler Plugin](/docs/migration/from-ksp-to-compiler-plugin): move off the KSP processor.
- [Gradle Setup](/docs/setup/gradle): Koin artifacts and the BOM.

---

# API Stability & Release Types

Source: https://insert-koin.io/docs/support/api-stability

This page describes the stability contract of the Koin API: how new APIs are introduced, how old ones are removed, and what each release type promises. For the changes in each version, see [Releases & Upgrade Guides](/docs/support/releases).

## Compatibility between versions

Koin aims to keep existing applications working across versions. The Kotzilla team and the maintainers check that changes, improvements and optimizations in a new release don't break existing code. When an API must change, it goes through the experimental and deprecation steps below, so you can plan the upgrade.

## Experimental APIs

New features are first published under the `@KoinExperimentalAPI` annotation. An experimental API is:

- **Under active development**: its design is not final and may change.
- **Open for feedback**: try it and report what works and what doesn't, this shapes the final design.
- **Not guaranteed**: it may change or be removed in a later release, based on feedback.

Using an experimental API without an opt-in produces a compiler warning. Opt in with Kotlin's `@OptIn`:

```kotlin
@OptIn(KoinExperimentalAPI::class)
fun setupKoin() { ... }
```

The opt-in makes the dependency on an unstable API explicit in your code.

## Delicate APIs

`@KoinDelicateAPI` marks stable APIs that need care. They target specific, advanced cases, and wrong usage can lead to unexpected behavior at runtime. Like experimental APIs, they produce a compiler warning until you opt in with `@OptIn(KoinDelicateAPI::class)`. Read the API documentation before you opt in.

## Deprecated APIs

An API that is being phased out is marked with Kotlin's `@Deprecated`. The message gives the replacement or the reason. When the update is simple, a `ReplaceWith` lets the IDE apply it for you.

Deprecation goes through two levels:

- **Warning**: the API still works, but you should replace it soon.
- **Error**: the API no longer compiles. You must replace it before upgrading.

An API deprecated at error level is usually removed in a later release. The [release notes](/docs/support/releases) list deprecations and removals for each version.

## Internal APIs

`@KoinInternalApi` marks functions and classes that exist for Koin's own mechanisms. They are not part of the public contract:

- **Internal use only**: they serve Koin's implementation, not application code.
- **Subject to change**: they may change or disappear in any release, without notice.

Using one without an opt-in is a compile error. Don't opt in from your application code.

## Release types

Koin follows semantic versioning (`Major.Minor.Patch`, described in [Versions, Roadmap & Support](/docs/support/)). Pre-release versions carry a suffix that says how mature they are:

- **Alpha and beta**: published for testing and feedback. They often contain experimental features and don't fully follow the stable API guarantees. Use them in non-production environments.
- **Release Candidate (RC)**: feature-complete candidates for a stable version, in final testing. They are expected to be compatible with the final release, but small changes are still possible based on feedback.

## Related

- [Releases & Upgrade Guides](/docs/support/releases): changes, deprecations and removals in each version.
- [Versions, Roadmap & Support](/docs/support/): release cycle and support options.
- [Migrating from KSP to the Compiler Plugin](/docs/migration/from-ksp-to-compiler-plugin): moving off the deprecated KSP processor.

---

# Versions, Roadmap & Support

Source: https://insert-koin.io/docs/support

This page explains how Koin versions are numbered and released, and what support exists for each version. Koin is open source and community driven. Kotzilla, the company that builds Koin, also offers commercial long-term support for teams that need it.

## Release cycle

Koin follows a release cycle of about 6 months, to stay aligned with Kotlin language and library updates. Each release goes through a beta period of 6 weeks or more to gather feedback.

Once a version is released, its community support phase lasts at least 6 months. During that phase the team collects feedback and follows the updates that affect Koin: Kotlin, Android, Ktor and other libraries.

For what changed in each version, see [Releases & Upgrade Guides](/docs/support/releases).

## Version numbers

Koin versions follow `Major.Minor.Patch`:

- **Patch**: fixes only, and minor updates of dependency libraries.
- **Minor**: new features and deprecations.
- **Major**: new features with impact, deprecations and breaking changes.

Pre-release suffixes (alpha, beta, RC) and the meaning of `@KoinExperimentalAPI` and `@Deprecated` are described in [API Stability](/docs/support/api-stability).

## Community support

Community support is available to everyone, on the current release line:

- **GitHub Issues**: bug reports and feature requests on [github.com/InsertKoinIO/koin](https://github.com/InsertKoinIO/koin).
- **Documentation**: this site, [insert-koin.io](https://insert-koin.io).
- **Slack**: community discussion on [Kotlin Slack #koin](https://kotlinlang.slack.com/messages/koin/).
- **Stack Overflow**: questions tagged [koin](https://stackoverflow.com/questions/tagged/koin).
- **Release notes**: upgrade guides in [Releases](/docs/support/releases).

## Enterprise Support by Kotzilla

Some companies can't follow the Koin release cycle, for legal, business or technical reasons. They may also need company-backed support and clear open-source license warranties.

Kotzilla offers two enterprise subscriptions for this. Both work the same way: you get a privately maintained build of Koin, pinned to a version you control, and fixes are delivered onto that build instead of only onto the latest public release.

- **[Koin LTS](#long-term-support-lts)**: a maintained Koin line, published under `org.koin.*`, for applications that must stay on a fixed version.
- **[Koin Embedded LTS](#koin-embedded-lts)**: for SDK and library vendors. Your own version of Koin LTS, relocated into a namespace that is yours alone.

Professional Koin support is contracted as an LTS or Embedded LTS subscription. There is no separate tier above it. Commitments such as SLAs, architecture review and training are [add-ons](#add-on-services) to that subscription.

### Long-Term Support (LTS)

An LTS line is a Koin version that Kotzilla keeps maintaining after its community support phase has ended. Security fixes and customer-reported bug fixes are backported onto it and published to subscribers, so you can stay on a version without staying on a known defect.

The support policy:

- **Minimum duration**: each LTS line is guaranteed for at least 18 months from its designation. This is a floor, not a schedule.
- **Coverage**: support continues for as long as your subscription is active, beyond that window, on the version you run. The 18 months bound the commitment to designate and maintain a line. Your coverage is bound by your contract, not by a date published here.
- **New lines**: a new LTS line is designated for each major Kotlin baseline, with a guided upgrade from the previous line and no gap in coverage. You never have to run unsupported during a migration.

This page does not publish end-of-support dates. Coverage follows your subscription and the version you run, and is stated in your agreement.

#### Available LTS lines

The two lines are maintained in parallel, not one after the other. Pick the one that matches the Kotlin baseline of your project. You don't need to move off `3.5.6` to be supported.

| LTS line | Kotlin baseline | Intended for |
|----------|-----------------|--------------|
| Koin 3.5.6 LTS | Kotlin 1.x | Projects that can't move to Kotlin 2.x: legacy toolchains, long-lived enterprise apps, constrained build environments |
| Koin 4.2.x LTS | Kotlin 2.x | Projects on the Kotlin 2.x toolchain that want a fixed, maintained Koin version instead of tracking each release |

:::note
An LTS line is designated at a specific patch level, and that patch level is the minimum: `3.5.6` is the lowest supported version on the Kotlin 1.x line. Versions below it are not covered. If you are on an older patch today, moving up to the LTS patch level is part of onboarding.
:::

The upgrade from the Kotlin 1.x line to the Kotlin 2.x line is part of the offer. The Koin team guides it, and your current line stays covered during the migration.

#### What's included

- **Maintenance and compatibility**: feature compatibility with the Android and Kotlin ecosystems, maintained on the LTS line you run.
- **Support**: priority access to the Koin team, through Slack and dedicated e-mail.
- **Legal compliance**: an audited Apache 2.0 license, with Kotzilla accountable for your compliance.
- **Transparency**: full access to the codebase, and community-identified fixes integrated into your line.

### Koin Embedded LTS

If you ship an SDK or a library that uses Koin internally, publishing under `org.koin.*` conflicts with the Koin version of the host application, and with any other SDK in the same app that embeds Koin too.

Koin Embedded LTS solves this: your own version of Koin LTS, conflict-free, maintained for at least 18 months. Kotzilla relocates a maintained [LTS line](#available-lts-lines) into a namespace that is yours alone, then builds, signs, hosts and maintains it for you. It covers `koin-core` and `koin-android`.

There is also a free, self-service way to get a relocated Koin, with different tradeoffs. [Koin for SDK & Libraries](/docs/support/embedded) covers both: the conflict cases, the self-service options and the [full Embedded LTS offer](/docs/support/embedded#koin-embedded-lts).

### Support tiers

| | Community | Koin LTS | Koin Embedded LTS |
|---|---|---|---|
| Audience | Everyone: apps, open-source projects, teams on the current release | Companies that must stay on a fixed Koin version | SDK and library vendors shipping Koin inside their artifact |
| Delivered version | Latest public release | A designated LTS line, privately maintained | A designated LTS line, relocated into your namespace |
| Namespace | `org.koin.*` | `org.koin.*` | A dedicated namespace, yours alone, for example `acme.koin.*` |
| Distribution | Maven Central | Kotzilla repository, private access with customer credentials | Kotzilla repository, private repository for your organization |
| Security patches | Current release line only | Backported onto your LTS line | Backported and relocated again onto your build |
| Customer issue fixes | Best effort, through public GitHub issues | Fixed and delivered on your LTS build | Fixed and delivered on your build |
| Direct channel to the Koin team | No, public Slack and GitHub only | Priority access, through Slack and dedicated e-mail | Priority access, through Slack and dedicated e-mail |
| Upgrade assistance | Public migration guides | Guided upgrade between LTS lines | Guided upgrade, relocation rebuilt for the target version |

### Add-on services

These are contracted on top of a Koin LTS or Koin Embedded LTS subscription. They are not a separate tier:

- **Service Level Agreements**: contractual response time commitments.
- **Architecture review**: review of your Koin setup and module structure by the Koin team.
- **Training and workshops**: team training on Koin practices.

Terms are agreed per contract. [Contact the team](#contact) about scope.

### Choosing a tier

- **Community**: you follow the current Koin release and public support is enough.
- **Koin LTS**: you need to stay on a version, and you need fixes on that version.
- **Koin Embedded LTS**: you redistribute Koin inside your own artifact and can't risk a namespace collision with your consumers.

## Contact

- **Koin LTS and Koin Embedded LTS**: [Koin Long Term Support](https://kotzilla.io/koin-lts)
- **Kotzilla platform**: [kotzilla.io](https://kotzilla.io)
- **General inquiries**: [koin@kotzilla.io](mailto:koin@kotzilla.io)
- **Community Slack**: [Kotlin Slack #koin](https://kotlinlang.slack.com/messages/koin/)

## Related

- [Releases & Upgrade Guides](/docs/support/releases): what changed in each version and how to upgrade.
- [API Stability](/docs/support/api-stability): experimental, deprecated and internal APIs, release types.
- [Koin for SDK & Libraries](/docs/support/embedded): relocate Koin inside an SDK.
- [Production & Tooling](/docs/tooling): IDE plugin and production monitoring.

---

# Koin for SDK & Libraries

Source: https://insert-koin.io/docs/support/embedded

Koin Embedded lets SDK and library developers package a relocated version of Koin under a different package name. The Koin your library uses internally then can't collide with the Koin used by anything else in the application. This page is for library authors. For a regular app, use standard Koin.

There are two ways to get a relocated Koin: self-service, with the prebuilt artifacts or the relocation scripts, or [Koin Embedded LTS](#koin-embedded-lts), where Kotzilla builds, signs, hosts and maintains a dedicated version for you as part of [Enterprise Support](/docs/support/#enterprise-support-by-kotzilla).

## The conflict problem

A library that uses Koin internally publishes `org.koin.*` as part of its dependency graph. That creates two collision risks, and the second one is often missed.

### Case 1: conflict with the host application

The application that consumes your SDK uses Koin too, on its own release schedule:

```kotlin
// Your SDK uses Koin 3.5.6
implementation("io.insert-koin:koin-core:3.5.6")

// Consumer app uses Koin 4.2.2
implementation("io.insert-koin:koin-core:4.2.2")
// Conflict: Gradle resolves one version for both
```

What this causes:

- **One version for everyone**: Gradle picks a single `org.koin` version for the whole app, so one of you runs against a version you never tested.
- **Runtime failures**: API changes between versions break at runtime.
- **Forced upgrades**: your SDK forces a Koin upgrade on its consumers, or blocks one.

### Case 2: conflict with other SDKs

Your SDK is rarely the only one in the app. If another vendor's SDK also embeds Koin, you collide with each other, and neither of you controls the other's release cycle:

```kotlin
// The app integrates two SDKs, both using Koin internally
implementation("com.vendor-a:analytics-sdk:2.1.0")  // embeds Koin 3.5.6
implementation("com.vendor-b:payments-sdk:5.0.0")   // embeds Koin 4.2.2
// Same conflict, and nobody in the chain can fix it
```

This is why a shared relocation namespace is not enough. Moving off `org.koin.*` onto a namespace that every embedder shares only moves the collision: two SDKs relocated to the same target conflict exactly as before. You need a namespace that is yours alone.

## Package relocation

Relocation rewrites Koin's packages into a different namespace and rebuilds it as a separate artifact:

```kotlin
// Before relocation
import org.koin.core.module.dsl.singleOf
import org.koin.core.context.startKoin

// After relocation
import acme.koin.core.module.dsl.singleOf
import acme.koin.core.context.startKoin
```

Two namespaces are two different sets of classes, so they coexist with no resolution conflict:

```kotlin
// Your SDK bundles its own relocated Koin
implementation("io.insert-koin:acme-koin-core:3.5.6")

// Consumer app uses standard Koin
implementation("io.insert-koin:koin-core:4.2.2")
// No conflict: two separate packages
```

:::warning
Don't use embedded Koin for regular app development. It is for library authors (payment, analytics or authentication SDKs, shared internal libraries, third-party integrations) who need to avoid dependency conflicts.
:::

## Prebuilt embedded version

Kotzilla maintains prebuilt artifacts, `embedded-koin-core` and `embedded-koin-android`, relocated to a shared `embedded.koin.*` namespace. Access is granted on request: contact the [Koin team](mailto:koin@kotzilla.io).

:::warning
These artifacts are in beta and use a shared namespace. They are for evaluation, not for a published SDK. Every consumer relocates to the same `embedded.koin.*` namespace, so two SDKs built on them in one application collide exactly as they would on `org.koin.*` (see [Case 2](#case-2-conflict-with-other-sdks)). Use them to try relocation, or for internal builds you control end to end. To ship an SDK to third parties, relocate it yourself with the [relocation scripts](#custom-relocation) or use [Koin Embedded LTS](#koin-embedded-lts).
:::

## Custom relocation

For a namespace that is yours alone, use the relocation scripts to rebuild Koin yourself.

:::warning
The scripts are a beta initiative, provided as-is, without maintenance guarantees. Everything downstream of them is your responsibility: building, verifying, publishing, and rebuilding on every future Koin release, security fixes included.
:::

### Using the relocation scripts

The [koin-relocate](https://github.com/InsertKoinIO/koin-relocate) project provides scripts to rebuild Koin with custom package names. Relocation is driven by a prefix, applied to both packages and module names:

```
RELOCATION_PREFIX=acme   ->   org.koin.*  becomes  acme.koin.*
                              koin-core   becomes  acme-koin-core
```

Steps:

1. Clone the relocation scripts repository:

   ```bash
   git clone https://github.com/InsertKoinIO/koin-relocate.git
   cd koin-relocate
   ```

2. Edit `relocate.properties` to configure the build:

   ```properties
   RELOCATION_PREFIX=acme
   TARGET_KOIN_VERSION=3.5.6
   KOIN_MODULES=core/koin-core;android/koin-android
   BUILD_DIR=./build
   ```

   - `RELOCATION_PREFIX`: the prefix applied to packages and module names.
   - `TARGET_KOIN_VERSION`: the Koin version tag to build from.
   - `KOIN_MODULES`: the Koin modules to relocate.
   - `BUILD_DIR`: where the built artifacts are copied.

3. Run the relocation. It clones and rebuilds Koin from source, and needs a JDK 17 environment:

   ```bash
   ./relocate.sh
   ```

4. Collect the `aar` and `jar` artifacts from `BUILD_DIR`. All relocated modules are also installed into your local Maven repository, so you can consume them right away while testing.

5. Publish them to your own Maven repository for your SDK builds.

For detailed instructions, see the [koin-relocate repository](https://github.com/InsertKoinIO/koin-relocate).

### What self-hosting involves

The scripts get you a first build. Running a relocated Koin as a dependency of a shipping SDK is a longer commitment. Know its shape before you commit:

- **Koin's build structure**: relocation rebuilds Koin from source. You inherit its multi-module Gradle setup, its version catalog and its toolchain requirements, and you need a JDK 17 environment that stays reproducible in CI.
- **More than package statements**: rewriting `org.koin` in Kotlin sources is the simple part. Resources and declarative service files such as `META-INF/services` entries also carry fully qualified names. Anything the rewrite misses fails at runtime, not at compile time.
- **Android and multiplatform artifacts**: `koin-android` produces `aar` artifacts with their own manifests and consumer rules. With Kotlin Multiplatform, each target publishes its own artifact with its own metadata, and the relocated coordinates must stay consistent across all of them.
- **Publishing and signing**: the scripts produce artifacts under the `io.insert-koin` group with a prefixed module name, installed to your local Maven repository. Publishing them to a repository you control is enough for internal use. Distributing publicly means taking on the POM metadata, group ownership and signing your consumers expect, since the relocated Koin is now part of your supply chain.
- **Verifying equivalence**: a relocated build must behave exactly like the original. Koin's own test suite runs against `org.koin`, so you need your own assurance that resolution, scoping and lifecycle behavior survived the rewrite, for the part of Koin your SDK uses.
- **Repeating it on every Koin patch**: every upstream release you want, every security fix included, means running relocation again, rebuilding, verifying, signing and publishing. A relocation done once is a snapshot that ages from the day you cut it.

None of this is a reason not to self-host. It is a reason to decide deliberately, instead of discovering the cost at the third security advisory.

### Koin Annotations and the Compiler Plugin

:::warning
Koin Annotations and the Koin Compiler Plugin are not supported in relocated builds.
:::

Both generate code that references `org.koin` directly. This code is generated in your project at compile time, after relocation has already happened, so it targets the standard Koin packages that your relocated build no longer provides. The scripts don't relocate generated code.

In a relocated build, declare your modules with the Constructor or Classic DSL (`module { }`, `single`, `factory`, `singleOf`, `factoryOf`).

## Limits of the self-service paths

Beyond the beta status and the shared-namespace caveat, the self-service paths have these limits:

- **No annotations**: Koin Annotations and the Compiler Plugin can't be used.
- **Limited modules**: not all Koin modules relocate cleanly.
- **Build complexity**: relocation means owning a build, verification and publishing pipeline.
- **Maintenance**: every Koin update, security fixes included, is yours to relocate and publish again.

The last one never goes away, and it is what Koin Embedded LTS takes off your hands.

## Koin Embedded LTS

Koin Embedded LTS gives you your own version of Koin LTS, conflict-free, maintained for at least 18 months. It is part of [Enterprise Support by Kotzilla](/docs/support/#enterprise-support-by-kotzilla). Instead of scripts, Kotzilla builds, signs, hosts and maintains a relocated Koin that belongs to you.

### Your own version

You get a dedicated namespace, used by you and nobody else. Kotzilla cuts the build from a maintained Koin LTS line, relocates it into your namespace, signs it, and hosts it in a private repository for your organization. You add one Maven repository and depend on your own relocated modules.

You don't run relocation scripts, maintain a build pipeline, or publish the artifacts.

### Conflict-free

Because the namespace is yours alone, your embedded Koin is invisible to the host application and to every other SDK shipped alongside yours, whatever Koin version they run and whether or not they embed Koin. Neither self-service path gives you that: the prebuilt artifacts share one namespace across all their users, and a namespace you relocate yourself stays isolated only as long as you keep it patched.

### 18 months of maintenance

Your build sits on a maintained LTS line, [Koin 3.5.6 for Kotlin 1.x or Koin 4.2.x for Kotlin 2.x](/docs/support/#available-lts-lines), with at least 18 months of maintenance from designation. Support continues while your subscription is active, on the version you ship.

Every patch on that line is rebuilt and published into your namespace, security backports included. You consume a new version of your own artifact. You don't redo the relocation.

### Scope

Koin Embedded LTS covers `koin-core` and `koin-android`.

Onboarding includes moving you to the LTS patch level. If you are on an older version of the line today, that migration is part of the setup, not something you do first.

:::note
Embedded LTS builds only from LTS lines. Relocating an arbitrary Koin version is a one-off: the artifact lives outside any maintained line, so there is no stream of upstream fixes to rebuild from. That is the artifact nobody patches, and an unpatched DI framework compiled into a widely distributed SDK is the problem this offer exists to prevent. An LTS line always has a next patch to relocate, for as long as your subscription runs.
:::

See [Koin Embedded LTS](https://kotzilla.io/koin-lts) on kotzilla.io.

## SDK development practices

When Koin runs inside your SDK:

- **Keep Koin internal**: it is an implementation detail of your SDK.
- **Don't expose Koin types**: keep `KoinComponent`, `Module` and other Koin types out of your SDK's public API.
- **Use an isolated instance**: start a separate Koin instance for your SDK with `koinApplication`, never the global `startKoin`. See [Context Isolation](/docs/reference/koin-core/context-isolation).
- **Pin the version**: depend on an exact relocated version, never a range.
- **Document the dependency**: say in your SDK documentation that it uses Koin internally.

Koin as an internal detail:

```kotlin
class PaymentSDK private constructor(context: Context) {

    companion object {
        private var instance: PaymentSDK? = null

        fun initialize(context: Context): PaymentSDK {
            return instance ?: PaymentSDK(context).also { instance = it }
        }
    }

    private val koinApp = koinApplication {
        androidContext(context)
        modules(paymentModule)
    }

    private val paymentService: PaymentService = koinApp.koin.get()

    fun processPayment(amount: Double): PaymentResult {
        return paymentService.process(amount)
    }
}
```

Avoid exposing Koin in the public API:

```kotlin
// Don't: KoinComponent and get() leak into your public API
class PaymentSDK : KoinComponent {
    fun getPaymentService(): PaymentService = get()
}
```

In your SDK documentation, state the internal dependency:

```markdown
## Dependencies

This SDK uses Koin internally (embedded version) for dependency injection.
The embedded version is isolated and will not conflict with Koin usage
in your application.

Internal dependency: `io.insert-koin:acme-koin-core:3.5.6`
Package namespace: `acme.koin.*`
```

## Moving an SDK to a relocated Koin

1. **Swap the dependencies**: `io.insert-koin:koin-core` becomes your relocated coordinates, for example `io.insert-koin:acme-koin-core`.
2. **Update the imports**: replace `import org.koin` with `import acme.koin`.
3. **Replace annotations with the DSL**: if your SDK uses Koin Annotations or the Compiler Plugin, rewrite those declarations with the Constructor or Classic DSL. See [Koin Annotations and the Compiler Plugin](#koin-annotations-and-the-compiler-plugin).
4. **Test in a realistic deployment**: in an app that also uses standard Koin, and next to another SDK that embeds Koin if your SDK will meet that situation.

Going back is the same in reverse: restore the standard `koin-*` coordinates and the `org.koin` imports.

## Troubleshooting

### The relocated artifact can't be resolved

```
Could not find io.insert-koin:acme-koin-core:3.5.6
```

Check that the relocated artifact was published, and that the repository you published it to is declared in the consuming build:

```kotlin
repositories {
    maven("https://maven.acme.com/releases")  // wherever you published it
}
```

### ClassNotFoundException at runtime

Check that you use the relocated package names everywhere:

```kotlin
// Wrong
import org.koin.core.context.startKoin

// Correct
import acme.koin.core.context.startKoin
```

If the missing class is only referenced from a resource or a `META-INF/services` entry, the relocation missed a non-source reference. Check that those files carry the relocated names too.

### Version conflicts remain

Don't mix standard and relocated Koin in the same module:

```kotlin
// Don't mix
implementation("io.insert-koin:koin-core:3.5.6")       // standard
implementation("io.insert-koin:acme-koin-core:3.5.6")  // relocated

// Use only your relocated build
implementation("io.insert-koin:acme-koin-core:3.5.6")
```

### Conflict with another SDK that embeds Koin

You are both relocated to the same namespace, most likely both on the prebuilt `embedded.koin.*` artifacts. One of you needs a namespace of its own: relocate it yourself, or use [Koin Embedded LTS](#koin-embedded-lts).

## Feedback

For the self-service paths (prebuilt artifacts and relocation scripts):

- **Issues**: [koin-relocate GitHub issues](https://github.com/InsertKoinIO/koin-relocate/issues)
- **Questions**: [Kotlin Slack #koin](https://kotlinlang.slack.com/messages/koin/)
- **Email**: [koin@kotzilla.io](mailto:koin@kotzilla.io)

## Related

- [Versions, Roadmap & Support](/docs/support/): LTS lines and Enterprise Support by Kotzilla.
- [Context Isolation](/docs/reference/koin-core/context-isolation): run a private Koin instance inside a library.
- [Starting Koin](/docs/reference/koin-core/starting-koin): `startKoin` and `koinApplication`.
- [koin-relocate](https://github.com/InsertKoinIO/koin-relocate): relocation scripts and their documentation.
- [Koin Embedded LTS](https://kotzilla.io/koin-lts): your own maintained, conflict-free Koin.