Gradle Setup

This guide covers how to add Koin dependencies to your Gradle project.

Koin BOM (Recommended)

The Bill of Materials (BOM) is the recommended way to manage Koin dependencies. It ensures all Koin libraries use compatible versions.

info

Best Practice: Always use the Koin BOM to avoid version conflicts between Koin libraries.

Using Version Catalogs (Recommended)

In your gradle/libs.versions.toml:

[versions]
koin-bom = "4.2.0"

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

In your build.gradle.kts:

dependencies {
    implementation(platform(libs.koin.bom))
    implementation(libs.koin.android)  // No version needed
}

Using BOM Directly

dependencies {
    implementation(platform("io.insert-koin:koin-bom:$koin_version"))

    // Add dependencies without versions
    implementation("io.insert-koin:koin-android")
    implementation("io.insert-koin:koin-androidx-compose")
}

Platform-Specific Setup

Kotlin/JVM

For pure Kotlin applications:

dependencies {
    implementation(platform("io.insert-koin:koin-bom:$koin_version"))
    implementation("io.insert-koin:koin-core")
}

Start Koin in your application:

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

Testing dependencies:

dependencies {
    testImplementation("io.insert-koin:koin-test")
    testImplementation("io.insert-koin:koin-test-junit5")  // or junit4
}

Android

For Android applications:

dependencies {
    implementation(platform("io.insert-koin:koin-bom:$koin_version"))
    implementation("io.insert-koin:koin-android")
}

Start Koin in your Application class:

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

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

Optional Android packages:

dependencies {
    // Jetpack WorkManager
    implementation("io.insert-koin:koin-androidx-workmanager")

    // Navigation Graph
    implementation("io.insert-koin:koin-androidx-navigation")

    // AndroidX Startup
    implementation("io.insert-koin:koin-androidx-startup")

    // Java Compatibility
    implementation("io.insert-koin:koin-android-compat")
}

Jetpack Compose (Android)

For Android apps using Jetpack Compose:

dependencies {
    implementation(platform("io.insert-koin:koin-bom:$koin_version"))
    implementation("io.insert-koin:koin-androidx-compose")
    implementation("io.insert-koin:koin-androidx-compose-navigation")
}

Compose Multiplatform

For Compose Multiplatform (Android, iOS, Desktop, Web):

dependencies {
    implementation(platform("io.insert-koin:koin-bom:$koin_version"))
    implementation("io.insert-koin:koin-compose")
    implementation("io.insert-koin:koin-compose-viewmodel")
    implementation("io.insert-koin:koin-compose-viewmodel-navigation")
}

Navigation 3 (Experimental):

dependencies {
    implementation("io.insert-koin:koin-compose-navigation3")
}

warning

Navigation 3 is in alpha. See Navigation 3 Integration for details.

Kotlin Multiplatform

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

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

        commonTest.dependencies {
            implementation("io.insert-koin:koin-test")
        }

        androidMain.dependencies {
            implementation("io.insert-koin:koin-android")
        }
    }
}

Ktor

For Ktor server applications:

dependencies {
    implementation(platform("io.insert-koin:koin-bom:$koin_version"))
    implementation("io.insert-koin:koin-ktor")
    implementation("io.insert-koin:koin-logger-slf4j")
}

Install Koin in your Ktor application:

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

All Available Packages

Package	Description
koin-core	Core Koin library
koin-core-coroutines	Coroutines support
koin-android	Android support
koin-android-compat	Java compatibility for Android
koin-androidx-navigation	Navigation Component support
koin-androidx-workmanager	WorkManager support
koin-androidx-startup	AndroidX Startup support
koin-androidx-compose	Jetpack Compose (Android)
koin-androidx-compose-navigation	Compose Navigation (Android)
koin-compose	Compose Multiplatform
koin-compose-viewmodel	ViewModel for Compose MP
koin-compose-viewmodel-navigation	Navigation + ViewModel for Compose MP
koin-compose-navigation3	Navigation 3 (experimental)
koin-ktor	Ktor server support
koin-logger-slf4j	SLF4J logging
koin-test	Testing utilities
koin-test-junit4	JUnit 4 support
koin-test-junit5	JUnit 5 support
koin-android-test	Android instrumented testing

Direct Version Specification

If you prefer not to use the BOM:

dependencies {
    implementation("io.insert-koin:koin-core:$koin_version")
    implementation("io.insert-koin:koin-android:$koin_version")
}

note

This approach requires manually keeping all dependencies synchronized. Using the BOM is strongly recommended.

Next Steps

• Compiler Plugin Setup - Add compile-time safety
• Starting Koin - Configure your application
• Tutorials - Build your first app