Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Language Features by Version

Useful JVM flags

A practical guide to JVM command-line options: heap and stack sizes, garbage collector choice, logging, diagnostics, -D properties, JAVA_TOOL_OPTIONS and more.

The java launcher accepts three families of options before the class or JAR name. Standard options (-cp, -version, --add-modules) are stable and documented. -X options (-Xmx, -Xss) are non-standard but widely used. -XX options tune or debug the HotSpot JVM and may change between releases; they come as -XX:+Flag (on), -XX:-Flag (off) or -XX:Name=value. A fourth kind, -Dname=value, is not a JVM setting at all: it defines a system property that your own code can read.

The sandbox on this page does not let you pass options, so the command lines below are read-only. The runnable examples show how a program sees its own options and how to read the properties you set with -D.

Terminal
# Read-only: the general shape of a launch command
java [options] MainClass [program arguments]
java [options] -jar app.jar [program arguments]
java [options] File.java [program arguments]     # source launcher

Memory options

Terminal
# Read-only
-Xms512m                       # initial heap size
-Xmx2g                         # maximum heap size
-XX:MaxRAMPercentage=75        # heap limit as a share of container/host memory
-Xss512k                       # stack size per thread
-XX:MaxMetaspaceSize=256m      # cap on class metadata
-XX:MaxDirectMemorySize=512m   # cap on ByteBuffer.allocateDirect
-XX:+AlwaysPreTouch            # touch all heap pages at start (steadier latency, slower start)

Setting -Xms equal to -Xmx avoids heap resizing in servers. In containers prefer MaxRAMPercentage to a fixed -Xmx, so the heap follows the memory limit.

Garbage collection and logging

Terminal
# Read-only
-XX:+UseG1GC   -XX:+UseZGC   -XX:+UseParallelGC   -XX:+UseSerialGC
-XX:MaxGCPauseMillis=200       # G1 pause goal
-Xlog:gc                       # one line per collection
-Xlog:gc*:file=gc.log:time,uptime,level,tags
-Xlog:safepoint                # time spent reaching safepoints

Diagnostics and crash handling

Terminal
# Read-only
-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/dumps
-XX:+ExitOnOutOfMemoryError    # let the orchestrator restart a broken process
-XX:+CrashOnOutOfMemoryError   # abort and write a core file
-XX:ErrorFile=/var/log/hs_err_%p.log
-XX:+ShowCodeDetailsInExceptionMessages   # default since Java 15: helpful NullPointerException text
-XX:MaxJavaStackTraceDepth=2048
-XX:NativeMemoryTracking=summary          # then: jcmd <pid> VM.native_memory
-XX:StartFlightRecording=duration=60s,filename=app.jfr   # Java Flight Recorder

Language, module and launcher options

Terminal
# Read-only
--enable-preview                       # use preview features of this exact JDK release
--add-modules jdk.incubator.vector     # resolve extra modules
--add-opens java.base/java.lang=ALL-UNNAMED   # allow deep reflection into a package
--add-exports java.base/sun.nio.ch=ALL-UNNAMED
--enable-native-access=ALL-UNNAMED     # allow the foreign function API without warnings
-ea / -da                              # enable / disable assertions (off by default)
-Dfile.encoding=UTF-8                  # redundant since Java 18: UTF-8 is the default
-Duser.timezone=UTC
-Xshare:auto                           # class data sharing (default)

Reading options from the environment

The launcher also reads these variables, which is handy when you cannot edit the command line, for example in a container image:

Variable Effect
JAVA_TOOL_OPTIONS Picked up by every JVM, prints "Picked up JAVA_TOOL_OPTIONS" to stderr
JDK_JAVA_OPTIONS Only for the java launcher (Java 9+); easier to override
@argfiles java @options.txt reads options from a file, one or more per line

Try it

Java -D properties from inside the program

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Asking the JVM about its own options

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Usage notes

  • Flags move. -XX options are not covered by a compatibility promise. Some are removed, some become defaults. An unknown flag stops the JVM with "Unrecognized VM option" unless you add -XX:+IgnoreUnrecognizedVMOptions.
  • Experimental and diagnostic flags need -XX:+UnlockExperimentalVMOptions or -XX:+UnlockDiagnosticVMOptions first.
  • Print the final values. java -XX:+PrintFlagsFinal -version lists every flag with its effective value, and a := in the output marks values that you or ergonomics changed.
  • Check a running JVM with jcmd <pid> VM.flags and jcmd <pid> VM.system_properties.
  • Order matters little for JVM options, but everything after the main class or -jar file belongs to your program, not to the JVM.
  • Do not copy flag lists blindly. Old blog posts recommend flags for the CMS collector (removed in Java 14) or for Java 8 heap layouts. Start with the defaults, measure, and change one thing at a time.
  • Set -Xmx below the container limit so that stacks, metaspace and native memory fit in what remains.