kotlin-reflect

Active contributors: Alexander Udalov, Dmitriy Novozhilov, Filipp Zhinkin

libraries/reflect/ is the Kotlin reflection library on the JVM. It provides full reflection over Kotlin declarations — parameter names, default values, generic type parameters, property delegates, and the lot — by reading the metadata that the Kotlin compiler embeds in JVM class files. JS, Native, and Wasm have a smaller subset of reflection inside stdlib; only the JVM needs a separate kotlin-reflect.jar.

Purpose

Expose Kotlin's full type system at runtime on the JVM. KClass, KFunction, KProperty, KType, parameter information, generic argument inspection, and method invocation through Kotlin types. It is opt-in: programs that don't import it pay no cost (and don't need to ship the ~3 MB kotlin-reflect.jar).

Directory layout

libraries/reflect/
├── api/                       (in src/) public reflection API
├── src/                       Implementation
└── ReadMe.md

(The reflect module shares its KClass/KFunction/KType interfaces with kotlin-stdlib; kotlin-reflect provides the full implementations.)

Key abstractions

Type	Where defined	Where implemented (kotlin-reflect)
KClass<T>	stdlib kotlin.reflect	libraries/reflect/.../KClassImpl.kt
KFunction<R>	stdlib	libraries/reflect/.../KFunctionImpl.kt
KProperty<R>	stdlib	libraries/reflect/.../KPropertyImpl.kt
KType	stdlib	libraries/reflect/.../KTypeImpl.kt
KParameter	stdlib	libraries/reflect/.../KParameterImpl.kt
ReflectKotlinClass	libraries/reflect/...	The bridge from JVM Class to Kotlin reflection.

How it works

Kotlin compilers embed metadata in JVM class files via the kotlin.Metadata annotation. The annotation carries serialized protocol-buffer data describing every Kotlin-specific aspect of the class (generic parameters with variance, default values, suspend marker, inline classes, ...).

kotlin-reflect reads that metadata using libraries/kotlinx-metadata/ (or its internal equivalent), then materializes the KClass/KFunction/KProperty views the user sees. Method invocation is implemented by reflecting JVM members and adapting Kotlin signatures to their JVM counterparts (e.g., suspend functions take an extra Continuation parameter).

graph LR
    User["KClass<MyClass>"] --> Impl["KClassImpl"]
    Impl -->|reads| Metadata["@kotlin.Metadata<br/>(JVM annotation)"]
    Metadata -->|deserialize| Proto["Kotlin proto-buf"]
    Proto --> Symbols["Kotlin descriptors<br/>(in-memory)"]
    Symbols --> View["KClass / KFunction / KProperty"]

Lazy initialization

The reflection library is heavily lazy. Walking a KClass does not deserialize every member up front; each accessor pulls in just what it needs. This keeps cold-start cost bounded for users who only inspect a few declarations.

Optional dependency

kotlin-reflect is shipped as a separate jar (kotlin-reflect.jar) and is not a transitive dependency of kotlin-stdlib. Code that uses full reflection must add it explicitly:

implementation("org.jetbrains.kotlin:kotlin-reflect:<version>")

This avoids the 3 MB cost for the (large) majority of Kotlin programs that don't need full reflection.

What stdlib alone gives you

Even without kotlin-reflect, stdlib offers minimal reflection:

• KClass<T>::simpleName, qualifiedName, isAbstract, isFinal
• KClass<T>::java (JVM bridge)
• T::class.javaClass and friends

The full set of KClass members (constructors, members, supertypes) requires kotlin-reflect.

Integration points

• Consumed by: any JVM Kotlin program that uses full reflection. Many ORMs, serialization libraries, and DI frameworks pull it in.
• Depends on: stdlib, kotlinx-metadata.
• Tested by: libraries/reflect/test/.

Where to start

For a new reflection feature: usually a new method on KClass/KFunction/KProperty in stdlib, plus an implementation in libraries/reflect/. Mind binary compatibility — both kotlin-reflect.jar and kotlin-stdlib.jar carry .api dumps.

For a bug in invocation behavior: libraries/reflect/.../calls/ is where Kotlin → JVM signature adaptation happens.