Java Launcher Options

The java launcher starts a JVM implementation; many flags are HotSpot implementation options rather than Java language or JVM specification requirements. Use the launcher documentation for the JDK release deployed by the application, because availability and defaults change between releases.

Option Families #

Standard options include --class-path, --module-path, -Dname=value, and -version. HotSpot uses -X for nonstandard options and -XX: for diagnostic and advanced flags. JDK_JAVA_OPTIONS prepends options to every launcher invocation in its environment, so reserve it for controlled runtime environments and inspect it when a process has unexpected behavior.

java --class-path app.jar com.example.Main
java --module-path mods --module com.example.app/com.example.Main
java -Duser.timezone=UTC -jar app.jar

Heap and Native Memory #

-Xms sets the initial heap size and -Xmx sets the maximum heap size. Use binary suffixes such as k, m, and g; without a suffix, the value is bytes. The heap is not the process memory limit: metaspace, code cache, thread stacks, direct buffers, native libraries, and JVM internals also consume native memory.

java -Xms512m -Xmx2g -XX:MaxMetaspaceSize=256m -jar app.jar

Set a container memory limit with headroom for non-heap memory. Inspect the effective JVM flags and native-memory behavior under production load rather than copying a heap ratio from an unrelated service.

Thread Stacks and Diagnostics #

-Xss controls the native stack allocated for each Java thread. A larger stack can avoid deep-recursion overflow but reduces the number of threads a fixed memory budget can support. -XX:ThreadStackSize expresses the corresponding HotSpot setting in KiB.

Use -Xlog for unified JVM logging on modern JDKs and use jcmd <pid> VM.flags or VM.command_line to inspect a running HotSpot process. Enable expensive diagnostic flags only for a measured purpose and remove them after the investigation.