Kotlin Symbol Processing API

Kotlin Symbol Processing (KSP) is a source code generation framework for Kotlin. With the KSP API, you can create processors that inspect static information about your source code and generate new code from it. The most common use case is generating code based on annotations.

KSP aims to simplify the creation of lightweight compiler plugins. A compiler plugin built with KSP is called a symbol processor, or processor for short. KSP's well-defined API hides compiler changes, so you don't need to spend much effort maintaining your processors. However, this approach comes with trade-offs. For example, KSP-based processors can't examine expressions or statements, and they can't modify the source code.

Typical use cases for KSP-based plugins include:

Dependency injection (Dagger)
Serialization (Moshi)
Database management (Room)

To learn how to create your first KSP-based processor, see Getting started with KSP.

Requirements

The latest KSP version, 2.3.10, supports the following dependency versions:

Dependency	Min and max versions
Kotlin Gradle plugin (KGP)	2.2.10–2.3.x
Android Gradle Plugin (AGP)	8.12.0 or later
Gradle	8.13 or later. For AGP 9.0 or later, use Gradle 9.x.
JDK	17 or later

How KSP works during compilation

KSP represents Kotlin source code as a hierarchy of symbols based on the Kotlin grammar. Processors use these symbols to inspect declarations such as classes, functions, properties, and types.

KSP fits into the compilation process as follows:

KSP processors analyze source code and resources.
The processors generate source files or other outputs.
The Kotlin compiler compiles the original source code together with the generated code.

To learn more about KSP, watch this video:

How KSP looks at source files

Most processors navigate through the various program structures of the input source code. Before diving into usage of the API, let's see at how a file might look from KSP's point of view:

KSFile
  packageName: KSName
  fileName: String
  annotations: List<KSAnnotation>  (File annotations)
  declarations: List<KSDeclaration>
    KSClassDeclaration // class, interface, object
      simpleName: KSName
      qualifiedName: KSName
      containingFile: String
      typeParameters: KSTypeParameter
      parentDeclaration: KSDeclaration
      classKind: ClassKind
      primaryConstructor: KSFunctionDeclaration
      superTypes: List<KSTypeReference>
      // contains inner classes, member functions, properties, etc.
      declarations: List<KSDeclaration>
    KSFunctionDeclaration // top level function
      simpleName: KSName
      qualifiedName: KSName
      containingFile: String
      typeParameters: KSTypeParameter
      parentDeclaration: KSDeclaration
      functionKind: FunctionKind
      extensionReceiver: KSTypeReference?
      returnType: KSTypeReference
      parameters: List<KSValueParameter>
      // contains local classes, local functions, local variables, etc.
      declarations: List<KSDeclaration>
    KSPropertyDeclaration // global variable
      simpleName: KSName
      qualifiedName: KSName
      containingFile: String
      typeParameters: KSTypeParameter
      parentDeclaration: KSDeclaration
      extensionReceiver: KSTypeReference?
      type: KSTypeReference
      getter: KSPropertyGetter
        returnType: KSTypeReference
      setter: KSPropertySetter
        parameter: KSValueParameter

This view lists common things that are declared in the file: classes, functions, properties, and so on.

How KSP runs a processor

KSP uses an implementation of SymbolProcessorProvider as the entry point for creating a SymbolProcessor instance:

interface SymbolProcessorProvider {
    fun create(environment: SymbolProcessorEnvironment): SymbolProcessor
}

The SymbolProcessor interface contains the processing logic. KSP calls the process() function and provides a Resolver, which the processor uses to access symbols in the source code:

interface SymbolProcessor {
    fun process(resolver: Resolver): List<KSAnnotated>
    fun finish() {}
    fun onError() {}
}

For a step-by-step guide on how to implement and register a processor, see Getting started with KSP.

Supported libraries

This table lists popular libraries on Android and their various stages of support for KSP:

Library	Status
Room	Officially supported
Moshi	Officially supported
RxHttp	Officially supported
Kotshi	Officially supported
Lyricist	Officially supported
Lich SavedState	Officially supported
gRPC Dekorator	Officially supported
EasyAdapter	Officially supported
Koin Annotations	Officially supported
Glide	Officially supported
Micronaut	Officially supported
Epoxy	Officially supported
Paris	Officially supported
Auto Dagger	Officially supported
SealedX	Officially supported
Ktorfit	Officially supported
Mockative	Officially supported
Kotest	Officially supported
DeeplinkDispatch	Supported via airbnb/DeepLinkDispatch#323
Dagger	Alpha
Motif	Alpha
Hilt	In progress
Auto Factory	Not yet supported

Other resources

17 September 2026