Koin Relocation Scripts — Embedded Koin for SDK & Libraries

Given that the Android plugin no longer allows using external aar files, and fatjar plugins are outdated, this project provides scripts to rebuild and package Koin under a different package name.

This matters for SDK & library development: if your library uses Koin internally and the consuming application also uses Koin, the two versions conflict. Relocating Koin into your own namespace removes that conflict — your library and the app each get their own independent Koin.

org.koin.*  →  embedded.koin.*     (packages)
koin-core   →  embedded-koin-core  (modules & artifacts)

Feedback or help? Contact the Koin Team.

Two Ways to Get an Embedded Koin

This repository is the open source path: you build it yourself. The scripts are free to use, they rebuild Koin from source under your own prefix, and the result is yours to publish and maintain. When a Koin fix lands upstream, you re-run the relocation and republish — nothing is pushed to you.

If you would rather not own that pipeline, Koin Embedded LTS is the enterprise path: Kotzilla builds your own version of Koin LTS, hosts it in a private repository for your organization, and supports it — with the relocation rebuilt on every patch. See Koin Embedded LTS, or kotzilla.io/koin-lts to get in touch.

Requirements

• JDK 17 environment — the scripts build the Koin project from source
• git and bash

Setup

Clone this repository, then open relocate.properties:

Property	Description
RELOCATION_PREFIX	Prefix used to relocate Koin. embedded turns org.koin.* into embedded.koin.*, and koin-core into embedded-koin-core
TARGET_KOIN_VERSION	Koin version tag to build from
KOIN_MODULES	Koin modules to relocate, as path/module pairs separated by ;
BUILD_DIR	Folder where the built artifacts are copied

Example — Koin 3.5.6

RELOCATION_PREFIX=embedded
TARGET_KOIN_VERSION=3.5.6
KOIN_MODULES=core/koin-core;android/koin-android
BUILD_DIR=./build

Example — Koin 4.0.4

RELOCATION_PREFIX=embedded
TARGET_KOIN_VERSION=4.0.4
KOIN_MODULES=core/koin-core;core/koin-core-viewmodel;android/koin-android
BUILD_DIR=./build

Choosing a prefix

The prefix is used in two places: the package namespace (<prefix>.koin.*) and the module and artifact names (<prefix>-koin-core).

Prefer a single segment, such as acme. A dotted prefix does relocate the packages correctly — com.acme.internal yields com.acme.internal.koin.* — but the same value is also applied to module and artifact names, producing awkward coordinates like com.acme.internal-koin-core.

The Maven group is unchanged: relocated artifacts are published as io.insert-koin:<prefix>-koin-core.

Run the Scripts

./relocate.sh

The script reads relocate.properties, clones Koin at TARGET_KOIN_VERSION into ./koin-<version>-<prefix>, rewrites the packages, renames the modules, then builds and installs them.

The individual steps can also be run on their own: clone_koin.sh, relocate-packages.sh, relocate-module.sh.

Artifacts & Outputs

• All relocated modules are installed into your local Maven repository (~/.m2), so you can consume them straight away while testing.
• The aar/jar artifacts are copied into BUILD_DIR (./build by default).

Consume them as you would any Koin module, under your prefix:

dependencies {
    implementation("io.insert-koin:embedded-koin-core:3.5.6")
    implementation("io.insert-koin:embedded-koin-android:3.5.6")
}

And import from the relocated namespace:

import embedded.koin.core.context.startKoin
import embedded.koin.dsl.module

To share the build across your team or CI, publish BUILD_DIR to your own Maven repository.

Project Sample

The embedded-project-sample folder contains a sample of a Koin embedded SDK library:

• sample-library — Android library project using a relocated Koin
• sample-app — Android application using standard Koin 4.x together with sample-library

Together they demonstrate the point of relocation: the library and the app run different Koin versions side by side, without conflict.

Install the library

From embedded-project-sample/sample-library, run install.sh.

Note: sample-library resolves its embedded-koin-* dependencies from a remote Maven repository. To build it against your own relocation instead, run ./relocate.sh first, then repoint sample-library at your local Maven repository (or your own).

Run the app and library

From embedded-project-sample/sample-app, run the Android app.

Limitations

• Not all Koin modules relocate cleanly — relocate only what you need via KOIN_MODULES
• Relocation builds Koin from source, so it adds a build and publishing step to your pipeline
• Maintenance is yours: every Koin update means re-running the relocation and republishing

See Also

• Koin for SDK & Libraries — full documentation for embedded Koin
• Koin Embedded LTS — Kotzilla builds, hosts and supports your own relocated Koin LTS
• Koin LTS — Enterprise Support by Kotzilla
• Koin Documentation — standard Koin usage