Starting Koin

This guide covers how to initialize the Koin container and configure it for your application.

The startKoin Function

startKoin is the main entry point to launch Koin. It registers the container in GlobalContext, making it accessible throughout your application.

startKoin {
    modules(appModule)
}

Once started, dependencies are ready for resolution via get() or by inject().

Configuration Options

startKoin {
    // Logging
    logger(Level.INFO)

    // Properties
    environmentProperties()
    fileProperties()
    properties(mapOf("env" to "production"))

    // Modules
    modules(
        coreModule,
        networkModule,
        dataModule
    )

    // Lazy modules (background loading)
    lazyModules(analyticsModule, reportingModule)

    // Create eager singletons
    createEagerInstances()

    // Override control
    allowOverride(false)
}

Option	Description
logger()	Set logging level and implementation
modules()	Load modules immediately
lazyModules()	Load modules in background
properties()	Load properties from map
fileProperties()	Load from koin.properties file
environmentProperties()	Load from system/environment
createEagerInstances()	Create all createdAtStart singletons
allowOverride()	Enable/disable definition overriding

info

startKoin can only be called once. To load additional modules later, use loadKoinModules().

Starting the Koin Container

Method	Use Case
startKoin { }	Standard apps - registers in GlobalContext
koinApplication { }	Testing, SDKs, isolated contexts - local instance
koinConfiguration { }	Configuration holder for dedicated APIs (Compose, Ktor)

tip

With the Koin Compiler Plugin, typed variants are available: startKoin<T>(), koinApplication<T>(), koinConfiguration<T>(). See Starting Koin with Compiler Plugin below.

startKoin - Global Instance

Most common approach - starts Koin globally:

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

    // Use anywhere
    val service: MyService = get()
}

koinApplication - Isolated Instance

Creates an isolated Koin instance (not in GlobalContext):

val myKoin = koinApplication {
    modules(myModule)
}.koin

// Use the isolated instance
val service: MyService = myKoin.get()

Use cases:

• Testing with isolated contexts
• SDK development (avoid polluting host app)
• Multiple Koin instances

koinConfiguration - Configuration Holder

Creates a configuration to be used by dedicated APIs (Compose KoinApplication, Ktor plugin):

val config = koinConfiguration {
    modules(appModule)
}

// Used by Compose KoinApplication, Ktor, etc.

Starting Koin with Compiler Plugin

When using the Koin Compiler Plugin with annotations, you can use typed APIs to start Koin - no generated code needed.

info

This requires the Koin Compiler Plugin. Your application class must be annotated with @KoinApplication.

Define Your Application

@Module
@Configuration
@ComponentScan("com.myapp")
class MyModule

@KoinApplication
class MyApp

Typed Startup APIs

API	Description
startKoin<T>()	Start Koin globally with application T
startKoin<T> { }	Start with application T and additional configuration
koinApplication<T>()	Create isolated KoinApplication with T
koinConfiguration<T>()	Create KoinConfiguration from T (for Compose, Ktor)

Where T is a class annotated with @KoinApplication.

Examples

// Simple startup
startKoin<MyApp>()

// With additional configuration
startKoin<MyApp> {
    printLogger()
}

// Isolated instance
val myKoin = koinApplication<MyApp>().koin

// Configuration for Compose/Ktor
val config = koinConfiguration<MyApp>()

Multi-Module Projects

// feature/src/main/kotlin/FeatureModule.kt
@Module
@Configuration
@ComponentScan("com.myapp.feature")
class FeatureModule

// app/src/main/kotlin/MyApp.kt
@KoinApplication
class MyApp

// Start Koin
startKoin<MyApp>()

Platform Integrations

Android

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()

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

With Compiler Plugin:

@KoinApplication
class MyApp

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        startKoin<MyApp> {
            androidLogger()
            androidContext(this@MainApplication)
        }
    }
}

Compose

Use KoinApplication composable with koinConfiguration:

@Composable
fun App() {
    KoinApplication(
        configuration = koinConfiguration { modules(appModule) }
    ) {
        MainScreen()
    }
}

With Compiler Plugin:

@KoinApplication
class MyApp

@Composable
fun App() {
    KoinApplication(
        configuration = koinConfiguration<MyApp>()
    ) {
        MainScreen()
    }
}

Ktor

fun Application.module() {
    install(Koin) {
        slf4jLogger()
        modules(appModule)
    }
}

With Compiler Plugin:

@KoinApplication
class MyApp

fun Application.module() {
    install(Koin) {
        slf4jLogger()
        withConfiguration<MyApp>()
    }
}

info

See Ktor Integration for more details.

Kotlin Multiplatform

Share configuration across platforms:

// commonMain
fun initKoin(config: KoinAppDeclaration? = null) {
    startKoin {
        config?.invoke(this)
        modules(sharedModule)
    }
}

// androidMain
class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        initKoin {
            androidContext(this@MainApplication)
            androidLogger()
        }
    }
}

// iosMain
fun initKoinIos() = initKoin()

Dynamic Module Management

Loading Modules After Startup

// Initial startup
startKoin {
    modules(coreModule)
}

// Later, load additional modules
loadKoinModules(featureModule)

Unloading Modules

unloadKoinModules(featureModule)

Feature Toggle Example

if (isFeatureEnabled) {
    loadKoinModules(premiumFeatureModule)
}

// Later, if disabled
unloadKoinModules(premiumFeatureModule)

Stopping Koin

Close the container and release resources:

stopKoin()

For isolated instances:

val koinApp = koinApplication { modules(myModule) }
koinApp.close()

Logging

Enable Logging

startKoin {
    logger(Level.INFO)  // Or DEBUG, WARNING, ERROR, NONE
}

Available Loggers

Logger	Platform	Description
EmptyLogger	All	No logging (default)
PrintLogger	All	Console output
AndroidLogger	Android	Android Logcat
SLF4JLogger	JVM	SLF4J integration

Platform-Specific Loggers

// Android
startKoin {
    androidLogger(Level.DEBUG)
}

// Ktor
install(Koin) {
    slf4jLogger()
}

Properties

Loading Properties

startKoin {
    // From environment
    environmentProperties()

    // From file (koin.properties)
    fileProperties()

    // From code
    properties(mapOf(
        "server_url" to "https://api.example.com",
        "api_key" to "secret123"
    ))
}

Using Properties

val appModule = module {
    single {
        ApiClient(
            url = getProperty("server_url"),
            key = getProperty("api_key", "default")
        )
    }
}

Best Practices

1. Call startKoin once - At application entry point
2. Load critical modules immediately - Use modules()
3. Use lazy modules - Defer non-critical with lazyModules()
4. Enable logging in development - logger(Level.DEBUG)
5. Use strict mode in production - allowOverride(false)
6. Stop Koin between tests - Call stopKoin() to reset state

Next Steps

• Modules - Organize your definitions
• Definitions - Create definitions with DSL or Annotations
• Injection - Retrieve dependencies