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.

Basic Startup

startKoin {
    modules(appModule)
}

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

Complete Configuration

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)
}

Configuration Options

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().

Four Ways to Start Koin

Method	Use Case	Context
startKoin { }	Standard apps	GlobalContext
koinApplication { }	Testing, SDKs, isolated contexts	Local instance
koinConfiguration { }	AndroidX Startup integration	Deferred startup
KoinApplication { }	Compose-only apps	Compose lifecycle

Standard: startKoin

Most common approach - starts Koin globally:

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

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

Isolated: koinApplication

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

Android Startup: koinConfiguration

For AndroidX Startup integration:

class MainApplication : Application(), KoinStartup {
    override fun onKoinStartup() = koinConfiguration {
        androidContext(this@MainApplication)
        modules(appModule)
    }
}

Compose: KoinApplication

For Compose-first applications:

@Composable
fun App() {
    KoinApplication(
        application = { modules(appModule) }
    ) {
        // Your Compose content
        MainScreen()
    }
}

Platform-Specific Configuration

Android

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

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

Ktor

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

Kotlin Multiplatform

Share configuration across platforms:

// commonMain
fun initKoin(config: KoinAppDeclaration? = null) {
    startKoin {
        includes(config)
        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