Kotlin Help

Running KSP from the command line

Most projects use KSP through the KSP plugin for Gradle that runs KSP automatically during compilation. As an alternative, you can also run KSP from the command line. This is useful if you integrate KSP with other build systems, develop processors, or test and debug the code.

Since KSP is a JVM application, use the java command to launch KSP from the command line. Provide the classpath and any necessary arguments:

java -cp <classpath> <mainclass> <options> <processor>

Argument

Description

<classpath>

A path to the KSP runtime JAR files and their dependencies.

<mainclass>

A platform-specific KSP entry point.

<options>

Command-line options for KSP.

<processor>

A path to the processor JAR.

Classpath

Unlike the KSP plugin for Gradle, the java command doesn't resolve dependencies automatically. You must provide the KSP runtime JAR files and their dependencies on the classpath.

Download artifacts.zip from the KSP release page on GitHub. The archive contains the required KSP JAR files:

  • symbol-processing-aa-2.3.12.jar

  • symbol-processing-common-deps-2.3.12.jar

  • symbol-processing-api-2.3.12.jar

You must also include the following runtime dependencies from the Maven repository:

Main class

Because KSP is a JVM application, you must specify the main class to launch. KSP provides a different entry point for each supported platform:

Entry point

Platforms

KSPJvmMain

Kotlin/JVM and Android

KSPJsMain

Kotlin/JS

KSPNativeMain

Kotlin/Native targets, such as iOS, macOS, Linux, and Windows

KSPCommonMain

Common compilations in Kotlin Multiplatform projects

When launching KSP with java, specify the fully qualified class name. For example:

java -cp <classpath> com.google.devtools.ksp.cmdline.KSPJvmMain <options> <processor>

The following example uses KSPJvmMain to run KSP for a JVM target:

java -cp \ symbol-processing-aa-2.3.12.jar:\ symbol-processing-common-deps-2.3.12.jar:\ symbol-processing-api-2.3.12.jar:\ kotlin-stdlib-2.4.21.jar:\ kotlinx-coroutines-core-jvm-1.11.0.jar \ com.google.devtools.ksp.cmdline.KSPJvmMain \ -language-version=2.0 \ -api-version=2.0 \ -jvm-target=11 \ -module-name=main \ -source-roots=project_dir/src/kotlin/main \ -project-base-dir=project_dir/ \ -output-base-dir=project_dir/build/ \ -caches-dir=project_dir/build/caches/ \ -class-output-dir=project_dir/build/out/main/classes \ -kotlin-output-dir=project_dir/build/out/main/kotlin/ \ -java-output-dir=project_dir/build/out/main/java/ \ -resource-output-dir=project_dir/build/out/main/res/ \ path/to/processor.jar

Options

The KSPJvmMain entry point requires the following options:

Option

Description

-language-version=<version>

Kotlin language version used in the project.

-api-version=<version>

Kotlin API version.

-jvm-target=<version>

Target JVM version.

-module-name=<name>

Module name.

-source-roots=<paths>

Source root directories. Use a colon-separated list for multiple directories.

-project-base-dir=<path>

Project root directory.

-output-base-dir=<path>

Base directory for KSP output.

-caches-dir=<path>

Directory for KSP caches.

-java-output-dir=<path>

Directory for generated Java files.

-class-output-dir=<path>

Directory for generated class files.

-kotlin-output-dir=<path>

Directory for generated Kotlin files.

-resource-output-dir=<path>

Directory for generated resources.

<processor>

Processor classpath.

Other entry points use a different set of options. To see the full list of options for a specific entry point, run the following command:

java -cp <classpath> <mainclass> -h

Other options

  • -libraries=<path>: the classpath used to resolve dependencies referenced by the source files. This is typically the module's compile classpath.

  • -jdk-home=<path>: the JDK home directory. Use when the processor resolves Java symbols and requires access to the Java standard library.

  • -friends=<path>: the classpath of the current module's friend modules. For more information, refer to the friendPaths property in the Kotlin Gradle plugin API reference.

See also

18 November 2026