Kotlin Symbol Processing API

Welcome to KSP!

Kotlin Symbol Processing (KSP) is an API that you can use to develop lightweight compiler plugins. KSP provides a simplified compiler plugin API that leverages the power of Kotlin while keeping the learning curve at a minimum. Compared to KAPT, annotation processors that use KSP can run up to 2x faster.

Most of the documentation of KSP can be found on kotlinlang.org. Here are some handy links:

For debugging and testing processors, as well as KSP itself, please check DEVELOPMENT.md

KSP Gradle Configurations Reference

This section contains a reference of Gradle configurations for KSP. If you have not used KSP before, or this section seems unclear, please read the documentation on the Kotlin lang website which is linked above.

When applying KSP in your Gradle project, place symbol processor dependencies into the appropriate configuration inside the dependencies { ... } block of your build.gradle.kts (or build.gradle) file based on your target platforms, source sets, and build variants.

Single-Platform (JVM & Android)

Configuration Name / Pattern	Project Type / Target	Source Set / Scope	Usage Example (`build.gradle.kts`)	Details & Behavior
`ksp`	Single-target JVM / Android	Main source set (`src/main`)	`ksp("com.example:processor:1.0")`	Applied to default JVM compilation and single-platform Android main source set. Deprecated in KMP unless `ksp.allow.all.target.configuration=true`.
`kspTest`	Single-target JVM / Android	Unit tests (`src/test`)	`kspTest("com.example:test-processor:1.0")`	Runs symbol processing exclusively for unit test sources.
`ksp<SourceSet>`	Single-target JVM	Custom JVM source set	`add("kspIntegrationTest", "...")`	Generates sources for custom source sets like `integrationTest`.
`ksp<BuildType>`	Android (Single-platform)	Specific build type (e.g., debug, release)	`add("kspDebug", "...")`	Runs processor only when compiling the specified Android build variant.
`ksp<Flavor>`	Android (Single-platform)	Product flavor (e.g., free, paid)	`add("kspFree", "...")`	Runs processor for all build variants matching the specified flavor.
`ksp<Flavor><BuildType>`	Android (Single-platform)	Flavor + Build Type combination	`add("kspFreeDebug", "...")`	Targeted execution for a specific flavor + build type variant.
`kspTest<Flavor><BuildType>`	Android (Single-platform)	Local Unit Tests for variant/flavor	`add("kspTestDebug", "...")`	Runs processing on unit test code in `src/testDebug`.
`kspAndroidTest<Variant>`	Android (Single-platform)	Instrumentation Tests (`src/androidTest`)	`add("kspAndroidTestDebug", "...")`	Runs processing on Android instrumentation test code (`src/androidTest`).

Kotlin Multiplatform (KMP)

Configuration Name / Pattern	Project Type / Target	Source Set / Scope	Usage Example (`build.gradle.kts`)	Details & Behavior
`ksp<Target>`	Kotlin Multiplatform	KMP target main compilation (JVM, JS, Native, Wasm)	`add("kspJvm", "...")` `add("kspJs", "...")` `add("kspIosArm64", "...")` `add("kspAndroid", "...")` `add("kspAndroidHostTest", "...")` `add("kspAndroidDeviceTest", "...")`	Target-specific configuration. Omits the Main suffix (e.g., target `jvm` becomes `kspJvm`, not `kspJvmMain`).
`ksp<Target>Test`	Kotlin Multiplatform	KMP target test compilation	`add("kspJvmTest", "...")` `add("kspJsTest", "...")`	Target-specific test configuration.
`kspCommonMainMetadata`	Kotlin Multiplatform	Common Main metadata compilation	`add("kspCommonMainMetadata", "...")`	Target-specific configuration for KMP `commonMain` metadata processing.

Nightly Builds

Nightly builds of KSP for the latest Kotlin stable releases are published here:

maven("https://central.sonatype.com/repository/maven-snapshots/")

Feedback and Bug Reporting

Please let us know what you think about KSP by filing a Github issue or connecting with our team in the #ksp channel in the Kotlin Slack workspace!

If you are interested in sending PRs, please also check out the Contributor guide.

Ongoing and Future Work

Here are some planned features that have not yet been completely implemented:

Improve support to multiplatform. E.g., running KSP on a subset of targets / sharing computations between targets
Improve performance. There are a bunch of optimizations to be done!
Keep fixing bugs!

A Note on KSP1

KSP 1.x has been removed and is no longer supported.