| Usage: kotlinc-jvm <options> <source files> |
| where advanced options include: |
| -Xabi-stability={stable|unstable} |
| When using unstable compiler features such as FIR, use 'stable' to mark generated class files as stable |
| to prevent diagnostics from being reported when using stable compilers at the call site. |
| When using the JVM IR backend, conversely, use 'unstable' to mark generated class files as unstable |
| to force diagnostics to be reported. |
| -Xadd-modules=<module[,]> Root modules to resolve in addition to the initial modules, or all modules on the module path if <module> is ALL-MODULE-PATH. |
| -Xallow-no-source-files Allow the set of source files to be empty. |
| -Xallow-unstable-dependencies Do not report errors on classes in dependencies that were compiled by an unstable version of the Kotlin compiler. |
| -Xannotations-in-metadata Write annotations on declarations into the metadata (in addition to the JVM bytecode), and read annotations from the metadata if they are present. |
| -Xassertions={always-enable|always-disable|jvm|legacy} |
| 'kotlin.assert' call behavior: |
| -Xassertions=always-enable: enable, ignore JVM assertion settings; |
| -Xassertions=always-disable: disable, ignore JVM assertion settings; |
| -Xassertions=jvm: enable, depend on JVM assertion settings; |
| -Xassertions=legacy: calculate the condition on each call, the behavior depends on JVM assertion settings in the kotlin package; |
| default: legacy |
| -Xbackend-threads=<N> Run codegen phase in N parallel threads. |
| 0 means use one thread per processor core. |
| The default value is 1. |
| -Xbuild-file=<path> Path to the .xml build file to compile. |
| -Xdebug Enable debug mode for compilation. |
| Currently this includes spilling all variables in a suspending context regardless of whether they are alive. |
| If API Level >= 2.2 -- no-op. |
| -Xdefault-script-extension=<script filename extension> |
| Compile expressions and unrecognized scripts passed with the -script argument as scripts with the given filename extension. |
| -Xdisable-standard-script Disable standard Kotlin scripting support. |
| -Xemit-jvm-type-annotations Emit JVM type annotations in bytecode. |
| -Xenhance-type-parameter-types-to-def-not-null |
| Enhance not-null-annotated type parameter types to definitely-non-nullable types ('@NotNull T' => 'T & Any'). |
| -Xenhanced-coroutines-debugging |
| Generate additional linenumber instruction for compiler-generated code |
| inside suspend functions and lambdas to distinguish them from user code by debugger. |
| -Xfriend-paths=<path> Paths to output directories for friend modules (modules whose internals should be visible). |
| -Xgenerate-strict-metadata-version |
| Generate metadata with strict version semantics (see the KDoc entry on 'Metadata.extraInt'). |
| -Xignored-annotations-for-bridges=<fq.name>|* |
| Do not copy these annotations to the bridge methods from their targets. |
| -Xindy-allow-annotated-lambdas Allow using 'invokedynamic' for lambda expressions with annotations |
| -Xir-do-not-clear-binding-context |
| When using the IR backend, do not clear BindingContext between 'psi2ir' and lowerings. |
| -Xjava-package-prefix Package prefix for Java files. |
| -Xjava-source-roots=<path> Paths to directories with Java source files. |
| -Xjdk-release=<version> Compile against the specified JDK API version, similarly to javac's '-release'. This requires JDK 9 or newer. |
| The supported versions depend on the JDK used; for JDK 17+, the supported versions are 1.8 and 9–26. |
| This also sets the value of '-jvm-target' to be equal to the selected JDK version. |
| -Xjspecify-annotations=ignore|strict|warn |
| Specify the behavior of 'jspecify' annotations. |
| The default value is 'strict'. |
| -Xjsr305={ignore/strict/warn}|under-migration:{ignore/strict/warn}|@<fq.name>:{ignore/strict/warn} |
| Specify the behavior of 'JSR-305' nullability annotations: |
| -Xjsr305={ignore/strict/warn} global (all non-@UnderMigration annotations) |
| -Xjsr305=under-migration:{ignore/strict/warn} all @UnderMigration annotations |
| -Xjsr305=@<fq.name>:{ignore/strict/warn} annotation with the given fully qualified class name |
| Modes: |
| * ignore |
| * strict (experimental; treat like other supported nullability annotations) |
| * warn (report a warning) |
| -Xjvm-default={all|all-compatibility|disable} |
| This option is deprecated. Migrate to -jvm-default as follows: |
| -Xjvm-default=disable -> -jvm-default=disable |
| -Xjvm-default=all-compatibility -> -jvm-default=enable |
| -Xjvm-default=all -> -jvm-default=no-compatibility |
| -Xjvm-enable-preview Allow using Java features that are in the preview phase. |
| This works like '--enable-preview' in Java. All class files are marked as compiled with preview features, meaning it won't be possible to use them in release environments. |
| -Xjvm-expose-boxed Expose inline classes and functions, accepting and returning them, to Java. |
| -Xklib=<path> Paths to cross-platform libraries in the .klib format. |
| -Xlambdas={class|indy} Select the code generation scheme for lambdas. |
| -Xlambdas=indy Generate lambdas using 'invokedynamic' with 'LambdaMetafactory.metafactory'. |
| A lambda object created using 'LambdaMetafactory.metafactory' will have a different 'toString()'. |
| -Xlambdas=class Generate lambdas as explicit classes. |
| The default value is 'indy' if language version is 2.0+, and 'class' otherwise. |
| -Xlink-via-signatures Link JVM IR symbols via signatures instead of descriptors. |
| This mode is slower, but it can be useful for troubleshooting problems with the JVM IR backend. |
| This option is deprecated and will be deleted in future versions. |
| It has no effect when -language-version is 2.0 or higher. |
| -Xmodule-path=<path> Paths to Java 9+ modules. |
| -Xmultifile-parts-inherit Compile multifile classes as a hierarchy of parts and a facade. |
| -Xno-call-assertions Don't generate not-null assertions for arguments of platform types. |
| -Xno-new-java-annotation-targets |
| Don't generate Java 1.8+ targets for Kotlin annotation classes. |
| -Xno-optimize Disable optimizations. |
| -Xno-param-assertions Don't generate not-null assertions on parameters of methods accessible from Java. |
| -Xno-receiver-assertions Don't generate not-null assertions for extension receiver arguments of platform types. |
| -Xno-reset-jar-timestamps Don't reset jar entry timestamps to a fixed date. |
| -Xno-source-debug-extension Don't generate the '@kotlin.jvm.internal.SourceDebugExtension' annotation with an SMAP copy on classes. |
| -Xno-unified-null-checks Use pre-1.4 exception types instead of 'java.lang.NPE' in null checks. See KT-22275 for more details. |
| -Xnullability-annotations=@<fq.name>:{ignore/strict/warn} |
| Specify the behavior for specific Java nullability annotations (provided with fully qualified package name). |
| Modes: |
| * ignore |
| * strict |
| * warn (report a warning) |
| -Xoutput-builtins-metadata Output builtins metadata as .kotlin_builtins files |
| -Xprofile=<profilerPath:command:outputDir> |
| Debug option: Run the compiler with the async profiler and save snapshots to `outputDir`; `command` is passed to the async profiler on start. |
| `profilerPath` is the path to libasyncProfiler.so; async-profiler.jar should be on the compiler classpath. |
| If it's not on the classpath, the compiler will attempt to load async-profiler.jar from the containing directory of profilerPath. |
| Individual parameter values are separated by the system path separator. |
| Example (Unix/Linux): -Xprofile=<PATH_TO_ASYNC_PROFILER>/async-profiler/build/libasyncProfiler.so:event=cpu,interval=1ms,threads,start:<SNAPSHOT_DIR_PATH> |
| Example (Windows): -Xprofile=<PATH_TO_ASYNC_PROFILER>/async-profiler/build/libasyncProfiler.so;event=cpu,interval=1ms,threads,start;<SNAPSHOT_DIR_PATH> |
| -Xsam-conversions={class|indy} Select the code generation scheme for SAM conversions. |
| -Xsam-conversions=indy Generate SAM conversions using 'invokedynamic' with 'LambdaMetafactory.metafactory'. |
| -Xsam-conversions=class Generate SAM conversions as explicit classes. |
| The default value is 'indy'. |
| -Xsanitize-parentheses Transform '(' and ')' in method names to some other character sequence. |
| This mode can BREAK BINARY COMPATIBILITY and should only be used as a workaround for |
| problems with parentheses in identifiers on certain platforms. |
| -Xscript-resolver-environment=<key=value[,]> |
| Set the script resolver environment in key-value pairs (the value can be quoted and escaped). |
| -Xstring-concat={indy-with-constants|indy|inline} |
| Select the code generation scheme for string concatenation: |
| -Xstring-concat=indy-with-constants Concatenate strings using 'invokedynamic' and 'makeConcatWithConstants'. This requires '-jvm-target 9' or greater. |
| -Xstring-concat=indy Concatenate strings using 'invokedynamic' and 'makeConcat'. This requires '-jvm-target 9' or greater. |
| -Xstring-concat=inline Concatenate strings using 'StringBuilder' |
| default: 'indy-with-constants' for JVM targets 9 or greater, 'inline' otherwise. |
| -Xsupport-compatqual-checker-framework-annotations=enable|disable |
| Specify the behavior for Checker Framework 'compatqual' annotations ('NullableDecl'/'NonNullDecl'). |
| The default value is 'enable'. |
| -Xsuppress-deprecated-jvm-target-warning |
| Suppress warnings about deprecated JVM target versions. |
| This option has no effect and will be deleted in a future version. |
| -Xsuppress-missing-builtins-error |
| Suppress the "cannot access built-in declaration" error (useful with '-no-stdlib'). |
| -Xtype-enhancement-improvements-strict-mode |
| Enable strict mode for improvements to type enhancement for loaded Java types based on nullability annotations, |
| including the ability to read type-use annotations from class files. |
| See KT-45671 for more details. |
| -Xuse-14-inline-classes-mangling-scheme |
| Use the scheme for inline class mangling from version 1.4 instead of the one from 1.4.30. |
| -Xuse-fast-jar-file-system Use the fast implementation of Jar FS. This may speed up compilation time, but it is experimental. |
| -Xuse-inline-scopes-numbers Use inline scopes numbers for inline marker variables. |
| -Xuse-old-class-files-reading Use the old implementation for reading class files. This may slow down the compilation and cause problems with Groovy interop. |
| This can be used in the event of problems with the new implementation. |
| -Xuse-type-table Use a type table in metadata serialization. |
| -Xvalidate-bytecode Validate generated JVM bytecode before and after optimizations. |
| -Xvalue-classes Enable experimental value classes. |
| -Xwhen-expressions={indy|inline} |
| Select the code generation scheme for type-checking 'when' expressions: |
| -Xwhen-expressions=indy Generate type-checking 'when' expressions using 'invokedynamic' with 'SwitchBootstraps.typeSwitch(..)' and |
| following 'tableswitch' or 'lookupswitch'. This requires '-jvm-target 21' or greater. |
| -Xwhen-expressions=inline Generate type-checking 'when' expressions as a chain of type checks. |
| The default value is 'inline'. |
| -Xallow-any-scripts-in-source-roots |
| Allow compiling scripts along with regular Kotlin sources. |
| -Xallow-condition-implies-returns-contracts |
| Allow contracts that specify a limited conditional returns postcondition. |
| -Xallow-contracts-on-more-functions |
| Allow contracts on some operators and accessors, and allow checks for erased types. |
| -Xallow-holdsin-contract Allow contracts that specify a condition that holds true inside a lambda argument. |
| -Xallow-kotlin-package Allow compiling code in the 'kotlin' package, and allow not requiring 'kotlin.stdlib' in 'module-info'. |
| -Xallow-reified-type-in-catch Allow 'catch' parameters to have reified types. |
| -Xallow-returns-result-of Allows to use `returnsResultOf()` in `contract {}` block of function body. This contract provides additional information for return value checker. Enabling this feature will force compiler to produce pre-release binaries, because this functions with this contract cannot be read correctly by Kotlin 2.3 and lower. |
| -Xannotation-default-target=first-only|first-only-warn|param-property |
| Change the default annotation targets for constructor properties: |
| -Xannotation-default-target=first-only: use the first of the following allowed targets: '@param:', '@property:', '@field:'; |
| -Xannotation-default-target=first-only-warn: same as first-only, and raise warnings when both '@param:' and either '@property:' or '@field:' are allowed; |
| -Xannotation-default-target=param-property: use '@param:' target if applicable, and also use the first of either '@property:' or '@field:'; |
| default: 'param-property' in language version 2.4+, 'first-only-warn' in language versions 2.2 & 2.3, 'first-only' in version 2.1 and before. |
| -Xannotation-target-all Enable experimental language support for @all: annotation use-site target. |
| -Xcheck-phase-conditions Check pre- and postconditions of IR lowering phases. |
| -Xcollection-literals Enable experimental language support for collection literals. |
| -Xcommon-sources=<path> Sources of the common module that need to be compiled together with this module in multiplatform mode. |
| They should be a subset of sources passed as free arguments. |
| -Xcompiler-plugin=<path1>,<path2>[=<optionName>=<value>,<optionName>=<value>] |
| Register a compiler plugin. |
| -Xcompiler-plugin-order=<pluginId1>><pluginId2> |
| Specify an execution order constraint for compiler plugins. |
| Order constraint can be specified using the 'pluginId' of compiler plugins. |
| The first specified plugin will be executed before the second plugin. |
| Multiple constraints can be specified by repeating this option. Cycles in constraints will cause an error. |
| -Xconsistent-data-class-copy-visibility |
| The effect of this compiler flag is the same as applying @ConsistentCopyVisibility annotation to all data classes in the module. See https://youtrack.jetbrains.com/issue/KT-11914 |
| -Xcontext-parameters Enable experimental context parameters. |
| -Xcontext-receivers Enable experimental context receivers. |
| -Xcontext-sensitive-resolution Enable experimental context-sensitive resolution. |
| -Xdata-flow-based-exhaustiveness |
| Enable `when` exhaustiveness improvements that rely on data-flow analysis. |
| -Xdetailed-perf Enable more detailed performance statistics (Experimental). |
| For Native, the performance report includes execution time and lines processed per second for every individual lowering. |
| For WASM and JS, the performance report includes execution time and lines per second for each lowering of the first stage of compilation. |
| -Xdirect-java-actualization Enable experimental direct Java actualization support. |
| -Xdisable-default-scripting-plugin |
| Don't enable the scripting plugin by default. |
| -Xdisable-phases Disable backend phases. |
| -Xdont-sort-source-files Disable automatic sorting of source files. |
| -Xdont-warn-on-error-suppression |
| Don't report warnings when errors are suppressed. This only affects K2. |
| -Xdump-directory Dump the backend state into this directory. |
| -Xdump-fqname Dump the declaration with the given FqName. |
| -Xdump-perf=<path> Dump detailed performance statistics to the specified file in plain text, JSON or markdown format (it's detected by the file's extension). |
| Also, it supports the placeholder `*` and directory for generating file names based on the module being compiled and the current time stamp. |
| Example: `path/to/dir/*.log` creates logs like `path/to/dir/my-module_2025-06-20-12-22-32.log` in plain text format, `path/to/dir/` creates logs like `path/to/dir/my-log_2025-06-20-12-22-32.json`. |
| -Xenable-incremental-compilation |
| Enable incremental compilation. |
| -Xexpect-actual-classes 'expect'/'actual' classes (including interfaces, objects, annotations, enums, and 'actual' typealiases) are in Beta. |
| Kotlin reports a warning every time you use one of them. You can use this flag to mute the warning. |
| -Xexplicit-api={strict|warning|disable} |
| Force the compiler to report errors on all public API declarations without an explicit visibility or a return type. |
| Use the 'warning' level to issue warnings instead of errors. |
| -Xexplicit-backing-fields Enable experimental language support for explicit backing fields. |
| -Xexplicit-context-arguments Enable explicit passing of context arguments using named argument syntax. |
| -Xfragment-dependency=<fragment name>:<path> |
| Declare common klib dependencies for the specific fragment. |
| This argument is required for any HMPP module except the platform leaf module: it takes dependencies from -cp/-libraries. |
| The argument should be used only if the new compilation scheme is enabled with -Xseparate-kmp-compilation |
| |
| -Xfragment-friend-dependency=<fragment name>:<path> |
| Declare common klib friend dependencies for the specific fragment. |
| This argument can be specified for any HMPP module except the platform leaf module: it takes dependencies from the platform specific friend module arguments. |
| The argument should be used only if the new compilation scheme is enabled with -Xseparate-kmp-compilation |
| |
| -Xfragment-refines=<fromModuleName>:<onModuleName> |
| Declare that <fromModuleName> refines <onModuleName> with the dependsOn/refines relation. |
| -Xfragment-sources=<fragment name>:<path> |
| Add sources to a specific fragment of a multiplatform compilation. |
| -Xfragments=<fragment name> Declare all known fragments of a multiplatform compilation. |
| -Xheader-mode Enable header compilation mode. |
| In this mode, the compiler produces class files that only contain the 'skeleton' of the classes to be |
| compiled but the method bodies of all the implementations are empty. This is used to speed up parallel compilation |
| build systems where header libraries can be used to replace downstream dependencies for which we only need to |
| see the type names and method signatures required to compile a given translation unit. Inline functions are still kept |
| with bodies. |
| -Xheader-mode-type={any|compilation} |
| Generates output based on what it is used for: |
| -Xheader-mode-type=compilation: Skips the IR generation for modules that don't have inline functions. |
| -Xheader-mode-type=any: Can be used for any downstream dependency which doesn't require linking. |
| -Xignore-const-optimization-errors |
| Ignore all compilation exceptions while optimizing some constant expressions. |
| -Xinline-classes Enable experimental inline classes. |
| -Xintellij-plugin-root=<path> Path to 'kotlin-compiler.jar' or the directory where the IntelliJ IDEA configuration files can be found. |
| -Xintrinsic-const-evaluation Enables `IntrinsicConstEvaluation` language feature.` |
| -Xlist-phases List backend phases. |
| -Xlocal-type-aliases Enable experimental language support for local type aliases. |
| -Xmetadata-klib Produce a klib that only contains the metadata of declarations. |
| -Xmetadata-version Change the metadata version of the generated binary files. |
| -Xmulti-dollar-interpolation Enable experimental multi-dollar interpolation. |
| -Xmulti-platform Enable language support for multiplatform projects. |
| -Xname-based-destructuring=only-syntax|name-mismatch|complete |
| Enables the following destructuring features: |
| -Xname-based-destructuring=only-syntax: Enables syntax for positional destructuring with square brackets and the full form of name-based destructuring with parentheses; |
| -Xname-based-destructuring=name-mismatch: Reports warnings when short form positional destructuring of data classes uses names that don't match the property names; |
| -Xname-based-destructuring=complete: Enables short-form name-based destructuring with parentheses; |
| -Xnested-type-aliases Enable experimental language support for nested type aliases. |
| -Xnew-inference Enable the new experimental generic type inference algorithm. |
| -Xno-check-actual Do not check for the presence of the 'actual' modifier in multiplatform projects. |
| -Xno-inline Disable method inlining. |
| -Xnon-local-break-continue Enable experimental non-local break and continue. |
| -Xphases-to-dump Dump the backend's state both before and after these phases. |
| -Xphases-to-dump-after Dump the backend's state after these phases. |
| -Xphases-to-dump-before Dump the backend's state before these phases. |
| -Xphases-to-validate Validate the backend's state both before and after these phases. |
| -Xphases-to-validate-after Validate the backend's state after these phases. |
| -Xphases-to-validate-before Validate the backend's state before these phases. |
| -Xplugin=<path> Load plugins from the given classpath. |
| -Xprint-configuration Print compiler configuration. |
| -Xprofile-phases Profile backend phases. |
| -Xrender-internal-diagnostic-names |
| Render the internal names of warnings and errors. |
| -Xrepl Run Kotlin REPL (deprecated) |
| -Xreport-all-warnings Report all warnings even if errors are found. |
| -Xreport-output-files Report the source-to-output file mapping. |
| -Xreport-perf Report detailed performance statistics. |
| -Xreturn-value-checker={check|full|disable} |
| Set improved unused return value checker mode. Use 'check' to run checker only and use 'full' to also enable automatic annotation insertion. |
| -Xseparate-kmp-compilation Enables the separated compilation scheme, in which common source sets are analyzed against their own dependencies |
| -Xskip-metadata-version-check Allow loading classes with bad metadata versions and pre-release classes. |
| -Xskip-prerelease-check Allow loading pre-release classes. |
| -Xstdlib-compilation Enables special features which are relevant only for stdlib compilation. |
| -Xsuppress-api-version-greater-than-language-version-error |
| Suppress error about API version greater than language version. |
| Warning: This is temporary solution (see KT-63712) intended to be used only for stdlib build. |
| -Xsuppress-version-warnings Suppress warnings about outdated, inconsistent, or experimental language or API versions. |
| -Xsuppress-warning=<WARNING_NAME> |
| Suppress specified warning module-wide. This option is deprecated in favor of "-Xwarning-level" flag |
| -Xunrestricted-builder-inference |
| Eliminate builder inference restrictions, for example by allowing type variables to be returned from builder inference calls. |
| -Xuse-fir-experimental-checkers |
| Enable experimental frontend IR checkers that are not yet ready for production. |
| -Xuse-fir-ic Compile using frontend IR internal incremental compilation. |
| Warning: This feature is not yet production-ready. |
| -Xuse-fir-lt Compile using the LightTree parser with the frontend IR. |
| -Xverbose-phases Be verbose while performing the given backend phases. |
| -Xverify-ir={none|warning|error} |
| IR verification mode (no verification by default). |
| -Xverify-ir-nested-offsets Check that offsets of nested IR elements conform to offsets of their containers. Only has effect if '-Xverify-ir' is not 'none'. |
| -Xverify-ir-visibility Check for visibility violations in IR when validating it before running any lowerings. Only has effect if '-Xverify-ir' is not 'none'. |
| -Xwarning-level=<WARNING_NAME>:(error|warning|disabled) |
| Set the severity of the given warning. |
| - `error` level raises the severity of a warning to error level (similar to -Werror but more granular) |
| - `disabled` level suppresses reporting of a warning (similar to -nowarn but more granular) |
| - `warning` level overrides -nowarn and -Werror for this specific warning (the warning will be reported/won't be considered as an error) |
| -Xwhen-guards Enable experimental language support for when guards. |
| |
| Advanced options are non-standard and may be changed or removed without any notice. |
| OK |
