Skip to main content
Version: 4.2

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​

OptionDescription
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​

MethodUse CaseContext
startKoin { }Standard appsGlobalContext
koinApplication { }Testing, SDKs, isolated contextsLocal instance
koinConfiguration { }AndroidX Startup integrationDeferred startup
KoinApplication { }Compose-only appsCompose 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​

LoggerPlatformDescription
EmptyLoggerAllNo logging (default)
PrintLoggerAllConsole output
AndroidLoggerAndroidAndroid Logcat
SLF4JLoggerJVMSLF4J 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​