1JAVA(1) JDK Commands JAVA(1)
2
6 java - launch a Java application
7
9 To launch a class file:
10 java [options] mainclass [args ...]
12 To launch the main class in a JAR file:
14 java [options] -jar jarfile [args ...]
16 To launch the main class in a module:
18 java [options] -m module[/mainclass] [args ...]
20 or
22 java [options] --module module[/mainclass] [args ...]
24 To launch a single source-file program:
26 java [options] source-file [args ...]
28 options
30 Optional: Specifies command-line options separated by spaces.
31 See Overview of Java Options for a description of available op‐
32 tions.
33 mainclass
35 Specifies the name of the class to be launched. Command-line
36 entries following classname are the arguments for the main meth‐
37 od.
38 -jar jarfile
40 Executes a program encapsulated in a JAR file. The jarfile ar‐
41 gument is the name of a JAR file with a manifest that contains a
42 line in the form Main-Class:classname that defines the class
43 with the public static void main(String[] args) method that
44 serves as your application's starting point. When you use -jar,
45 the specified JAR file is the source of all user classes, and
46 other class path settings are ignored. If you're using JAR
47 files, then see jar.
48 -m or --module module[/mainclass]
50 Executes the main class in a module specified by mainclass if it
51 is given, or, if it is not given, the value in the module. In
52 other words, mainclass can be used when it is not specified by
53 the module, or to override the value when it is specified.
54 See Standard Options for Java.
56 source-file
58 Only used to launch a single source-file program. Specifies the
59 source file that contains the main class when using source-file
60 mode. See Using Source-File Mode to Launch Single-File
61 Source-Code Programs
62 args ...
64 Optional: Arguments following mainclass, source-file, -jar
65 jarfile, and -m or --module module/mainclass are passed as argu‐
66 ments to the main class.
67
69 The java command starts a Java application. It does this by starting
70 the Java Virtual Machine (JVM), loading the specified class, and call‐
71 ing that class's main() method. The method must be declared public and
72 static, it must not return any value, and it must accept a String array
73 as a parameter. The method declaration has the following form:
74 public static void main(String[] args)
76 In source-file mode, the java command can launch a class declared in a
78 source file. See Using Source-File Mode to Launch Single-File
79 Source-Code Programs for a description of using the source-file mode.
80 Note: You can use the JDK_JAVA_OPTIONS launcher environment
82 variable to prepend its content to the actual command line of
83 the java launcher. See Using the JDK_JAVA_OPTIONS Launcher En‐
84 vironment Variable.
85 By default, the first argument that isn't an option of the java command
87 is the fully qualified name of the class to be called. If -jar is
88 specified, then its argument is the name of the JAR file containing
89 class and resource files for the application. The startup class must
90 be indicated by the Main-Class manifest header in its manifest file.
91 Arguments after the class file name or the JAR file name are passed to
93 the main() method.
94 javaw
96 Windows: The javaw command is identical to java, except that with javaw
97 there's no associated console window. Use javaw when you don't want a
98 command prompt window to appear. The javaw launcher will, however,
99 display a dialog box with error information if a launch fails.
100
102 To launch a class declared in a source file, run the java launcher in
103 source-file mode. Entering source-file mode is determined by two items
104 on the java command line:
105 • The first item on the command line that is not an option or part of
107 an option. In other words, the item in the command line that would
108 otherwise be the main class name.
109 • The --source version option, if present.
111 If the class identifies an existing file that has a .java extension, or
113 if the --source option is specified, then source-file mode is selected.
114 The source file is then compiled and run. The --source option can be
115 used to specify the source version or N of the source code. This de‐
116 termines the API that can be used. When you set --source N, you can
117 only use the public API that was defined in JDK N.
118 Note: The valid values of N change for each release, with new
120 values added and old values removed. You'll get an error mes‐
121 sage if you use a value of N that is no longer supported. The
122 supported values of N are the current Java SE release (18) and a
123 limited number of previous releases, detailed in the com‐
124 mand-line help for javac, under the --source and --release op‐
125 tions.
126 If the file does not have the .java extension, the --source option must
128 be used to tell the java command to use the source-file mode. The
129 --source option is used for cases when the source file is a "script" to
130 be executed and the name of the source file does not follow the normal
131 naming conventions for Java source files.
132 In source-file mode, the effect is as though the source file is com‐
134 piled into memory, and the first class found in the source file is exe‐
135 cuted. Any arguments placed after the name of the source file in the
136 original command line are passed to the compiled class when it is exe‐
137 cuted.
138 For example, if a file were named HelloWorld.java and contained a class
140 named hello.World, then the source-file mode command to launch the
141 class would be:
142 java HelloWorld.java
144 The example illustrates that the class can be in a named package, and
146 does not need to be in the unnamed package. This use of source-file
147 mode is informally equivalent to using the following two commands where
148 hello.World is the name of the class in the package:
149 javac -d <memory> HelloWorld.java
151 java -cp <memory> hello.World
152 In source-file mode, any additional command-line options are processed
154 as follows:
155 • The launcher scans the options specified before the source file for
157 any that are relevant in order to compile the source file.
158 This includes: --class-path, --module-path, --add-exports, --add-mod‐
160 ules, --limit-modules, --patch-module, --upgrade-module-path, and any
161 variant forms of those options. It also includes the new --en‐
162 able-preview option, described in JEP 12.
163 • No provision is made to pass any additional options to the compiler,
165 such as -processor or -Werror.
166 • Command-line argument files (@-files) may be used in the standard
168 way. Long lists of arguments for either the VM or the program being
169 invoked may be placed in files specified on the command-line by pre‐
170 fixing the filename with an @ character.
171 In source-file mode, compilation proceeds as follows:
173 • Any command-line options that are relevant to the compilation envi‐
175 ronment are taken into account.
176 • No other source files are found and compiled, as if the source path
178 is set to an empty value.
179 • Annotation processing is disabled, as if -proc:none is in effect.
181 • If a version is specified, via the --source option, the value is used
183 as the argument for an implicit --release option for the compilation.
184 This sets both the source version accepted by compiler and the system
185 API that may be used by the code in the source file.
186 • The source file is compiled in the context of an unnamed module.
188 • The source file should contain one or more top-level classes, the
190 first of which is taken as the class to be executed.
191 • The compiler does not enforce the optional restriction defined at the
193 end of JLS ??7.6, that a type in a named package should exist in a
194 file whose name is composed from the type name followed by the .java
195 extension.
196 • If the source file contains errors, appropriate error messages are
198 written to the standard error stream, and the launcher exits with a
199 non-zero exit code.
200 In source-file mode, execution proceeds as follows:
202 • The class to be executed is the first top-level class found in the
204 source file. It must contain a declaration of the standard pub‐
205 lic static void main(String[]) method.
206 • The compiled classes are loaded by a custom class loader, that dele‐
208 gates to the application class loader. This implies that classes ap‐
209 pearing on the application class path cannot refer to any classes de‐
210 clared in the source file.
211 • The compiled classes are executed in the context of an unnamed mod‐
213 ule, as though --add-modules=ALL-DEFAULT is in effect. This is in
214 addition to any other --add-module options that may be have been
215 specified on the command line.
216 • Any arguments appearing after the name of the file on the command
218 line are passed to the standard main method in the obvious way.
219 • It is an error if there is a class on the application class path
221 whose name is the same as that of the class to be executed.
222 See JEP 330: Launch Single-File Source-Code Programs [http://open‐
224 jdk.java.net/jeps/330] for complete details.
225
227 JDK_JAVA_OPTIONS prepends its content to the options parsed from the
228 command line. The content of the JDK_JAVA_OPTIONS environment variable
229 is a list of arguments separated by white-space characters (as deter‐
230 mined by isspace()). These are prepended to the command line arguments
231 passed to java launcher. The encoding requirement for the environment
232 variable is the same as the java command line on the system. JDK_JA‐
233 VA_OPTIONS environment variable content is treated in the same manner
234 as that specified in the command line.
235 Single (') or double (") quotes can be used to enclose arguments that
237 contain whitespace characters. All content between the open quote and
238 the first matching close quote are preserved by simply removing the
239 pair of quotes. In case a matching quote is not found, the launcher
240 will abort with an error message. @-files are supported as they are
241 specified in the command line. However, as in @-files, use of a wild‐
242 card is not supported. In order to mitigate potential misuse of
243 JDK_JAVA_OPTIONS behavior, options that specify the main class (such as
244 -jar) or cause the java launcher to exit without executing the main
245 class (such as -h) are disallowed in the environment variable. If any
246 of these options appear in the environment variable, the launcher will
247 abort with an error message. When JDK_JAVA_OPTIONS is set, the launch‐
248 er prints a message to stderr as a reminder.
249 Example:
251 $ export JDK_JAVA_OPTIONS='-g @file1 -Dprop=value @file2 -Dws.prop="white spaces"'
253 $ java -Xint @file3
254 is equivalent to the command line:
256 java -g @file1 -Dprop=value @file2 -Dws.prop="white spaces" -Xint @file3
258
260 The java command supports a wide range of options in the following cat‐
261 egories:
262 • Standard Options for Java: Options guaranteed to be supported by all
264 implementations of the Java Virtual Machine (JVM). They're used for
265 common actions, such as checking the version of the JRE, setting the
266 class path, enabling verbose output, and so on.
267 • Extra Options for Java: General purpose options that are specific to
269 the Java HotSpot Virtual Machine. They aren't guaranteed to be sup‐
270 ported by all JVM implementations, and are subject to change. These
271 options start with -X.
272 The advanced options aren't recommended for casual use. These are de‐
274 veloper options used for tuning specific areas of the Java HotSpot Vir‐
275 tual Machine operation that often have specific system requirements and
276 may require privileged access to system configuration parameters. Sev‐
277 eral examples of performance tuning are provided in Performance Tuning
278 Examples. These options aren't guaranteed to be supported by all JVM
279 implementations and are subject to change. Advanced options start with
280 -XX.
281 • Advanced Runtime Options for Java: Control the runtime behavior of
283 the Java HotSpot VM.
284 • Advanced JIT Compiler Options for java: Control the dynamic
286 just-in-time (JIT) compilation performed by the Java HotSpot VM.
287 • Advanced Serviceability Options for Java: Enable gathering system in‐
289 formation and performing extensive debugging.
290 • Advanced Garbage Collection Options for Java: Control how garbage
292 collection (GC) is performed by the Java HotSpot
293 Boolean options are used to either enable a feature that's disabled by
295 default or disable a feature that's enabled by default. Such options
296 don't require a parameter. Boolean -XX options are enabled using the
297 plus sign (-XX:+OptionName) and disabled using the minus sign (-XX:-Op‐
298 tionName).
299 For options that require an argument, the argument may be separated
301 from the option name by a space, a colon (:), or an equal sign (=), or
302 the argument may directly follow the option (the exact syntax differs
303 for each option). If you're expected to specify the size in bytes,
304 then you can use no suffix, or use the suffix k or K for kilobytes
305 (KB), m or M for megabytes (MB), or g or G for gigabytes (GB). For ex‐
306 ample, to set the size to 8 GB, you can specify either 8g, 8192m,
307 8388608k, or 8589934592 as the argument. If you are expected to speci‐
308 fy the percentage, then use a number from 0 to 1. For example, specify
309 0.25 for 25%.
310 The following sections describe the options that are obsolete, depre‐
312 cated, and removed:
313 • Deprecated Java Options: Accepted and acted upon --- a warning is is‐
315 sued when they're used.
316 • Obsolete Java Options: Accepted but ignored --- a warning is issued
318 when they're used.
319 • Removed Java Options: Removed --- using them results in an error.
321
323 These are the most commonly used options supported by all implementa‐
324 tions of the JVM.
325 Note: To specify an argument for a long option, you can use ei‐
327 ther --name=value or --name value.
328 -agentlib:libname[=options]
330 Loads the specified native agent library. After the library
331 name, a comma-separated list of options specific to the library
332 can be used.
333 • Linux and macOS: If the option -agentlib:foo is specified,
335 then the JVM attempts to load the library named libfoo.so in
336 the location specified by the LD_LIBRARY_PATH system variable
337 (on macOS this variable is DYLD_LIBRARY_PATH).
338 • Windows: If the option -agentlib:foo is specified, then the
340 JVM attempts to load the library named foo.dll in the location
341 specified by the PATH system variable.
342 The following example shows how to load the Java Debug Wire
344 Protocol (JDWP) library and listen for the socket connection
345 on port 8000, suspending the JVM before the main class loads:
346 -agentlib:jdwp=transport=dt_socket,server=y,ad‐
348 dress=8000
349 -agentpath:pathname[=options]
351 Loads the native agent library specified by the absolute path
352 name. This option is equivalent to -agentlib but uses the full
353 path and file name of the library.
354 --class-path classpath, -classpath classpath, or -cp classpath
356 A semicolon (;) separated list of directories, JAR archives, and
357 ZIP archives to search for class files.
358 Specifying classpath overrides any setting of the CLASSPATH en‐
360 vironment variable. If the class path option isn't used and
361 classpath isn't set, then the user class path consists of the
362 current directory (.).
363 As a special convenience, a class path element that contains a
365 base name of an asterisk (*) is considered equivalent to speci‐
366 fying a list of all the files in the directory with the exten‐
367 sion .jar or .JAR . A Java program can't tell the difference
368 between the two invocations. For example, if the directory my‐
369 dir contains a.jar and b.JAR, then the class path element my‐
370 dir/* is expanded to A.jar:b.JAR, except that the order of JAR
371 files is unspecified. All .jar files in the specified directo‐
372 ry, even hidden ones, are included in the list. A class path
373 entry consisting of an asterisk (*) expands to a list of all the
374 jar files in the current directory. The CLASSPATH environment
375 variable, where defined, is similarly expanded. Any class path
376 wildcard expansion that occurs before the Java VM is started.
377 Java programs never see wildcards that aren't expanded except by
378 querying the environment, such as by calling Sys‐
379 tem.getenv("CLASSPATH").
380 --disable-@files
382 Can be used anywhere on the command line, including in an argu‐
383 ment file, to prevent further @filename expansion. This option
384 stops expanding @-argfiles after the option.
385 --enable-preview
387 Allows classes to depend on preview features [https://docs.ora‐
388 cle.com/en/java/javase/12/language/index.html#JS‐
389 LAN-GUID-5A82FE0E-0CA4-4F1F-B075-564874FE2823] of the release.
390 --finalization=value
392 Controls whether the JVM performs finalization of objects.
393 Valid values are "enabled" and "disabled". Finalization is en‐
394 abled by default, so the value "enabled" does nothing. The val‐
395 ue "disabled" disables finalization, so that no finalizers are
396 invoked.
397 --module-path modulepath... or -p modulepath
399 A semicolon (;) separated list of directories in which each di‐
400 rectory is a directory of modules.
401 --upgrade-module-path modulepath...
403 A semicolon (;) separated list of directories in which each di‐
404 rectory is a directory of modules that replace upgradeable mod‐
405 ules in the runtime image.
406 --add-modules module[,module...]
408 Specifies the root modules to resolve in addition to the initial
409 module. module also can be ALL-DEFAULT, ALL-SYSTEM, and
410 ALL-MODULE-PATH.
411 --list-modules
413 Lists the observable modules and then exits.
414 -d module_name or --describe-module module_name
416 Describes a specified module and then exits.
417 --dry-run
419 Creates the VM but doesn't execute the main method. This
420 --dry-run option might be useful for validating the command-line
421 options such as the module system configuration.
422 --validate-modules
424 Validates all modules and exit. This option is helpful for
425 finding conflicts and other errors with modules on the module
426 path.
427 -Dproperty=value
429 Sets a system property value. The property variable is a string
430 with no spaces that represents the name of the property. The
431 value variable is a string that represents the value of the
432 property. If value is a string with spaces, then enclose it in
433 quotation marks (for example -Dfoo="foo bar").
434 -disableassertions[:[packagename]...|:classname] or -da[:[package‐
436 name]...|:classname]
437 Disables assertions. By default, assertions are disabled in all
438 packages and classes. With no arguments, -disableassertions
439 (-da) disables assertions in all packages and classes. With the
440 packagename argument ending in ..., the switch disables asser‐
441 tions in the specified package and any subpackages. If the ar‐
442 gument is simply ..., then the switch disables assertions in the
443 unnamed package in the current working directory. With the
444 classname argument, the switch disables assertions in the speci‐
445 fied class.
446 The -disableassertions (-da) option applies to all class loaders
448 and to system classes (which don't have a class loader).
449 There's one exception to this rule: If the option is provided
450 with no arguments, then it doesn't apply to system classes.
451 This makes it easy to disable assertions in all classes except
452 for system classes. The -disablesystemassertions option enables
453 you to disable assertions in all system classes. To explicitly
454 enable assertions in specific packages or classes, use the -en‐
455 ableassertions (-ea) option. Both options can be used at the
456 same time. For example, to run the MyClass application with as‐
457 sertions enabled in the package com.wombat.fruitbat (and any
458 subpackages) but disabled in the class com.wombat.fruit‐
459 bat.Brickbat, use the following command:
460 java -ea:com.wombat.fruitbat... -da:com.wombat.fruit‐
462 bat.Brickbat MyClass
463 -disablesystemassertions or -dsa
465 Disables assertions in all system classes.
466 -enableassertions[:[packagename]...|:classname] or -ea[:[package‐
468 name]...|:classname]
469 Enables assertions. By default, assertions are disabled in all
470 packages and classes. With no arguments, -enableassertions
471 (-ea) enables assertions in all packages and classes. With the
472 packagename argument ending in ..., the switch enables asser‐
473 tions in the specified package and any subpackages. If the ar‐
474 gument is simply ..., then the switch enables assertions in the
475 unnamed package in the current working directory. With the
476 classname argument, the switch enables assertions in the speci‐
477 fied class.
478 The -enableassertions (-ea) option applies to all class loaders
480 and to system classes (which don't have a class loader).
481 There's one exception to this rule: If the option is provided
482 with no arguments, then it doesn't apply to system classes.
483 This makes it easy to enable assertions in all classes except
484 for system classes. The -enablesystemassertions option provides
485 a separate switch to enable assertions in all system classes.
486 To explicitly disable assertions in specific packages or class‐
487 es, use the -disableassertions (-da) option. If a single com‐
488 mand contains multiple instances of these switches, then they're
489 processed in order, before loading any classes. For example, to
490 run the MyClass application with assertions enabled only in the
491 package com.wombat.fruitbat (and any subpackages) but disabled
492 in the class com.wombat.fruitbat.Brickbat, use the following
493 command:
494 java -ea:com.wombat.fruitbat... -da:com.wombat.fruit‐
496 bat.Brickbat MyClass
497 -enablesystemassertions or -esa
499 Enables assertions in all system classes.
500 -help, -h, or -?
502 Prints the help message to the error stream.
503 --help Prints the help message to the output stream.
505 -javaagent:jarpath[=options]
507 Loads the specified Java programming language agent. See ja‐
508 va.lang.instrument.
509 --show-version
511 Prints the product version to the output stream and continues.
512 -showversion
514 Prints the product version to the error stream and continues.
515 --show-module-resolution
517 Shows module resolution output during startup.
518 -splash:imagepath
520 Shows the splash screen with the image specified by imagepath.
521 HiDPI scaled images are automatically supported and used if
522 available. The unscaled image file name, such as image.ext,
523 should always be passed as the argument to the -splash option.
524 The most appropriate scaled image provided is picked up automat‐
525 ically.
526 For example, to show the splash.gif file from the images direc‐
528 tory when starting your application, use the following option:
529 -splash:images/splash.gif
531 See the SplashScreen API documentation for more information.
533 -verbose:class
535 Displays information about each loaded class.
536 -verbose:gc
538 Displays information about each garbage collection (GC) event.
539 -verbose:jni
541 Displays information about the use of native methods and other
542 Java Native Interface (JNI) activity.
543 -verbose:module
545 Displays information about the modules in use.
546 --version
548 Prints product version to the output stream and exits.
549 -version
551 Prints product version to the error stream and exits.
552 -X Prints the help on extra options to the error stream.
554 --help-extra
556 Prints the help on extra options to the output stream.
557 @argfile
559 Specifies one or more argument files prefixed by @ used by the
560 java command. It isn't uncommon for the java command line to be
561 very long because of the .jar files needed in the classpath.
562 The @argfile option overcomes command-line length limitations by
563 enabling the launcher to expand the contents of argument files
564 after shell expansion, but before argument processing. Contents
565 in the argument files are expanded because otherwise, they would
566 be specified on the command line until the --disable-@files op‐
567 tion was encountered.
568 The argument files can also contain the main class name and all
570 options. If an argument file contains all of the options re‐
571 quired by the java command, then the command line could simply
572 be:
573 java @argfile
575 See java Command-Line Argument Files for a description and exam‐
577 ples of using @-argfiles.
578
580 The following java options are general purpose options that are specif‐
581 ic to the Java HotSpot Virtual Machine.
582 -Xbatch
584 Disables background compilation. By default, the JVM compiles
585 the method as a background task, running the method in inter‐
586 preter mode until the background compilation is finished. The
587 -Xbatch flag disables background compilation so that compilation
588 of all methods proceeds as a foreground task until completed.
589 This option is equivalent to -XX:-BackgroundCompilation.
590 -Xbootclasspath/a:directories|zip|JAR-files
592 Specifies a list of directories, JAR files, and ZIP archives to
593 append to the end of the default bootstrap class path.
594 Linux and macOS: Colons (:) separate entities in this list.
596 Windows: Semicolons (;) separate entities in this list.
598 -Xcheck:jni
600 Performs additional checks for Java Native Interface (JNI) func‐
601 tions.
602 The following checks are considered indicative of significant
604 problems with the native code, and the JVM terminates with an
605 irrecoverable error in such cases:
606 • The thread doing the call is not attached to the JVM.
608 • The thread doing the call is using the JNIEnv belonging to an‐
610 other thread.
611 • A parameter validation check fails:
613 • A jfieldID, or jmethodID, is detected as being invalid. For
615 example:
616 • Of the wrong type
618 • Associated with the wrong class
620 • A parameter of the wrong type is detected.
622 • An invalid parameter value is detected. For example:
624 • NULL where not permitted
626 • An out-of-bounds array index, or frame capacity
628 • A non-UTF-8 string
630 • An invalid JNI reference
632 • An attempt to use a ReleaseXXX function on a parameter not
634 produced by the corresponding GetXXX function
635 The following checks only result in warnings being printed:
637 • A JNI call was made without checking for a pending exception
639 from a previous JNI call, and the current call is not safe
640 when an exception may be pending.
641 • The number of JNI local references existing when a JNI func‐
643 tion terminates exceeds the number guaranteed to be available.
644 See the EnsureLocalcapacity function.
645 • A class descriptor is in decorated format (Lname;) when it
647 should not be.
648 • A NULL parameter is allowed, but its use is questionable.
650 • Calling other JNI functions in the scope of Get/ReleasePrimi‐
652 tiveArrayCritical or Get/ReleaseStringCritical
653 Expect a performance degradation when this option is used.
655 -Xdebug
657 Does nothing. Provided for backward compatibility.
658 -Xdiag Shows additional diagnostic messages.
660 -Xint Runs the application in interpreted-only mode. Compilation to
662 native code is disabled, and all bytecode is executed by the in‐
663 terpreter. The performance benefits offered by the just-in-time
664 (JIT) compiler aren't present in this mode.
665 -Xinternalversion
667 Displays more detailed JVM version information than the -version
668 option, and then exits.
669 -Xlog:option
671 Configure or enable logging with the Java Virtual Machine (JVM)
672 unified logging framework. See Enable Logging with the JVM Uni‐
673 fied Logging Framework.
674 -Xmixed
676 Executes all bytecode by the interpreter except for hot methods,
677 which are compiled to native code. On by default. Use -Xint to
678 switch off.
679 -Xmn size
681 Sets the initial and maximum size (in bytes) of the heap for the
682 young generation (nursery) in the generational collectors. Ap‐
683 pend the letter k or K to indicate kilobytes, m or M to indicate
684 megabytes, or g or G to indicate gigabytes. The young genera‐
685 tion region of the heap is used for new objects. GC is per‐
686 formed in this region more often than in other regions. If the
687 size for the young generation is too small, then a lot of minor
688 garbage collections are performed. If the size is too large,
689 then only full garbage collections are performed, which can take
690 a long time to complete. It is recommended that you do not set
691 the size for the young generation for the G1 collector, and keep
692 the size for the young generation greater than 25% and less than
693 50% of the overall heap size for other collectors. The follow‐
694 ing examples show how to set the initial and maximum size of
695 young generation to 256 MB using various units:
696 -Xmn256m
698 -Xmn262144k
699 -Xmn268435456
700 Instead of the -Xmn option to set both the initial and maximum
702 size of the heap for the young generation, you can use -XX:New‐
703 Size to set the initial size and -XX:MaxNewSize to set the maxi‐
704 mum size.
705 -Xms size
707 Sets the minimum and the initial size (in bytes) of the heap.
708 This value must be a multiple of 1024 and greater than 1 MB.
709 Append the letter k or K to indicate kilobytes, m or M to indi‐
710 cate megabytes, or g or G to indicate gigabytes. The following
711 examples show how to set the size of allocated memory to 6 MB
712 using various units:
713 -Xms6291456
715 -Xms6144k
716 -Xms6m
717 If you do not set this option, then the initial size will be set
719 as the sum of the sizes allocated for the old generation and the
720 young generation. The initial size of the heap for the young
721 generation can be set using the -Xmn option or the -XX:NewSize
722 option.
723 Note that the -XX:InitialHeapSize option can also be used to set
725 the initial heap size. If it appears after -Xms on the command
726 line, then the initial heap size gets set to the value specified
727 with -XX:InitialHeapSize.
728 -Xmx size
730 Specifies the maximum size (in bytes) of the heap. This value
731 must be a multiple of 1024 and greater than 2 MB. Append the
732 letter k or K to indicate kilobytes, m or M to indicate
733 megabytes, or g or G to indicate gigabytes. The default value
734 is chosen at runtime based on system configuration. For server
735 deployments, -Xms and -Xmx are often set to the same value. The
736 following examples show how to set the maximum allowed size of
737 allocated memory to 80 MB using various units:
738 -Xmx83886080
740 -Xmx81920k
741 -Xmx80m
742 The -Xmx option is equivalent to -XX:MaxHeapSize.
744 -Xnoclassgc
746 Disables garbage collection (GC) of classes. This can save some
747 GC time, which shortens interruptions during the application
748 run. When you specify -Xnoclassgc at startup, the class objects
749 in the application are left untouched during GC and are always
750 be considered live. This can result in more memory being perma‐
751 nently occupied which, if not used carefully, throws an
752 out-of-memory exception.
753 -Xrs Reduces the use of operating system signals by the JVM. Shut‐
755 down hooks enable the orderly shutdown of a Java application by
756 running user cleanup code (such as closing database connections)
757 at shutdown, even if the JVM terminates abruptly.
758 • Linux and macOS:
760 • The JVM catches signals to implement shutdown hooks for un‐
762 expected termination. The JVM uses SIGHUP, SIGINT, and
763 SIGTERM to initiate the running of shutdown hooks.
764 • Applications embedding the JVM frequently need to trap sig‐
766 nals such as SIGINT or SIGTERM, which can lead to interfer‐
767 ence with the JVM signal handlers. The -Xrs option is
768 available to address this issue. When -Xrs is used, the
769 signal masks for SIGINT, SIGTERM, SIGHUP, and SIGQUIT aren't
770 changed by the JVM, and signal handlers for these signals
771 aren't installed.
772 • Windows:
774 • The JVM watches for console control events to implement
776 shutdown hooks for unexpected termination. Specifically,
777 the JVM registers a console control handler that begins
778 shutdown-hook processing and returns TRUE for CTRL_C_EVENT,
779 CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUT‐
780 DOWN_EVENT.
781 • The JVM uses a similar mechanism to implement the feature of
783 dumping thread stacks for debugging purposes. The JVM uses
784 CTRL_BREAK_EVENT to perform thread dumps.
785 • If the JVM is run as a service (for example, as a servlet
787 engine for a web server), then it can receive CTRL_LO‐
788 GOFF_EVENT but shouldn't initiate shutdown because the oper‐
789 ating system doesn't actually terminate the process. To
790 avoid possible interference such as this, the -Xrs option
791 can be used. When the -Xrs option is used, the JVM doesn't
792 install a console control handler, implying that it doesn't
793 watch for or process CTRL_C_EVENT, CTRL_CLOSE_EVENT,
794 CTRL_LOGOFF_EVENT, or CTRL_SHUTDOWN_EVENT.
795 There are two consequences of specifying -Xrs:
797 • Linux and macOS: SIGQUIT thread dumps aren't available.
799 • Windows: Ctrl + Break thread dumps aren't available.
801 User code is responsible for causing shutdown hooks to run, for
803 example, by calling the System.exit() when the JVM is to be ter‐
804 minated.
805 -Xshare:mode
807 Sets the class data sharing (CDS) mode.
808 Possible mode arguments for this option include the following:
810 auto Use shared class data if possible (default).
812 on Require using shared class data, otherwise fail.
814 Note: The -Xshare:on option is used for testing purposes
816 only and may cause intermittent failures due to the use
817 of address space layout randomization by the operation
818 system. This option should not be used in production en‐
819 vironments.
820 off Do not attempt to use shared class data.
822 -XshowSettings
824 Shows all settings and then continues.
825 -XshowSettings:category
827 Shows settings and continues. Possible category arguments for
828 this option include the following:
829 all Shows all categories of settings. This is the default
831 value.
832 locale Shows settings related to locale.
834 properties
836 Shows settings related to system properties.
837 vm Shows the settings of the JVM.
839 system Linux: Shows host system or container configuration and
841 continues.
842 -Xss size
844 Sets the thread stack size (in bytes). Append the letter k or K
845 to indicate KB, m or M to indicate MB, or g or G to indicate GB.
846 The default value depends on the platform:
847 • Linux/x64 (64-bit): 1024 KB
849 • macOS (64-bit): 1024 KB
851 • Windows: The default value depends on virtual memory
853 The following examples set the thread stack size to 1024 KB in
855 different units:
856 -Xss1m
858 -Xss1024k
859 -Xss1048576
860 This option is similar to -XX:ThreadStackSize.
862 --add-reads module=target-module(,target-module)*
864 Updates module to read the target-module, regardless of the mod‐
865 ule declaration. target-module can be all unnamed to read all
866 unnamed modules.
867 --add-exports module/package=target-module(,target-module)*
869 Updates module to export package to target-module, regardless of
870 module declaration. The target-module can be all unnamed to ex‐
871 port to all unnamed modules.
872 --add-opens module/package=target-module(,target-module)*
874 Updates module to open package to target-module, regardless of
875 module declaration.
876 --limit-modules module[,module...]
878 Specifies the limit of the universe of observable modules.
879 --patch-module module=file(;file)*
881 Overrides or augments a module with classes and resources in JAR
882 files or directories.
883 --source version
885 Sets the version of the source in source-file mode.
886
888 The following extra options are macOS specific.
889 -XstartOnFirstThread
891 Runs the main() method on the first (AppKit) thread.
892 -Xdock:name=application_name
894 Overrides the default application name displayed in dock.
895 -Xdock:icon=path_to_icon_file
897 Overrides the default icon displayed in dock.
898
900 These java options can be used to enable other advanced options.
901 -XX:+UnlockDiagnosticVMOptions
903 Unlocks the options intended for diagnosing the JVM. By de‐
904 fault, this option is disabled and diagnostic options aren't
905 available.
906 Command line options that are enabled with the use of this op‐
908 tion are not supported. If you encounter issues while using any
909 of these options, it is very likely that you will be required to
910 reproduce the problem without using any of these unsupported op‐
911 tions before Oracle Support can assist with an investigation.
912 It is also possible that any of these options may be removed or
913 their behavior changed without any warning.
914 -XX:+UnlockExperimentalVMOptions
916 Unlocks the options that provide experimental features in the
917 JVM. By default, this option is disabled and experimental fea‐
918 tures aren't available.
919
921 These java options control the runtime behavior of the Java HotSpot VM.
922 -XX:ActiveProcessorCount=x
924 Overrides the number of CPUs that the VM will use to calculate
925 the size of thread pools it will use for various operations such
926 as Garbage Collection and ForkJoinPool.
927 The VM normally determines the number of available processors
929 from the operating system. This flag can be useful for parti‐
930 tioning CPU resources when running multiple Java processes in
931 docker containers. This flag is honored even if UseContainer‐
932 Support is not enabled. See -XX:-UseContainerSupport for a de‐
933 scription of enabling and disabling container support.
934 -XX:AllocateHeapAt=path
936 Takes a path to the file system and uses memory mapping to allo‐
937 cate the object heap on the memory device. Using this option
938 enables the HotSpot VM to allocate the Java object heap on an
939 alternative memory device, such as an NV-DIMM, specified by the
940 user.
941 Alternative memory devices that have the same semantics as DRAM,
943 including the semantics of atomic operations, can be used in‐
944 stead of DRAM for the object heap without changing the existing
945 application code. All other memory structures (such as the code
946 heap, metaspace, and thread stacks) continue to reside in DRAM.
947 Some operating systems expose non-DRAM memory through the file
949 system. Memory-mapped files in these file systems bypass the
950 page cache and provide a direct mapping of virtual memory to the
951 physical memory on the device. The existing heap related flags
952 (such as -Xmx and -Xms) and garbage-collection related flags
953 continue to work as before.
954 -XX:-CompactStrings
956 Disables the Compact Strings feature. By default, this option
957 is enabled. When this option is enabled, Java Strings contain‐
958 ing only single-byte characters are internally represented and
959 stored as single-byte-per-character Strings using ISO-8859-1 /
960 Latin-1 encoding. This reduces, by 50%, the amount of space re‐
961 quired for Strings containing only single-byte characters. For
962 Java Strings containing at least one multibyte character: these
963 are represented and stored as 2 bytes per character using UTF-16
964 encoding. Disabling the Compact Strings feature forces the use
965 of UTF-16 encoding as the internal representation for all Java
966 Strings.
967 Cases where it may be beneficial to disable Compact Strings in‐
969 clude the following:
970 • When it's known that an application overwhelmingly will be al‐
972 locating multibyte character Strings
973 • In the unexpected event where a performance regression is ob‐
975 served in migrating from Java SE 8 to Java SE 9 and an analy‐
976 sis shows that Compact Strings introduces the regression
977 In both of these scenarios, disabling Compact Strings makes
979 sense.
980 -XX:ErrorFile=filename
982 Specifies the path and file name to which error data is written
983 when an irrecoverable error occurs. By default, this file is
984 created in the current working directory and named hs_err_pid‐
985 pid.log where pid is the identifier of the process that encoun‐
986 tered the error.
987 The following example shows how to set the default log file
989 (note that the identifier of the process is specified as %p):
990 -XX:ErrorFile=./hs_err_pid%p.log
992 • Linux and macOS: The following example shows how to set the
994 error log to /var/log/java/java_error.log:
995 -XX:ErrorFile=/var/log/java/java_error.log
997 • Windows: The following example shows how to set the error log
999 file to C:/log/java/java_error.log:
1000 -XX:ErrorFile=C:/log/java/java_error.log
1002 If the file exists, and is writeable, then it will be overwrit‐
1004 ten. Otherwise, if the file can't be created in the specified
1005 directory (due to insufficient space, permission problem, or an‐
1006 other issue), then the file is created in the temporary directo‐
1007 ry for the operating system:
1008 • Linux and macOS: The temporary directory is /tmp.
1010 • Windows: The temporary directory is specified by the value of
1012 the TMP environment variable; if that environment variable
1013 isn't defined, then the value of the TEMP environment variable
1014 is used.
1015 -XX:+ExtensiveErrorReports
1017 Enables the reporting of more extensive error information in the
1018 ErrorFile. This option can be turned on in environments where
1019 maximal information is desired - even if the resulting logs may
1020 be quite large and/or contain information that might be consid‐
1021 ered sensitive. The information can vary from release to re‐
1022 lease, and across different platforms. By default this option
1023 is disabled.
1024 -XX:FlightRecorderOptions=parameter=value (or) -XX:FlightRecorderOp‐
1026 tions:parameter=value
1027 Sets the parameters that control the behavior of JFR.
1028 The following list contains the available JFR parameter=value
1030 entries:
1031 globalbuffersize=size
1033 Specifies the total amount of primary memory used for da‐
1034 ta retention. The default value is based on the value
1035 specified for memorysize. Change the memorysize parame‐
1036 ter to alter the size of global buffers.
1037 maxchunksize=size
1039 Specifies the maximum size (in bytes) of the data chunks
1040 in a recording. Append m or M to specify the size in
1041 megabytes (MB), or g or G to specify the size in giga‐
1042 bytes (GB). By default, the maximum size of data chunks
1043 is set to 12 MB. The minimum allowed is 1 MB.
1044 memorysize=size
1046 Determines how much buffer memory should be used, and
1047 sets the globalbuffersize and numglobalbuffers parameters
1048 based on the size specified. Append m or M to specify
1049 the size in megabytes (MB), or g or G to specify the size
1050 in gigabytes (GB). By default, the memory size is set to
1051 10 MB.
1052 numglobalbuffers
1054 Specifies the number of global buffers used. The default
1055 value is based on the memory size specified. Change the
1056 memorysize parameter to alter the number of global buf‐
1057 fers.
1058 old-object-queue-size=number-of-objects
1060 Maximum number of old objects to track. By default, the
1061 number of objects is set to 256.
1062 repository=path
1064 Specifies the repository (a directory) for temporary disk
1065 storage. By default, the system's temporary directory is
1066 used.
1067 retransform={true|false}
1069 Specifies whether event classes should be retransformed
1070 using JVMTI. If false, instrumentation is added when
1071 event classes are loaded. By default, this parameter is
1072 enabled.
1073 samplethreads={true|false}
1075 Specifies whether thread sampling is enabled. Thread
1076 sampling occurs only if the sampling event is enabled
1077 along with this parameter. By default, this parameter is
1078 enabled.
1079 stackdepth=depth
1081 Stack depth for stack traces. By default, the depth is
1082 set to 64 method calls. The maximum is 2048. Values
1083 greater than 64 could create significant overhead and re‐
1084 duce performance.
1085 threadbuffersize=size
1087 Specifies the per-thread local buffer size (in bytes).
1088 By default, the local buffer size is set to 8 kilobytes,
1089 with a minimum value of 4 kilobytes. Overriding this pa‐
1090 rameter could reduce performance and is not recommended.
1091 You can specify values for multiple parameters by separating
1093 them with a comma.
1094 -XX:LargePageSizeInBytes=size
1096 Sets the maximum large page size (in bytes) used by the JVM.
1097 The size argument must be a valid page size supported by the en‐
1098 vironment to have any effect. Append the letter k or K to indi‐
1099 cate kilobytes, m or M to indicate megabytes, or g or G to indi‐
1100 cate gigabytes. By default, the size is set to 0, meaning that
1101 the JVM will use the default large page size for the environment
1102 as the maximum size for large pages. See Large Pages.
1103 The following example describes how to set the large page size
1105 to 1 gigabyte (GB):
1106 -XX:LargePageSizeInBytes=1g
1108 -XX:MaxDirectMemorySize=size
1110 Sets the maximum total size (in bytes) of the java.nio package,
1111 direct-buffer allocations. Append the letter k or K to indicate
1112 kilobytes, m or M to indicate megabytes, or g or G to indicate
1113 gigabytes. By default, the size is set to 0, meaning that the
1114 JVM chooses the size for NIO direct-buffer allocations automati‐
1115 cally.
1116 The following examples illustrate how to set the NIO size to
1118 1024 KB in different units:
1119 -XX:MaxDirectMemorySize=1m
1121 -XX:MaxDirectMemorySize=1024k
1122 -XX:MaxDirectMemorySize=1048576
1123 -XX:-MaxFDLimit
1125 Disables the attempt to set the soft limit for the number of
1126 open file descriptors to the hard limit. By default, this op‐
1127 tion is enabled on all platforms, but is ignored on Windows.
1128 The only time that you may need to disable this is on Mac OS,
1129 where its use imposes a maximum of 10240, which is lower than
1130 the actual system maximum.
1131 -XX:NativeMemoryTracking=mode
1133 Specifies the mode for tracking JVM native memory usage. Possi‐
1134 ble mode arguments for this option include the following:
1135 off Instructs not to track JVM native memory usage. This is
1137 the default behavior if you don't specify the -XX:Native‐
1138 MemoryTracking option.
1139 summary
1141 Tracks memory usage only by JVM subsystems, such as Java
1142 heap, class, code, and thread.
1143 detail In addition to tracking memory usage by JVM subsystems,
1145 track memory usage by individual CallSite, individual
1146 virtual memory region and its committed regions.
1147 -XX:+NeverActAsServerClassMachine
1149 Enable the "Client VM emulation" mode which only uses the C1 JIT
1150 compiler, a 32Mb CodeCache and the Serial GC. The maximum
1151 amount of memory that the JVM may use (controlled by the
1152 -XX:MaxRAM=n flag) is set to 1GB by default. The string "emu‐
1153 lated-client" is added to the JVM version string.
1154 By default the flag is set to true only on Windows in 32-bit
1156 mode and false in all other cases.
1157 The "Client VM emulation" mode will not be enabled if any of the
1159 following flags are used on the command line:
1160 -XX:{+|-}TieredCompilation
1162 -XX:CompilationMode=mode
1163 -XX:TieredStopAtLevel=n
1164 -XX:{+|-}EnableJVMCI
1165 -XX:{+|-}UseJVMCICompiler
1166 -XX:ObjectAlignmentInBytes=alignment
1168 Sets the memory alignment of Java objects (in bytes). By de‐
1169 fault, the value is set to 8 bytes. The specified value should
1170 be a power of 2, and must be within the range of 8 and 256 (in‐
1171 clusive). This option makes it possible to use compressed
1172 pointers with large Java heap sizes.
1173 The heap size limit in bytes is calculated as:
1175 4GB * ObjectAlignmentInBytes
1177 Note: As the alignment value increases, the unused space
1179 between objects also increases. As a result, you may not
1180 realize any benefits from using compressed pointers with
1181 large Java heap sizes.
1182 -XX:OnError=string
1184 Sets a custom command or a series of semicolon-separated com‐
1185 mands to run when an irrecoverable error occurs. If the string
1186 contains spaces, then it must be enclosed in quotation marks.
1187 • Linux and macOS: The following example shows how the -XX:On‐
1189 Error option can be used to run the gcore command to create a
1190 core image, and start the gdb debugger to attach to the
1191 process in case of an irrecoverable error (the %p designates
1192 the current process identifier):
1193 -XX:OnError="gcore %p;gdb -p %p"
1195 • Windows: The following example shows how the -XX:OnError op‐
1197 tion can be used to run the userdump.exe utility to obtain a
1198 crash dump in case of an irrecoverable error (the %p desig‐
1199 nates the current process identifier). This example assumes
1200 that the path to the userdump.exe utility is specified in the
1201 PATH environment variable:
1202 -XX:OnError="userdump.exe %p"
1204 -XX:OnOutOfMemoryError=string
1206 Sets a custom command or a series of semicolon-separated com‐
1207 mands to run when an OutOfMemoryError exception is first thrown.
1208 If the string contains spaces, then it must be enclosed in quo‐
1209 tation marks. For an example of a command string, see the de‐
1210 scription of the -XX:OnError option.
1211 -XX:+PrintCommandLineFlags
1213 Enables printing of ergonomically selected JVM flags that ap‐
1214 peared on the command line. It can be useful to know the ergo‐
1215 nomic values set by the JVM, such as the heap space size and the
1216 selected garbage collector. By default, this option is disabled
1217 and flags aren't printed.
1218 -XX:+PreserveFramePointer
1220 Selects between using the RBP register as a general purpose reg‐
1221 ister (-XX:-PreserveFramePointer) and using the RBP register to
1222 hold the frame pointer of the currently executing method
1223 (-XX:+PreserveFramePointer . If the frame pointer is available,
1224 then external profiling tools (for example, Linux perf) can con‐
1225 struct more accurate stack traces.
1226 -XX:+PrintNMTStatistics
1228 Enables printing of collected native memory tracking data at JVM
1229 exit when native memory tracking is enabled (see -XX:NativeMemo‐
1230 ryTracking). By default, this option is disabled and native
1231 memory tracking data isn't printed.
1232 -XX:SharedArchiveFile=path
1234 Specifies the path and name of the class data sharing (CDS) ar‐
1235 chive file
1236 See Application Class Data Sharing.
1238 -XX:SharedArchiveConfigFile=shared_config_file
1240 Specifies additional shared data added to the archive file.
1241 -XX:SharedClassListFile=file_name
1243 Specifies the text file that contains the names of the classes
1244 to store in the class data sharing (CDS) archive. This file
1245 contains the full name of one class per line, except slashes (/)
1246 replace dots (.). For example, to specify the classes ja‐
1247 va.lang.Object and hello.Main, create a text file that contains
1248 the following two lines:
1249 java/lang/Object
1251 hello/Main
1252 The classes that you specify in this text file should include
1254 the classes that are commonly used by the application. They may
1255 include any classes from the application, extension, or boot‐
1256 strap class paths.
1257 See Application Class Data Sharing.
1259 -XX:+ShowCodeDetailsInExceptionMessages
1261 Enables printing of improved NullPointerException messages.
1262 When an application throws a NullPointerException, the option
1263 enables the JVM to analyze the program's bytecode instructions
1264 to determine precisely which reference is null, and describes
1265 the source with a null-detail message. The null-detail message
1266 is calculated and returned by NullPointerException.getMessage(),
1267 and will be printed as the exception message along with the
1268 method, filename, and line number. By default, this option is
1269 enabled.
1270 -XX:+ShowMessageBoxOnError
1272 Enables the display of a dialog box when the JVM experiences an
1273 irrecoverable error. This prevents the JVM from exiting and
1274 keeps the process active so that you can attach a debugger to it
1275 to investigate the cause of the error. By default, this option
1276 is disabled.
1277 -XX:StartFlightRecording=parameter=value
1279 Starts a JFR recording for the Java application. This option is
1280 equivalent to the JFR.start diagnostic command that starts a
1281 recording during runtime. You can set the following parame‐
1282 ter=value entries when starting a JFR recording:
1283 delay=time
1285 Specifies the delay between the Java application launch
1286 time and the start of the recording. Append s to specify
1287 the time in seconds, m for minutes, h for hours, or d for
1288 days (for example, specifying 10m means 10 minutes). By
1289 default, there's no delay, and this parameter is set to
1290 0.
1291 disk={true|false}
1293 Specifies whether to write data to disk while recording.
1294 By default, this parameter is enabled.
1295 dumponexit={true|false}
1297 Specifies if the running recording is dumped when the JVM
1298 shuts down. If enabled and a filename is not entered,
1299 the recording is written to a file in the directory where
1300 the process was started. The file name is a system-gen‐
1301 erated name that contains the process ID, recording ID,
1302 and current timestamp, similar to
1303 hotspot-pid-47496-id-1-2018_01_25_19_10_41.jfr. By de‐
1304 fault, this parameter is disabled.
1305 duration=time
1307 Specifies the duration of the recording. Append s to
1308 specify the time in seconds, m for minutes, h for hours,
1309 or d for days (for example, specifying 5h means 5 hours).
1310 By default, the duration isn't limited, and this parame‐
1311 ter is set to 0.
1312 filename=path
1314 Specifies the path and name of the file to which the
1315 recording is written when the recording is stopped, for
1316 example:
1317 • recording.jfr
1319 • /home/user/recordings/recording.jfr
1321 • c:\recordings\recording.jfr
1323 name=identifier
1325 Takes both the name and the identifier of a recording.
1326 maxage=time
1328 Specifies the maximum age of disk data to keep for the
1329 recording. This parameter is valid only when the disk
1330 parameter is set to true. Append s to specify the time
1331 in seconds, m for minutes, h for hours, or d for days
1332 (for example, specifying 30s means 30 seconds). By de‐
1333 fault, the maximum age isn't limited, and this parameter
1334 is set to 0s.
1335 maxsize=size
1337 Specifies the maximum size (in bytes) of disk data to
1338 keep for the recording. This parameter is valid only
1339 when the disk parameter is set to true. The value must
1340 not be less than the value for the maxchunksize parameter
1341 set with -XX:FlightRecorderOptions. Append m or M to
1342 specify the size in megabytes, or g or G to specify the
1343 size in gigabytes. By default, the maximum size of disk
1344 data isn't limited, and this parameter is set to 0.
1345 path-to-gc-roots={true|false}
1347 Specifies whether to collect the path to garbage collec‐
1348 tion (GC) roots at the end of a recording. By default,
1349 this parameter is disabled.
1350 The path to GC roots is useful for finding memory leaks,
1352 but collecting it is time-consuming. Enable this option
1353 only when you start a recording for an application that
1354 you suspect has a memory leak. If the settings parameter
1355 is set to profile, the stack trace from where the poten‐
1356 tial leaking object was allocated is included in the in‐
1357 formation collected.
1358 settings=path
1360 Specifies the path and name of the event settings file
1361 (of type JFC). By default, the default.jfc file is used,
1362 which is located in JAVA_HOME/lib/jfr. This default set‐
1363 tings file collects a predefined set of information with
1364 low overhead, so it has minimal impact on performance and
1365 can be used with recordings that run continuously.
1366 A second settings file is also provided, profile.jfc,
1368 which provides more data than the default configuration,
1369 but can have more overhead and impact performance. Use
1370 this configuration for short periods of time when more
1371 information is needed.
1372 You can specify values for multiple parameters by separating
1374 them with a comma. Event settings and .jfc options can be spec‐
1375 ified using the following syntax:
1376 option=value
1378 Specifies the option value to modify. To list available
1379 options, use the JAVA_HOME/bin/jfr tool.
1380 event-setting=value
1382 Specifies the event setting value to modify. Use the
1383 form: <event-name>#<setting-name>=<value>. To add a new
1384 event setting, prefix the event name with '+'.
1385 You can specify values for multiple event settings and .jfc op‐
1387 tions by separating them with a comma. In case of a conflict
1388 between a parameter and a .jfc option, the parameter will take
1389 precedence. The whitespace delimiter can be omitted for times‐
1390 pan values, i.e. 20ms. For more information about the settings
1391 syntax, see Javadoc of the jdk.jfr package.
1392 -XX:ThreadStackSize=size
1394 Sets the Java thread stack size (in kilobytes). Use of a scal‐
1395 ing suffix, such as k, results in the scaling of the kilobytes
1396 value so that -XX:ThreadStackSize=1k sets the Java thread stack
1397 size to 1024*1024 bytes or 1 megabyte. The default value de‐
1398 pends on the platform:
1399 • Linux/x64 (64-bit): 1024 KB
1401 • macOS (64-bit): 1024 KB
1403 • Windows: The default value depends on virtual memory
1405 The following examples show how to set the thread stack size to
1407 1 megabyte in different units:
1408 -XX:ThreadStackSize=1k
1410 -XX:ThreadStackSize=1024
1411 This option is similar to -Xss.
1413 -XX:-UseCompressedOops
1415 Disables the use of compressed pointers. By default, this op‐
1416 tion is enabled, and compressed pointers are used. This will
1417 automatically limit the maximum ergonomically determined Java
1418 heap size to the maximum amount of memory that can be covered by
1419 compressed pointers. By default this range is 32 GB.
1420 With compressed oops enabled, object references are represented
1422 as 32-bit offsets instead of 64-bit pointers, which typically
1423 increases performance when running the application with Java
1424 heap sizes smaller than the compressed oops pointer range. This
1425 option works only for 64-bit JVMs.
1426 It's possible to use compressed pointers with Java heap sizes
1428 greater than 32 GB. See the -XX:ObjectAlignmentInBytes option.
1429 -XX:-UseContainerSupport
1431 The VM now provides automatic container detection support, which
1432 allows the VM to determine the amount of memory and number of
1433 processors that are available to a Java process running in dock‐
1434 er containers. It uses this information to allocate system re‐
1435 sources. This support is only available on Linux x64 platforms.
1436 If supported, the default for this flag is true, and container
1437 support is enabled by default. It can be disabled with
1438 -XX:-UseContainerSupport.
1439 Unified Logging is available to help to diagnose issues related
1441 to this support.
1442 Use -Xlog:os+container=trace for maximum logging of container
1444 information. See Enable Logging with the JVM Unified Logging
1445 Framework for a description of using Unified Logging.
1446 -XX:+UseHugeTLBFS
1448 Linux only: This option is the equivalent of specifying
1449 -XX:+UseLargePages. This option is disabled by default. This
1450 option pre-allocates all large pages up-front, when memory is
1451 reserved; consequently the JVM can't dynamically grow or shrink
1452 large pages memory areas; see -XX:UseTransparentHugePages if you
1453 want this behavior.
1454 See Large Pages.
1456 -XX:+UseLargePages
1458 Enables the use of large page memory. By default, this option
1459 is disabled and large page memory isn't used.
1460 See Large Pages.
1462 -XX:+UseTransparentHugePages
1464 Linux only: Enables the use of large pages that can dynamically
1465 grow or shrink. This option is disabled by default. You may
1466 encounter performance problems with transparent huge pages as
1467 the OS moves other pages around to create huge pages; this op‐
1468 tion is made available for experimentation.
1469 -XX:+AllowUserSignalHandlers
1471 Enables installation of signal handlers by the application. By
1472 default, this option is disabled and the application isn't al‐
1473 lowed to install signal handlers.
1474 -XX:VMOptionsFile=filename
1476 Allows user to specify VM options in a file, for example, ja‐
1477 va -XX:VMOptionsFile=/var/my_vm_options HelloWorld.
1478
1480 These java options control the dynamic just-in-time (JIT) compilation
1481 performed by the Java HotSpot VM.
1482 -XX:AllocateInstancePrefetchLines=lines
1484 Sets the number of lines to prefetch ahead of the instance allo‐
1485 cation pointer. By default, the number of lines to prefetch is
1486 set to 1:
1487 -XX:AllocateInstancePrefetchLines=1
1489 -XX:AllocatePrefetchDistance=size
1491 Sets the size (in bytes) of the prefetch distance for object al‐
1492 location. Memory about to be written with the value of new ob‐
1493 jects is prefetched up to this distance starting from the ad‐
1494 dress of the last allocated object. Each Java thread has its
1495 own allocation point.
1496 Negative values denote that prefetch distance is chosen based on
1498 the platform. Positive values are bytes to prefetch. Append
1499 the letter k or K to indicate kilobytes, m or M to indicate
1500 megabytes, or g or G to indicate gigabytes. The default value
1501 is set to -1.
1502 The following example shows how to set the prefetch distance to
1504 1024 bytes:
1505 -XX:AllocatePrefetchDistance=1024
1507 -XX:AllocatePrefetchInstr=instruction
1509 Sets the prefetch instruction to prefetch ahead of the alloca‐
1510 tion pointer. Possible values are from 0 to 3. The actual in‐
1511 structions behind the values depend on the platform. By de‐
1512 fault, the prefetch instruction is set to 0:
1513 -XX:AllocatePrefetchInstr=0
1515 -XX:AllocatePrefetchLines=lines
1517 Sets the number of cache lines to load after the last object al‐
1518 location by using the prefetch instructions generated in com‐
1519 piled code. The default value is 1 if the last allocated object
1520 was an instance, and 3 if it was an array.
1521 The following example shows how to set the number of loaded
1523 cache lines to 5:
1524 -XX:AllocatePrefetchLines=5
1526 -XX:AllocatePrefetchStepSize=size
1528 Sets the step size (in bytes) for sequential prefetch instruc‐
1529 tions. Append the letter k or K to indicate kilobytes, m or M
1530 to indicate megabytes, g or G to indicate gigabytes. By de‐
1531 fault, the step size is set to 16 bytes:
1532 -XX:AllocatePrefetchStepSize=16
1534 -XX:AllocatePrefetchStyle=style
1536 Sets the generated code style for prefetch instructions. The
1537 style argument is an integer from 0 to 3:
1538 0 Don't generate prefetch instructions.
1540 1 Execute prefetch instructions after each allocation.
1542 This is the default setting.
1543 2 Use the thread-local allocation block (TLAB) watermark
1545 pointer to determine when prefetch instructions are exe‐
1546 cuted.
1547 3 Generate one prefetch instruction per cache line.
1549 -XX:+BackgroundCompilation
1551 Enables background compilation. This option is enabled by de‐
1552 fault. To disable background compilation, specify -XX:-Back‐
1553 groundCompilation (this is equivalent to specifying -Xbatch).
1554 -XX:CICompilerCount=threads
1556 Sets the number of compiler threads to use for compilation. By
1557 default, the number of compiler threads is selected automatical‐
1558 ly depending on the number of CPUs and memory available for com‐
1559 piled code. The following example shows how to set the number
1560 of threads to 2:
1561 -XX:CICompilerCount=2
1563 -XX:+UseDynamicNumberOfCompilerThreads
1565 Dynamically create compiler thread up to the limit specified by
1566 -XX:CICompilerCount. This option is enabled by default.
1567 -XX:CompileCommand=command,method[,option]
1569 Specifies a command to perform on a method. For example, to ex‐
1570 clude the indexOf() method of the String class from being com‐
1571 piled, use the following:
1572 -XX:CompileCommand=exclude,java/lang/String.indexOf
1574 Note that the full class name is specified, including all pack‐
1576 ages and subpackages separated by a slash (/). For easier
1577 cut-and-paste operations, it's also possible to use the method
1578 name format produced by the -XX:+PrintCompilation and -XX:+Log‐
1579 Compilation options:
1580 -XX:CompileCommand=exclude,java.lang.String::indexOf
1582 If the method is specified without the signature, then the com‐
1584 mand is applied to all methods with the specified name. Howev‐
1585 er, you can also specify the signature of the method in the
1586 class file format. In this case, you should enclose the argu‐
1587 ments in quotation marks, because otherwise the shell treats the
1588 semicolon as a command end. For example, if you want to exclude
1589 only the indexOf(String) method of the String class from being
1590 compiled, use the following:
1591 -XX:CompileCommand="exclude,java/lang/String.index‐
1593 Of,(Ljava/lang/String;)I"
1594 You can also use the asterisk (*) as a wildcard for class and
1596 method names. For example, to exclude all indexOf() methods in
1597 all classes from being compiled, use the following:
1598 -XX:CompileCommand=exclude,*.indexOf
1600 The commas and periods are aliases for spaces, making it easier
1602 to pass compiler commands through a shell. You can pass argu‐
1603 ments to -XX:CompileCommand using spaces as separators by en‐
1604 closing the argument in quotation marks:
1605 -XX:CompileCommand="exclude java/lang/String indexOf"
1607 Note that after parsing the commands passed on the command line
1609 using the -XX:CompileCommand options, the JIT compiler then
1610 reads commands from the .hotspot_compiler file. You can add
1611 commands to this file or specify a different file using the
1612 -XX:CompileCommandFile option.
1613 To add several commands, either specify the -XX:CompileCommand
1615 option multiple times, or separate each argument with the new
1616 line separator (\n). The following commands are available:
1617 break Sets a breakpoint when debugging the JVM to stop at the
1619 beginning of compilation of the specified method.
1620 compileonly
1622 Excludes all methods from compilation except for the
1623 specified method. As an alternative, you can use the
1624 -XX:CompileOnly option, which lets you specify several
1625 methods.
1626 dontinline
1628 Prevents inlining of the specified method.
1629 exclude
1631 Excludes the specified method from compilation.
1632 help Prints a help message for the -XX:CompileCommand option.
1634 inline Attempts to inline the specified method.
1636 log Excludes compilation logging (with the -XX:+LogCompila‐
1638 tion option) for all methods except for the specified
1639 method. By default, logging is performed for all com‐
1640 piled methods.
1641 option Passes a JIT compilation option to the specified method
1643 in place of the last argument (option). The compilation
1644 option is set at the end, after the method name. For ex‐
1645 ample, to enable the BlockLayoutByFrequency option for
1646 the append() method of the StringBuffer class, use the
1647 following:
1648 -XX:CompileCommand=option,java/lang/String‐
1650 Buffer.append,BlockLayoutByFrequency
1651 You can specify multiple compilation options, separated
1653 by commas or spaces.
1654 print Prints generated assembler code after compilation of the
1656 specified method.
1657 quiet Instructs not to print the compile commands. By default,
1659 the commands that you specify with the -XX:CompileCommand
1660 option are printed; for example, if you exclude from com‐
1661 pilation the indexOf() method of the String class, then
1662 the following is printed to standard output:
1663 CompilerOracle: exclude java/lang/String.indexOf
1665 You can suppress this by specifying the -XX:CompileCom‐
1667 mand=quiet option before other -XX:CompileCommand op‐
1668 tions.
1669 -XX:CompileCommandFile=filename
1671 Sets the file from which JIT compiler commands are read. By de‐
1672 fault, the .hotspot_compiler file is used to store commands per‐
1673 formed by the JIT compiler.
1674 Each line in the command file represents a command, a class
1676 name, and a method name for which the command is used. For ex‐
1677 ample, this line prints assembly code for the toString() method
1678 of the String class:
1679 print java/lang/String toString
1681 If you're using commands for the JIT compiler to perform on
1683 methods, then see the -XX:CompileCommand option.
1684 -XX:CompilerDirectivesFile=file
1686 Adds directives from a file to the directives stack when a pro‐
1687 gram starts. See Compiler Control [https://docs.ora‐
1688 cle.com/en/java/javase/12/vm/compiler-con‐
1689 trol1.html#GUID-94AD8194-786A-4F19-BFFF-278F8E237F3A].
1690 The -XX:CompilerDirectivesFile option has to be used together
1692 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1693 nostic JVM options.
1694 -XX:+CompilerDirectivesPrint
1696 Prints the directives stack when the program starts or when a
1697 new directive is added.
1698 The -XX:+CompilerDirectivesPrint option has to be used together
1700 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1701 nostic JVM options.
1702 -XX:CompileOnly=methods
1704 Sets the list of methods (separated by commas) to which compila‐
1705 tion should be restricted. Only the specified methods are com‐
1706 piled. Specify each method with the full class name (including
1707 the packages and subpackages). For example, to compile only the
1708 length() method of the String class and the size() method of the
1709 List class, use the following:
1710 -XX:CompileOnly=java/lang/String.length,ja‐
1712 va/util/List.size
1713 Note that the full class name is specified, including all pack‐
1715 ages and subpackages separated by a slash (/). For easier cut
1716 and paste operations, it's also possible to use the method name
1717 format produced by the -XX:+PrintCompilation and -XX:+LogCompi‐
1718 lation options:
1719 -XX:CompileOnly=java.lang.String::length,ja‐
1721 va.util.List::size
1722 Although wildcards aren't supported, you can specify only the
1724 class or package name to compile all methods in that class or
1725 package, as well as specify just the method to compile methods
1726 with this name in any class:
1727 -XX:CompileOnly=java/lang/String
1729 -XX:CompileOnly=java/lang
1730 -XX:CompileOnly=.length
1731 -XX:CompileThresholdScaling=scale
1733 Provides unified control of first compilation. This option con‐
1734 trols when methods are first compiled for both the tiered and
1735 the nontiered modes of operation. The CompileThresholdScaling
1736 option has a floating point value between 0 and +Inf and scales
1737 the thresholds corresponding to the current mode of operation
1738 (both tiered and nontiered). Setting CompileThresholdScaling to
1739 a value less than 1.0 results in earlier compilation while val‐
1740 ues greater than 1.0 delay compilation. Setting CompileThresh‐
1741 oldScaling to 0 is equivalent to disabling compilation.
1742 -XX:+DoEscapeAnalysis
1744 Enables the use of escape analysis. This option is enabled by
1745 default. To disable the use of escape analysis, specify
1746 -XX:-DoEscapeAnalysis.
1747 -XX:InitialCodeCacheSize=size
1749 Sets the initial code cache size (in bytes). Append the letter
1750 k or K to indicate kilobytes, m or M to indicate megabytes, or g
1751 or G to indicate gigabytes. The default value depends on the
1752 platform. The initial code cache size shouldn't be less than
1753 the system's minimal memory page size. The following example
1754 shows how to set the initial code cache size to 32 KB:
1755 -XX:InitialCodeCacheSize=32k
1757 -XX:+Inline
1759 Enables method inlining. This option is enabled by default to
1760 increase performance. To disable method inlining, specify
1761 -XX:-Inline.
1762 -XX:InlineSmallCode=size
1764 Sets the maximum code size (in bytes) for already compiled meth‐
1765 ods that may be inlined. This flag only applies to the C2 com‐
1766 piler. Append the letter k or K to indicate kilobytes, m or M
1767 to indicate megabytes, or g or G to indicate gigabytes. The de‐
1768 fault value depends on the platform and on whether tiered compi‐
1769 lation is enabled. In the following example it is set to 1000
1770 bytes:
1771 -XX:InlineSmallCode=1000
1773 -XX:+LogCompilation
1775 Enables logging of compilation activity to a file named
1776 hotspot.log in the current working directory. You can specify a
1777 different log file path and name using the -XX:LogFile option.
1778 By default, this option is disabled and compilation activity
1780 isn't logged. The -XX:+LogCompilation option has to be used to‐
1781 gether with the -XX:UnlockDiagnosticVMOptions option that un‐
1782 locks diagnostic JVM options.
1783 You can enable verbose diagnostic output with a message printed
1785 to the console every time a method is compiled by using the
1786 -XX:+PrintCompilation option.
1787 -XX:FreqInlineSize=size
1789 Sets the maximum bytecode size (in bytes) of a hot method to be
1790 inlined. This flag only applies to the C2 compiler. Append the
1791 letter k or K to indicate kilobytes, m or M to indicate
1792 megabytes, or g or G to indicate gigabytes. The default value
1793 depends on the platform. In the following example it is set to
1794 325 bytes:
1795 -XX:FreqInlineSize=325
1797 -XX:MaxInlineSize=size
1799 Sets the maximum bytecode size (in bytes) of a cold method to be
1800 inlined. This flag only applies to the C2 compiler. Append the
1801 letter k or K to indicate kilobytes, m or M to indicate
1802 megabytes, or g or G to indicate gigabytes. By default, the
1803 maximum bytecode size is set to 35 bytes:
1804 -XX:MaxInlineSize=35
1806 -XX:C1MaxInlineSize=size
1808 Sets the maximum bytecode size (in bytes) of a cold method to be
1809 inlined. This flag only applies to the C1 compiler. Append the
1810 letter k or K to indicate kilobytes, m or M to indicate
1811 megabytes, or g or G to indicate gigabytes. By default, the
1812 maximum bytecode size is set to 35 bytes:
1813 -XX:MaxInlineSize=35
1815 -XX:MaxTrivialSize=size
1817 Sets the maximum bytecode size (in bytes) of a trivial method to
1818 be inlined. This flag only applies to the C2 compiler. Append
1819 the letter k or K to indicate kilobytes, m or M to indicate
1820 megabytes, or g or G to indicate gigabytes. By default, the
1821 maximum bytecode size of a trivial method is set to 6 bytes:
1822 -XX:MaxTrivialSize=6
1824 -XX:C1MaxTrivialSize=size
1826 Sets the maximum bytecode size (in bytes) of a trivial method to
1827 be inlined. This flag only applies to the C1 compiler. Append
1828 the letter k or K to indicate kilobytes, m or M to indicate
1829 megabytes, or g or G to indicate gigabytes. By default, the
1830 maximum bytecode size of a trivial method is set to 6 bytes:
1831 -XX:MaxTrivialSize=6
1833 -XX:MaxNodeLimit=nodes
1835 Sets the maximum number of nodes to be used during single method
1836 compilation. By default the value depends on the features en‐
1837 abled. In the following example the maximum number of nodes is
1838 set to 100,000:
1839 -XX:MaxNodeLimit=100000
1841 -XX:NonNMethodCodeHeapSize=size
1843 Sets the size in bytes of the code segment containing nonmethod
1844 code.
1845 A nonmethod code segment containing nonmethod code, such as com‐
1847 piler buffers and the bytecode interpreter. This code type
1848 stays in the code cache forever. This flag is used only if
1849 -XX:SegmentedCodeCache is enabled.
1850 -XX:NonProfiledCodeHeapSize=size
1852 Sets the size in bytes of the code segment containing nonpro‐
1853 filed methods. This flag is used only if -XX:SegmentedCodeCache
1854 is enabled.
1855 -XX:+OptimizeStringConcat
1857 Enables the optimization of String concatenation operations.
1858 This option is enabled by default. To disable the optimization
1859 of String concatenation operations, specify -XX:-OptimizeString‐
1860 Concat.
1861 -XX:+PrintAssembly
1863 Enables printing of assembly code for bytecoded and native meth‐
1864 ods by using the external hsdis-<arch>.so or .dll library. For
1865 64-bit VM on Windows, it's hsdis-amd64.dll. This lets you to
1866 see the generated code, which may help you to diagnose perfor‐
1867 mance issues.
1868 By default, this option is disabled and assembly code isn't
1870 printed. The -XX:+PrintAssembly option has to be used together
1871 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1872 nostic JVM options.
1873 -XX:ProfiledCodeHeapSize=size
1875 Sets the size in bytes of the code segment containing profiled
1876 methods. This flag is used only if -XX:SegmentedCodeCache is
1877 enabled.
1878 -XX:+PrintCompilation
1880 Enables verbose diagnostic output from the JVM by printing a
1881 message to the console every time a method is compiled. This
1882 lets you to see which methods actually get compiled. By de‐
1883 fault, this option is disabled and diagnostic output isn't
1884 printed.
1885 You can also log compilation activity to a file by using the
1887 -XX:+LogCompilation option.
1888 -XX:+PrintInlining
1890 Enables printing of inlining decisions. This let's you see
1891 which methods are getting inlined.
1892 By default, this option is disabled and inlining information
1894 isn't printed. The -XX:+PrintInlining option has to be used to‐
1895 gether with the -XX:+UnlockDiagnosticVMOptions option that un‐
1896 locks diagnostic JVM options.
1897 -XX:ReservedCodeCacheSize=size
1899 Sets the maximum code cache size (in bytes) for JIT-compiled
1900 code. Append the letter k or K to indicate kilobytes, m or M to
1901 indicate megabytes, or g or G to indicate gigabytes. The de‐
1902 fault maximum code cache size is 240 MB; if you disable tiered
1903 compilation with the option -XX:-TieredCompilation, then the de‐
1904 fault size is 48 MB. This option has a limit of 2 GB; other‐
1905 wise, an error is generated. The maximum code cache size
1906 shouldn't be less than the initial code cache size; see the op‐
1907 tion -XX:InitialCodeCacheSize.
1908 -XX:RTMAbortRatio=abort_ratio
1910 Specifies the RTM abort ratio is specified as a percentage (%)
1911 of all executed RTM transactions. If a number of aborted trans‐
1912 actions becomes greater than this ratio, then the compiled code
1913 is deoptimized. This ratio is used when the -XX:+UseRTMDeopt
1914 option is enabled. The default value of this option is 50.
1915 This means that the compiled code is deoptimized if 50% of all
1916 transactions are aborted.
1917 -XX:RTMRetryCount=number_of_retries
1919 Specifies the number of times that the RTM locking code is re‐
1920 tried, when it is aborted or busy, before falling back to the
1921 normal locking mechanism. The default value for this option is
1922 5. The -XX:UseRTMLocking option must be enabled.
1923 -XX:+SegmentedCodeCache
1925 Enables segmentation of the code cache, without which the code
1926 cache consists of one large segment. With -XX:+SegmentedCode‐
1927 Cache, separate segments will be used for non-method, profiled
1928 method, and non-profiled method code. The segments are not re‐
1929 sized at runtime. The advantages are better control of the mem‐
1930 ory footprint, reduced code fragmentation, and better CPU iTLB
1931 (instruction translation lookaside buffer) and instruction cache
1932 behavior due to improved locality.
1933 The feature is enabled by default if tiered compilation is en‐
1935 abled (-XX:+TieredCompilation ) and the reserved code cache size
1936 (-XX:ReservedCodeCacheSize) is at least 240 MB.
1937 -XX:StartAggressiveSweepingAt=percent
1939 Forces stack scanning of active methods to aggressively remove
1940 unused code when only the given percentage of the code cache is
1941 free. The default value is 10%.
1942 -XX:-TieredCompilation
1944 Disables the use of tiered compilation. By default, this option
1945 is enabled.
1946 -XX:UseSSE=version
1948 Enables the use of SSE instruction set of a specified version.
1949 Is set by default to the highest supported version available
1950 (x86 only).
1951 -XX:UseAVX=version
1953 Enables the use of AVX instruction set of a specified version.
1954 Is set by default to the highest supported version available
1955 (x86 only).
1956 -XX:+UseAES
1958 Enables hardware-based AES intrinsics for hardware that supports
1959 it. This option is on by default on hardware that has the nec‐
1960 essary instructions. The -XX:+UseAES is used in conjunction
1961 with UseAESIntrinsics. Flags that control intrinsics now re‐
1962 quire the option -XX:+UnlockDiagnosticVMOptions.
1963 -XX:+UseAESIntrinsics
1965 Enables AES intrinsics. Specifying -XX:+UseAESIntrinsics is
1966 equivalent to also enabling -XX:+UseAES. To disable hard‐
1967 ware-based AES intrinsics, specify -XX:-UseAES -XX:-UseAESIn‐
1968 trinsics. For example, to enable hardware AES, use the follow‐
1969 ing flags:
1970 -XX:+UseAES -XX:+UseAESIntrinsics
1972 Flags that control intrinsics now require the option -XX:+Un‐
1974 lockDiagnosticVMOptions.
1975 -XX:+UseAESCTRIntrinsics
1977 Analogous to -XX:+UseAESIntrinsics enables AES/CTR intrinsics.
1978 -XX:+UseGHASHIntrinsics
1980 Controls the use of GHASH intrinsics. Enabled by default on
1981 platforms that support the corresponding instructions. Flags
1982 that control intrinsics now require the option -XX:+UnlockDiag‐
1983 nosticVMOptions.
1984 -XX:+UseBASE64Intrinsics
1986 Controls the use of accelerated BASE64 encoding routines for ja‐
1987 va.util.Base64. Enabled by default on platforms that support
1988 it. Flags that control intrinsics now require the option
1989 -XX:+UnlockDiagnosticVMOptions.
1990 -XX:+UseAdler32Intrinsics
1992 Controls the use of Adler32 checksum algorithm intrinsic for ja‐
1993 va.util.zip.Adler32. Enabled by default on platforms that sup‐
1994 port it. Flags that control intrinsics now require the option
1995 -XX:+UnlockDiagnosticVMOptions.
1996 -XX:+UseCRC32Intrinsics
1998 Controls the use of CRC32 intrinsics for java.util.zip.CRC32.
1999 Enabled by default on platforms that support it. Flags that
2000 control intrinsics now require the option -XX:+UnlockDiagnos‐
2001 ticVMOptions.
2002 -XX:+UseCRC32CIntrinsics
2004 Controls the use of CRC32C intrinsics for java.util.zip.CRC32C.
2005 Enabled by default on platforms that support it. Flags that
2006 control intrinsics now require the option -XX:+UnlockDiagnos‐
2007 ticVMOptions.
2008 -XX:+UseSHA
2010 Enables hardware-based intrinsics for SHA crypto hash functions
2011 for some hardware. The UseSHA option is used in conjunction
2012 with the UseSHA1Intrinsics, UseSHA256Intrinsics, and Use‐
2013 SHA512Intrinsics options.
2014 The UseSHA and UseSHA*Intrinsics flags are enabled by default on
2016 machines that support the corresponding instructions.
2017 This feature is applicable only when using the sun.securi‐
2019 ty.provider.Sun provider for SHA operations. Flags that control
2020 intrinsics now require the option -XX:+UnlockDiagnosticVMOp‐
2021 tions.
2022 To disable all hardware-based SHA intrinsics, specify the
2024 -XX:-UseSHA. To disable only a particular SHA intrinsic, use
2025 the appropriate corresponding option. For example: -XX:-Use‐
2026 SHA256Intrinsics.
2027 -XX:+UseSHA1Intrinsics
2029 Enables intrinsics for SHA-1 crypto hash function. Flags that
2030 control intrinsics now require the option -XX:+UnlockDiagnos‐
2031 ticVMOptions.
2032 -XX:+UseSHA256Intrinsics
2034 Enables intrinsics for SHA-224 and SHA-256 crypto hash func‐
2035 tions. Flags that control intrinsics now require the option
2036 -XX:+UnlockDiagnosticVMOptions.
2037 -XX:+UseSHA512Intrinsics
2039 Enables intrinsics for SHA-384 and SHA-512 crypto hash func‐
2040 tions. Flags that control intrinsics now require the option
2041 -XX:+UnlockDiagnosticVMOptions.
2042 -XX:+UseMathExactIntrinsics
2044 Enables intrinsification of various java.lang.Math.*Exact()
2045 functions. Enabled by default. Flags that control intrinsics
2046 now require the option -XX:+UnlockDiagnosticVMOptions.
2047 -XX:+UseMultiplyToLenIntrinsic
2049 Enables intrinsification of BigInteger.multiplyToLen(). Enabled
2050 by default on platforms that support it. Flags that control in‐
2051 trinsics now require the option -XX:+UnlockDiagnosticVMOptions.
2052 -XX:+UseSquareToLenIntrinsic
2054 Enables intrinsification of BigInteger.squareToLen(). Enabled
2055 by default on platforms that support it. Flags that control in‐
2056 trinsics now require the option -XX:+UnlockDiagnosticVMOptions.
2057 -XX:+UseMulAddIntrinsic
2059 Enables intrinsification of BigInteger.mulAdd(). Enabled by de‐
2060 fault on platforms that support it. Flags that control intrin‐
2061 sics now require the option -XX:+UnlockDiagnosticVMOptions.
2062 -XX:+UseMontgomeryMultiplyIntrinsic
2064 Enables intrinsification of BigInteger.montgomeryMultiply().
2065 Enabled by default on platforms that support it. Flags that
2066 control intrinsics now require the option -XX:+UnlockDiagnos‐
2067 ticVMOptions.
2068 -XX:+UseMontgomerySquareIntrinsic
2070 Enables intrinsification of BigInteger.montgomerySquare(). En‐
2071 abled by default on platforms that support it. Flags that con‐
2072 trol intrinsics now require the option -XX:+UnlockDiagnosticV‐
2073 MOptions.
2074 -XX:+UseCMoveUnconditionally
2076 Generates CMove (scalar and vector) instructions regardless of
2077 profitability analysis.
2078 -XX:+UseCodeCacheFlushing
2080 Enables flushing of the code cache before shutting down the com‐
2081 piler. This option is enabled by default. To disable flushing
2082 of the code cache before shutting down the compiler, specify
2083 -XX:-UseCodeCacheFlushing.
2084 -XX:+UseCondCardMark
2086 Enables checking if the card is already marked before updating
2087 the card table. This option is disabled by default. It should
2088 be used only on machines with multiple sockets, where it in‐
2089 creases the performance of Java applications that rely on con‐
2090 current operations.
2091 -XX:+UseCountedLoopSafepoints
2093 Keeps safepoints in counted loops. Its default value depends on
2094 whether the selected garbage collector requires low latency
2095 safepoints.
2096 -XX:LoopStripMiningIter=number_of_iterations
2098 Controls the number of iterations in the inner strip mined loop.
2099 Strip mining transforms counted loops into two level nested
2100 loops. Safepoints are kept in the outer loop while the inner
2101 loop can execute at full speed. This option controls the maxi‐
2102 mum number of iterations in the inner loop. The default value
2103 is 1,000.
2104 -XX:LoopStripMiningIterShortLoop=number_of_iterations
2106 Controls loop strip mining optimization. Loops with the number
2107 of iterations less than specified will not have safepoints in
2108 them. Default value is 1/10th of -XX:LoopStripMiningIter.
2109 -XX:+UseFMA
2111 Enables hardware-based FMA intrinsics for hardware where FMA in‐
2112 structions are available (such as, Intel and ARM64). FMA in‐
2113 trinsics are generated for the java.lang.Math.fma(a, b, c) meth‐
2114 ods that calculate the value of ( a * b + c ) expressions.
2115 -XX:+UseRTMDeopt
2117 Autotunes RTM locking depending on the abort ratio. This ratio
2118 is specified by the -XX:RTMAbortRatio option. If the number of
2119 aborted transactions exceeds the abort ratio, then the method
2120 containing the lock is deoptimized and recompiled with all locks
2121 as normal locks. This option is disabled by default. The
2122 -XX:+UseRTMLocking option must be enabled.
2123 -XX:+UseRTMLocking
2125 Generates Restricted Transactional Memory (RTM) locking code for
2126 all inflated locks, with the normal locking mechanism as the
2127 fallback handler. This option is disabled by default. Options
2128 related to RTM are available only on x86 CPUs that support
2129 Transactional Synchronization Extensions (TSX).
2130 RTM is part of Intel's TSX, which is an x86 instruction set ex‐
2132 tension and facilitates the creation of multithreaded applica‐
2133 tions. RTM introduces the new instructions XBEGIN, XABORT,
2134 XEND, and XTEST. The XBEGIN and XEND instructions enclose a set
2135 of instructions to run as a transaction. If no conflict is
2136 found when running the transaction, then the memory and register
2137 modifications are committed together at the XEND instruction.
2138 The XABORT instruction can be used to explicitly abort a trans‐
2139 action and the XTEST instruction checks if a set of instructions
2140 is being run in a transaction.
2141 A lock on a transaction is inflated when another thread tries to
2143 access the same transaction, thereby blocking the thread that
2144 didn't originally request access to the transaction. RTM re‐
2145 quires that a fallback set of operations be specified in case a
2146 transaction aborts or fails. An RTM lock is a lock that has
2147 been delegated to the TSX's system.
2148 RTM improves performance for highly contended locks with low
2150 conflict in a critical region (which is code that must not be
2151 accessed by more than one thread concurrently). RTM also im‐
2152 proves the performance of coarse-grain locking, which typically
2153 doesn't perform well in multithreaded applications.
2154 (Coarse-grain locking is the strategy of holding locks for long
2155 periods to minimize the overhead of taking and releasing locks,
2156 while fine-grained locking is the strategy of trying to achieve
2157 maximum parallelism by locking only when necessary and unlocking
2158 as soon as possible.) Also, for lightly contended locks that are
2159 used by different threads, RTM can reduce false cache line shar‐
2160 ing, also known as cache line ping-pong. This occurs when mul‐
2161 tiple threads from different processors are accessing different
2162 resources, but the resources share the same cache line. As a
2163 result, the processors repeatedly invalidate the cache lines of
2164 other processors, which forces them to read from main memory in‐
2165 stead of their cache.
2166 -XX:+UseSuperWord
2168 Enables the transformation of scalar operations into superword
2169 operations. Superword is a vectorization optimization. This
2170 option is enabled by default. To disable the transformation of
2171 scalar operations into superword operations, specify -XX:-UseSu‐
2172 perWord.
2173
2175 These java options provide the ability to gather system information and
2176 perform extensive debugging.
2177 -XX:+DisableAttachMechanism
2179 Disables the mechanism that lets tools attach to the JVM. By
2180 default, this option is disabled, meaning that the attach mecha‐
2181 nism is enabled and you can use diagnostics and troubleshooting
2182 tools such as jcmd, jstack, jmap, and jinfo.
2183 Note: The tools such as jcmd, jinfo, jmap, and jstack
2185 shipped with the JDK aren't supported when using the
2186 tools from one JDK version to troubleshoot a different
2187 JDK version.
2188 -XX:+ExtendedDTraceProbes
2190 Linux and macOS: Enables additional dtrace tool probes that af‐
2191 fect the performance. By default, this option is disabled and
2192 dtrace performs only standard probes.
2193 -XX:+HeapDumpOnOutOfMemoryError
2195 Enables the dumping of the Java heap to a file in the current
2196 directory by using the heap profiler (HPROF) when a ja‐
2197 va.lang.OutOfMemoryError exception is thrown. You can explicit‐
2198 ly set the heap dump file path and name using the -XX:HeapDump‐
2199 Path option. By default, this option is disabled and the heap
2200 isn't dumped when an OutOfMemoryError exception is thrown.
2201 -XX:HeapDumpPath=path
2203 Sets the path and file name for writing the heap dump provided
2204 by the heap profiler (HPROF) when the -XX:+HeapDumpOnOutOfMemo‐
2205 ryError option is set. By default, the file is created in the
2206 current working directory, and it's named java_pid<pid>.hprof
2207 where <pid> is the identifier of the process that caused the er‐
2208 ror. The following example shows how to set the default file
2209 explicitly (%p represents the current process identifier):
2210 -XX:HeapDumpPath=./java_pid%p.hprof
2212 • Linux and macOS: The following example shows how to set the
2214 heap dump file to /var/log/java/java_heapdump.hprof:
2215 -XX:HeapDumpPath=/var/log/java/java_heapdump.hprof
2217 • Windows: The following example shows how to set the heap dump
2219 file to C:/log/java/java_heapdump.log:
2220 -XX:HeapDumpPath=C:/log/java/java_heapdump.log
2222 -XX:LogFile=path
2224 Sets the path and file name to where log data is written. By
2225 default, the file is created in the current working directory,
2226 and it's named hotspot.log.
2227 • Linux and macOS: The following example shows how to set the
2229 log file to /var/log/java/hotspot.log:
2230 -XX:LogFile=/var/log/java/hotspot.log
2232 • Windows: The following example shows how to set the log file
2234 to C:/log/java/hotspot.log:
2235 -XX:LogFile=C:/log/java/hotspot.log
2237 -XX:+PrintClassHistogram
2239 Enables printing of a class instance histogram after one of the
2240 following events:
2241 • Linux and macOS: Control+Break
2243 • Windows: Control+C (SIGTERM)
2245 By default, this option is disabled.
2247 Setting this option is equivalent to running the jmap -histo
2249 command, or the jcmd pid GC.class_histogram command, where pid
2250 is the current Java process identifier.
2251 -XX:+PrintConcurrentLocks
2253 Enables printing of java.util.concurrent locks after one of the
2254 following events:
2255 • Linux and macOS: Control+Break
2257 • Windows: Control+C (SIGTERM)
2259 By default, this option is disabled.
2261 Setting this option is equivalent to running the jstack -l com‐
2263 mand or the jcmd pid Thread.print -l command, where pid is the
2264 current Java process identifier.
2265 -XX:+PrintFlagsRanges
2267 Prints the range specified and allows automatic testing of the
2268 values. See Validate Java Virtual Machine Flag Arguments.
2269 -XX:+PerfDataSaveToFile
2271 If enabled, saves jstat binary data when the Java application
2272 exits. This binary data is saved in a file named hsperfda‐
2273 ta_pid, where pid is the process identifier of the Java applica‐
2274 tion that you ran. Use the jstat command to display the perfor‐
2275 mance data contained in this file as follows:
2276 jstat -class file:///path/hsperfdata_pid
2278 jstat -gc file:///path/hsperfdata_pid
2280 -XX:+UsePerfData
2282 Enables the perfdata feature. This option is enabled by default
2283 to allow JVM monitoring and performance testing. Disabling it
2284 suppresses the creation of the hsperfdata_userid directories.
2285 To disable the perfdata feature, specify -XX:-UsePerfData.
2286
2288 These java options control how garbage collection (GC) is performed by
2289 the Java HotSpot VM.
2290 -XX:+AggressiveHeap
2292 Enables Java heap optimization. This sets various parameters to
2293 be optimal for long-running jobs with intensive memory alloca‐
2294 tion, based on the configuration of the computer (RAM and CPU).
2295 By default, the option is disabled and the heap sizes are con‐
2296 figured less aggressively.
2297 -XX:+AlwaysPreTouch
2299 Requests the VM to touch every page on the Java heap after re‐
2300 questing it from the operating system and before handing memory
2301 out to the application. By default, this option is disabled and
2302 all pages are committed as the application uses the heap space.
2303 -XX:ConcGCThreads=threads
2305 Sets the number of threads used for concurrent GC. Sets threads
2306 to approximately 1/4 of the number of parallel garbage collec‐
2307 tion threads. The default value depends on the number of CPUs
2308 available to the JVM.
2309 For example, to set the number of threads for concurrent GC to
2311 2, specify the following option:
2312 -XX:ConcGCThreads=2
2314 -XX:+DisableExplicitGC
2316 Enables the option that disables processing of calls to the Sys‐
2317 tem.gc() method. This option is disabled by default, meaning
2318 that calls to System.gc() are processed. If processing of calls
2319 to System.gc() is disabled, then the JVM still performs GC when
2320 necessary.
2321 -XX:+ExplicitGCInvokesConcurrent
2323 Enables invoking of concurrent GC by using the System.gc() re‐
2324 quest. This option is disabled by default and can be enabled
2325 only with the -XX:+UseG1GC option.
2326 -XX:G1AdaptiveIHOPNumInitialSamples=number
2328 When -XX:UseAdaptiveIHOP is enabled, this option sets the number
2329 of completed marking cycles used to gather samples until G1
2330 adaptively determines the optimum value of -XX:InitiatingHeapOc‐
2331 cupancyPercent. Before, G1 uses the value of -XX:Initiat‐
2332 ingHeapOccupancyPercent directly for this purpose. The default
2333 value is 3.
2334 -XX:G1HeapRegionSize=size
2336 Sets the size of the regions into which the Java heap is subdi‐
2337 vided when using the garbage-first (G1) collector. The value is
2338 a power of 2 and can range from 1 MB to 32 MB. The default re‐
2339 gion size is determined ergonomically based on the heap size
2340 with a goal of approximately 2048 regions.
2341 The following example sets the size of the subdivisions to 16
2343 MB:
2344 -XX:G1HeapRegionSize=16m
2346 -XX:G1HeapWastePercent=percent
2348 Sets the percentage of heap that you're willing to waste. The
2349 Java HotSpot VM doesn't initiate the mixed garbage collection
2350 cycle when the reclaimable percentage is less than the heap
2351 waste percentage. The default is 5 percent.
2352 -XX:G1MaxNewSizePercent=percent
2354 Sets the percentage of the heap size to use as the maximum for
2355 the young generation size. The default value is 60 percent of
2356 your Java heap.
2357 This is an experimental flag. This setting replaces the -XX:De‐
2359 faultMaxNewGenPercent setting.
2360 -XX:G1MixedGCCountTarget=number
2362 Sets the target number of mixed garbage collections after a
2363 marking cycle to collect old regions with at most G1MixedG‐
2364 CLIveThresholdPercent live data. The default is 8 mixed garbage
2365 collections. The goal for mixed collections is to be within
2366 this target number.
2367 -XX:G1MixedGCLiveThresholdPercent=percent
2369 Sets the occupancy threshold for an old region to be included in
2370 a mixed garbage collection cycle. The default occupancy is 85
2371 percent.
2372 This is an experimental flag. This setting replaces the
2374 -XX:G1OldCSetRegionLiveThresholdPercent setting.
2375 -XX:G1NewSizePercent=percent
2377 Sets the percentage of the heap to use as the minimum for the
2378 young generation size. The default value is 5 percent of your
2379 Java heap.
2380 This is an experimental flag. This setting replaces the -XX:De‐
2382 faultMinNewGenPercent setting.
2383 -XX:G1OldCSetRegionThresholdPercent=percent
2385 Sets an upper limit on the number of old regions to be collected
2386 during a mixed garbage collection cycle. The default is 10 per‐
2387 cent of the Java heap.
2388 -XX:G1ReservePercent=percent
2390 Sets the percentage of the heap (0 to 50) that's reserved as a
2391 false ceiling to reduce the possibility of promotion failure for
2392 the G1 collector. When you increase or decrease the percentage,
2393 ensure that you adjust the total Java heap by the same amount.
2394 By default, this option is set to 10%.
2395 The following example sets the reserved heap to 20%:
2397 -XX:G1ReservePercent=20
2399 -XX:+G1UseAdaptiveIHOP
2401 Controls adaptive calculation of the old generation occupancy to
2402 start background work preparing for an old generation collec‐
2403 tion. If enabled, G1 uses -XX:InitiatingHeapOccupancyPercent
2404 for the first few times as specified by the value of -XX:G1Adap‐
2405 tiveIHOPNumInitialSamples, and after that adaptively calculates
2406 a new optimum value for the initiating occupancy automatically.
2407 Otherwise, the old generation collection process always starts
2408 at the old generation occupancy determined by -XX:Initiat‐
2409 ingHeapOccupancyPercent.
2410 The default is enabled.
2412 -XX:InitialHeapSize=size
2414 Sets the initial size (in bytes) of the memory allocation pool.
2415 This value must be either 0, or a multiple of 1024 and greater
2416 than 1 MB. Append the letter k or K to indicate kilobytes, m or
2417 M to indicate megabytes, or g or G to indicate gigabytes. The
2418 default value is selected at run time based on the system con‐
2419 figuration.
2420 The following examples show how to set the size of allocated
2422 memory to 6 MB using various units:
2423 -XX:InitialHeapSize=6291456
2425 -XX:InitialHeapSize=6144k
2426 -XX:InitialHeapSize=6m
2427 If you set this option to 0, then the initial size is set as the
2429 sum of the sizes allocated for the old generation and the young
2430 generation. The size of the heap for the young generation can
2431 be set using the -XX:NewSize option. Note that the -Xms option
2432 sets both the minimum and the initial heap size of the heap. If
2433 -Xms appears after -XX:InitialHeapSize on the command line, then
2434 the initial heap size gets set to the value specified with -Xms.
2435 -XX:InitialRAMPercentage=percent
2437 Sets the initial amount of memory that the JVM will use for the
2438 Java heap before applying ergonomics heuristics as a percentage
2439 of the maximum amount determined as described in the -XX:MaxRAM
2440 option. The default value is 1.5625 percent.
2441 The following example shows how to set the percentage of the
2443 initial amount of memory used for the Java heap:
2444 -XX:InitialRAMPercentage=5
2446 -XX:InitialSurvivorRatio=ratio
2448 Sets the initial survivor space ratio used by the throughput
2449 garbage collector (which is enabled by the -XX:+UseParallelGC
2450 option). Adaptive sizing is enabled by default with the
2451 throughput garbage collector by using the -XX:+UseParallelGC op‐
2452 tion, and the survivor space is resized according to the appli‐
2453 cation behavior, starting with the initial value. If adaptive
2454 sizing is disabled (using the -XX:-UseAdaptiveSizePolicy op‐
2455 tion), then the -XX:SurvivorRatio option should be used to set
2456 the size of the survivor space for the entire execution of the
2457 application.
2458 The following formula can be used to calculate the initial size
2460 of survivor space (S) based on the size of the young generation
2461 (Y), and the initial survivor space ratio (R):
2462 S=Y/(R+2)
2464 The 2 in the equation denotes two survivor spaces. The larger
2466 the value specified as the initial survivor space ratio, the
2467 smaller the initial survivor space size.
2468 By default, the initial survivor space ratio is set to 8. If
2470 the default value for the young generation space size is used (2
2471 MB), then the initial size of the survivor space is 0.2 MB.
2472 The following example shows how to set the initial survivor
2474 space ratio to 4:
2475 -XX:InitialSurvivorRatio=4
2477 -XX:InitiatingHeapOccupancyPercent=percent
2479 Sets the percentage of the old generation occupancy (0 to 100)
2480 at which to start the first few concurrent marking cycles for
2481 the G1 garbage collector.
2482 By default, the initiating value is set to 45%. A value of 0
2484 implies nonstop concurrent GC cycles from the beginning until G1
2485 adaptively sets this value.
2486 See also the -XX:G1UseAdaptiveIHOP and -XX:G1AdaptiveIHOPNumIni‐
2488 tialSamples options.
2489 The following example shows how to set the initiating heap occu‐
2491 pancy to 75%:
2492 -XX:InitiatingHeapOccupancyPercent=75
2494 -XX:MaxGCPauseMillis=time
2496 Sets a target for the maximum GC pause time (in milliseconds).
2497 This is a soft goal, and the JVM will make its best effort to
2498 achieve it. The specified value doesn't adapt to your heap
2499 size. By default, for G1 the maximum pause time target is 200
2500 milliseconds. The other generational collectors do not use a
2501 pause time goal by default.
2502 The following example shows how to set the maximum target pause
2504 time to 500 ms:
2505 -XX:MaxGCPauseMillis=500
2507 -XX:MaxHeapSize=size
2509 Sets the maximum size (in byes) of the memory allocation pool.
2510 This value must be a multiple of 1024 and greater than 2 MB.
2511 Append the letter k or K to indicate kilobytes, m or M to indi‐
2512 cate megabytes, or g or G to indicate gigabytes. The default
2513 value is selected at run time based on the system configuration.
2514 For server deployments, the options -XX:InitialHeapSize and
2515 -XX:MaxHeapSize are often set to the same value.
2516 The following examples show how to set the maximum allowed size
2518 of allocated memory to 80 MB using various units:
2519 -XX:MaxHeapSize=83886080
2521 -XX:MaxHeapSize=81920k
2522 -XX:MaxHeapSize=80m
2523 The -XX:MaxHeapSize option is equivalent to -Xmx.
2525 -XX:MaxHeapFreeRatio=percent
2527 Sets the maximum allowed percentage of free heap space (0 to
2528 100) after a GC event. If free heap space expands above this
2529 value, then the heap is shrunk. By default, this value is set
2530 to 70%.
2531 Minimize the Java heap size by lowering the values of the param‐
2533 eters MaxHeapFreeRatio (default value is 70%) and MinHeapFreeRa‐
2534 tio (default value is 40%) with the command-line options
2535 -XX:MaxHeapFreeRatio and -XX:MinHeapFreeRatio. Lowering Max‐
2536 HeapFreeRatio to as low as 10% and MinHeapFreeRatio to 5% has
2537 successfully reduced the heap size without too much performance
2538 regression; however, results may vary greatly depending on your
2539 application. Try different values for these parameters until
2540 they're as low as possible yet still retain acceptable perfor‐
2541 mance.
2542 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
2544 Customers trying to keep the heap small should also add the op‐
2546 tion -XX:-ShrinkHeapInSteps. See Performance Tuning Examples
2547 for a description of using this option to keep the Java heap
2548 small by reducing the dynamic footprint for embedded applica‐
2549 tions.
2550 -XX:MaxMetaspaceSize=size
2552 Sets the maximum amount of native memory that can be allocated
2553 for class metadata. By default, the size isn't limited. The
2554 amount of metadata for an application depends on the application
2555 itself, other running applications, and the amount of memory
2556 available on the system.
2557 The following example shows how to set the maximum class metada‐
2559 ta size to 256 MB:
2560 -XX:MaxMetaspaceSize=256m
2562 -XX:MaxNewSize=size
2564 Sets the maximum size (in bytes) of the heap for the young gen‐
2565 eration (nursery). The default value is set ergonomically.
2566 -XX:MaxRAM=size
2568 Sets the maximum amount of memory that the JVM may use for the
2569 Java heap before applying ergonomics heuristics. The default
2570 value is the maximum amount of available memory to the JVM
2571 process or 128 GB, whichever is lower.
2572 The maximum amount of available memory to the JVM process is the
2574 minimum of the machine's physical memory and any constraints set
2575 by the environment (e.g. container).
2576 Specifying this option disables automatic use of compressed oops
2578 if the combined result of this and other options influencing the
2579 maximum amount of memory is larger than the range of memory ad‐
2580 dressable by compressed oops. See -XX:UseCompressedOops for
2581 further information about compressed oops.
2582 The following example shows how to set the maximum amount of
2584 available memory for sizing the Java heap to 2 GB:
2585 -XX:MaxRAM=2G
2587 -XX:MaxRAMPercentage=percent
2589 Sets the maximum amount of memory that the JVM may use for the
2590 Java heap before applying ergonomics heuristics as a percentage
2591 of the maximum amount determined as described in the -XX:MaxRAM
2592 option. The default value is 25 percent.
2593 Specifying this option disables automatic use of compressed oops
2595 if the combined result of this and other options influencing the
2596 maximum amount of memory is larger than the range of memory ad‐
2597 dressable by compressed oops. See -XX:UseCompressedOops for
2598 further information about compressed oops.
2599 The following example shows how to set the percentage of the
2601 maximum amount of memory used for the Java heap:
2602 -XX:MaxRAMPercentage=75
2604 -XX:MinRAMPercentage=percent
2606 Sets the maximum amount of memory that the JVM may use for the
2607 Java heap before applying ergonomics heuristics as a percentage
2608 of the maximum amount determined as described in the -XX:MaxRAM
2609 option for small heaps. A small heap is a heap of approximately
2610 125 MB. The default value is 50 percent.
2611 The following example shows how to set the percentage of the
2613 maximum amount of memory used for the Java heap for small heaps:
2614 -XX:MinRAMPercentage=75
2616 -XX:MaxTenuringThreshold=threshold
2618 Sets the maximum tenuring threshold for use in adaptive GC siz‐
2619 ing. The largest value is 15. The default value is 15 for the
2620 parallel (throughput) collector.
2621 The following example shows how to set the maximum tenuring
2623 threshold to 10:
2624 -XX:MaxTenuringThreshold=10
2626 -XX:MetaspaceSize=size
2628 Sets the size of the allocated class metadata space that trig‐
2629 gers a garbage collection the first time it's exceeded. This
2630 threshold for a garbage collection is increased or decreased de‐
2631 pending on the amount of metadata used. The default size de‐
2632 pends on the platform.
2633 -XX:MinHeapFreeRatio=percent
2635 Sets the minimum allowed percentage of free heap space (0 to
2636 100) after a GC event. If free heap space falls below this val‐
2637 ue, then the heap is expanded. By default, this value is set to
2638 40%.
2639 Minimize Java heap size by lowering the values of the parameters
2641 MaxHeapFreeRatio (default value is 70%) and MinHeapFreeRatio
2642 (default value is 40%) with the command-line options -XX:Max‐
2643 HeapFreeRatio and -XX:MinHeapFreeRatio. Lowering MaxHeapFreeRa‐
2644 tio to as low as 10% and MinHeapFreeRatio to 5% has successfully
2645 reduced the heap size without too much performance regression;
2646 however, results may vary greatly depending on your application.
2647 Try different values for these parameters until they're as low
2648 as possible, yet still retain acceptable performance.
2649 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
2651 Customers trying to keep the heap small should also add the op‐
2653 tion -XX:-ShrinkHeapInSteps. See Performance Tuning Examples
2654 for a description of using this option to keep the Java heap
2655 small by reducing the dynamic footprint for embedded applica‐
2656 tions.
2657 -XX:MinHeapSize=size
2659 Sets the minimum size (in bytes) of the memory allocation pool.
2660 This value must be either 0, or a multiple of 1024 and greater
2661 than 1 MB. Append the letter k or K to indicate kilobytes, m or
2662 M to indicate megabytes, or g or G to indicate gigabytes. The
2663 default value is selected at run time based on the system con‐
2664 figuration.
2665 The following examples show how to set the mimimum size of allo‐
2667 cated memory to 6 MB using various units:
2668 -XX:MinHeapSize=6291456
2670 -XX:MinHeapSize=6144k
2671 -XX:MinHeapSize=6m
2672 If you set this option to 0, then the minimum size is set to the
2674 same value as the initial size.
2675 -XX:NewRatio=ratio
2677 Sets the ratio between young and old generation sizes. By de‐
2678 fault, this option is set to 2. The following example shows how
2679 to set the young-to-old ratio to 1:
2680 -XX:NewRatio=1
2682 -XX:NewSize=size
2684 Sets the initial size (in bytes) of the heap for the young gen‐
2685 eration (nursery). Append the letter k or K to indicate kilo‐
2686 bytes, m or M to indicate megabytes, or g or G to indicate giga‐
2687 bytes.
2688 The young generation region of the heap is used for new objects.
2690 GC is performed in this region more often than in other regions.
2691 If the size for the young generation is too low, then a large
2692 number of minor GCs are performed. If the size is too high,
2693 then only full GCs are performed, which can take a long time to
2694 complete. It is recommended that you keep the size for the
2695 young generation greater than 25% and less than 50% of the over‐
2696 all heap size.
2697 The following examples show how to set the initial size of the
2699 young generation to 256 MB using various units:
2700 -XX:NewSize=256m
2702 -XX:NewSize=262144k
2703 -XX:NewSize=268435456
2704 The -XX:NewSize option is equivalent to -Xmn.
2706 -XX:ParallelGCThreads=threads
2708 Sets the number of the stop-the-world (STW) worker threads. The
2709 default value depends on the number of CPUs available to the JVM
2710 and the garbage collector selected.
2711 For example, to set the number of threads for G1 GC to 2, speci‐
2713 fy the following option:
2714 -XX:ParallelGCThreads=2
2716 -XX:+ParallelRefProcEnabled
2718 Enables parallel reference processing. By default, this option
2719 is disabled.
2720 -XX:+PrintAdaptiveSizePolicy
2722 Enables printing of information about adaptive-generation siz‐
2723 ing. By default, this option is disabled.
2724 -XX:+ScavengeBeforeFullGC
2726 Enables GC of the young generation before each full GC. This
2727 option is enabled by default. It is recommended that you don't
2728 disable it, because scavenging the young generation before a
2729 full GC can reduce the number of objects reachable from the old
2730 generation space into the young generation space. To disable GC
2731 of the young generation before each full GC, specify the option
2732 -XX:-ScavengeBeforeFullGC.
2733 -XX:SoftRefLRUPolicyMSPerMB=time
2735 Sets the amount of time (in milliseconds) a softly reachable ob‐
2736 ject is kept active on the heap after the last time it was ref‐
2737 erenced. The default value is one second of lifetime per free
2738 megabyte in the heap. The -XX:SoftRefLRUPolicyMSPerMB option
2739 accepts integer values representing milliseconds per one
2740 megabyte of the current heap size (for Java HotSpot Client VM)
2741 or the maximum possible heap size (for Java HotSpot Server VM).
2742 This difference means that the Client VM tends to flush soft
2743 references rather than grow the heap, whereas the Server VM
2744 tends to grow the heap rather than flush soft references. In
2745 the latter case, the value of the -Xmx option has a significant
2746 effect on how quickly soft references are garbage collected.
2747 The following example shows how to set the value to 2.5 seconds:
2749 -XX:SoftRefLRUPolicyMSPerMB=2500
2751 -XX:-ShrinkHeapInSteps
2753 Incrementally reduces the Java heap to the target size, speci‐
2754 fied by the option -XX:MaxHeapFreeRatio. This option is enabled
2755 by default. If disabled, then it immediately reduces the Java
2756 heap to the target size instead of requiring multiple garbage
2757 collection cycles. Disable this option if you want to minimize
2758 the Java heap size. You will likely encounter performance
2759 degradation when this option is disabled.
2760 See Performance Tuning Examples for a description of using the
2762 MaxHeapFreeRatio option to keep the Java heap small by reducing
2763 the dynamic footprint for embedded applications.
2764 -XX:StringDeduplicationAgeThreshold=threshold
2766 Identifies String objects reaching the specified age that are
2767 considered candidates for deduplication. An object's age is a
2768 measure of how many times it has survived garbage collection.
2769 This is sometimes referred to as tenuring.
2770 Note: String objects that are promoted to an old heap re‐
2772 gion before this age has been reached are always consid‐
2773 ered candidates for deduplication. The default value for
2774 this option is 3. See the -XX:+UseStringDeduplication
2775 option.
2776 -XX:SurvivorRatio=ratio
2778 Sets the ratio between eden space size and survivor space size.
2779 By default, this option is set to 8. The following example
2780 shows how to set the eden/survivor space ratio to 4:
2781 -XX:SurvivorRatio=4
2783 -XX:TargetSurvivorRatio=percent
2785 Sets the desired percentage of survivor space (0 to 100) used
2786 after young garbage collection. By default, this option is set
2787 to 50%.
2788 The following example shows how to set the target survivor space
2790 ratio to 30%:
2791 -XX:TargetSurvivorRatio=30
2793 -XX:TLABSize=size
2795 Sets the initial size (in bytes) of a thread-local allocation
2796 buffer (TLAB). Append the letter k or K to indicate kilobytes,
2797 m or M to indicate megabytes, or g or G to indicate gigabytes.
2798 If this option is set to 0, then the JVM selects the initial
2799 size automatically.
2800 The following example shows how to set the initial TLAB size to
2802 512 KB:
2803 -XX:TLABSize=512k
2805 -XX:+UseAdaptiveSizePolicy
2807 Enables the use of adaptive generation sizing. This option is
2808 enabled by default. To disable adaptive generation sizing,
2809 specify -XX:-UseAdaptiveSizePolicy and set the size of the memo‐
2810 ry allocation pool explicitly. See the -XX:SurvivorRatio op‐
2811 tion.
2812 -XX:+UseG1GC
2814 Enables the use of the garbage-first (G1) garbage collector.
2815 It's a server-style garbage collector, targeted for multiproces‐
2816 sor machines with a large amount of RAM. This option meets GC
2817 pause time goals with high probability, while maintaining good
2818 throughput. The G1 collector is recommended for applications
2819 requiring large heaps (sizes of around 6 GB or larger) with lim‐
2820 ited GC latency requirements (a stable and predictable pause
2821 time below 0.5 seconds). By default, this option is enabled and
2822 G1 is used as the default garbage collector.
2823 -XX:+UseGCOverheadLimit
2825 Enables the use of a policy that limits the proportion of time
2826 spent by the JVM on GC before an OutOfMemoryError exception is
2827 thrown. This option is enabled, by default, and the parallel GC
2828 will throw an OutOfMemoryError if more than 98% of the total
2829 time is spent on garbage collection and less than 2% of the heap
2830 is recovered. When the heap is small, this feature can be used
2831 to prevent applications from running for long periods of time
2832 with little or no progress. To disable this option, specify the
2833 option -XX:-UseGCOverheadLimit.
2834 -XX:+UseNUMA
2836 Enables performance optimization of an application on a machine
2837 with nonuniform memory architecture (NUMA) by increasing the ap‐
2838 plication's use of lower latency memory. By default, this op‐
2839 tion is disabled and no optimization for NUMA is made. The op‐
2840 tion is available only when the parallel garbage collector is
2841 used (-XX:+UseParallelGC).
2842 -XX:+UseParallelGC
2844 Enables the use of the parallel scavenge garbage collector (also
2845 known as the throughput collector) to improve the performance of
2846 your application by leveraging multiple processors.
2847 By default, this option is disabled and the default collector is
2849 used.
2850 -XX:+UseSerialGC
2852 Enables the use of the serial garbage collector. This is gener‐
2853 ally the best choice for small and simple applications that
2854 don't require any special functionality from garbage collection.
2855 By default, this option is disabled and the default collector is
2856 used.
2857 -XX:+UseSHM
2859 Linux only: Enables the JVM to use shared memory to set up large
2860 pages.
2861 See Large Pages for setting up large pages.
2863 -XX:+UseStringDeduplication
2865 Enables string deduplication. By default, this option is dis‐
2866 abled. To use this option, you must enable the garbage-first
2867 (G1) garbage collector.
2868 String deduplication reduces the memory footprint of String ob‐
2870 jects on the Java heap by taking advantage of the fact that many
2871 String objects are identical. Instead of each String object
2872 pointing to its own character array, identical String objects
2873 can point to and share the same character array.
2874 -XX:+UseTLAB
2876 Enables the use of thread-local allocation blocks (TLABs) in the
2877 young generation space. This option is enabled by default. To
2878 disable the use of TLABs, specify the option -XX:-UseTLAB.
2879 -XX:+UseZGC
2881 Enables the use of the Z garbage collector (ZGC). This is a low
2882 latency garbage collector, providing max pause times of a few
2883 milliseconds, at some throughput cost. Pause times are indepen‐
2884 dent of what heap size is used. Supports heap sizes from 8MB to
2885 16TB.
2886 -XX:ZAllocationSpikeTolerance=factor
2888 Sets the allocation spike tolerance for ZGC. By default, this
2889 option is set to 2.0. This factor describes the level of allo‐
2890 cation spikes to expect. For example, using a factor of 3.0
2891 means the current allocation rate can be expected to triple at
2892 any time.
2893 -XX:ZCollectionInterval=seconds
2895 Sets the maximum interval (in seconds) between two GC cycles
2896 when using ZGC. By default, this option is set to 0 (disabled).
2897 -XX:ZFragmentationLimit=percent
2899 Sets the maximum acceptable heap fragmentation (in percent) for
2900 ZGC. By default, this option is set to 25. Using a lower value
2901 will cause the heap to be compacted more aggressively, to re‐
2902 claim more memory at the cost of using more CPU time.
2903 -XX:+ZProactive
2905 Enables proactive GC cycles when using ZGC. By default, this
2906 option is enabled. ZGC will start a proactive GC cycle if doing
2907 so is expected to have minimal impact on the running applica‐
2908 tion. This is useful if the application is mostly idle or allo‐
2909 cates very few objects, but you still want to keep the heap size
2910 down and allow reference processing to happen even when there
2911 are a lot of free space on the heap.
2912 -XX:+ZUncommit
2914 Enables uncommitting of unused heap memory when using ZGC. By
2915 default, this option is enabled. Uncommitting unused heap memo‐
2916 ry will lower the memory footprint of the JVM, and make that
2917 memory available for other processes to use.
2918 -XX:ZUncommitDelay=seconds
2920 Sets the amount of time (in seconds) that heap memory must have
2921 been unused before being uncommitted. By default, this option
2922 is set to 300 (5 minutes). Committing and uncommitting memory
2923 are relatively expensive operations. Using a lower value will
2924 cause heap memory to be uncommitted earlier, at the risk of soon
2925 having to commit it again.
2926
2928 These java options are deprecated and might be removed in a future JDK
2929 release. They're still accepted and acted upon, but a warning is is‐
2930 sued when they're used.
2931 -Xfuture
2933 Enables strict class-file format checks that enforce close con‐
2934 formance to the class-file format specification. Developers
2935 should use this flag when developing new code. Stricter checks
2936 may become the default in future releases.
2937 -Xloggc:filename
2939 Sets the file to which verbose GC events information should be
2940 redirected for logging. The -Xloggc option overrides -ver‐
2941 bose:gc if both are given with the same java command. -Xlog‐
2942 gc:filename is replaced by -Xlog:gc:filename. See Enable Log‐
2943 ging with the JVM Unified Logging Framework.
2944 Example:
2946 -Xlog:gc:garbage-collection.log
2948 -XX:+FlightRecorder
2950 Enables the use of Java Flight Recorder (JFR) during the runtime
2951 of the application. Since JDK 8u40 this option has not been re‐
2952 quired to use JFR.
2953 -XX:InitialRAMFraction=ratio
2955 Sets the initial amount of memory that the JVM may use for the
2956 Java heap before applying ergonomics heuristics as a ratio of
2957 the maximum amount determined as described in the -XX:MaxRAM op‐
2958 tion. The default value is 64.
2959 Use the option -XX:InitialRAMPercentage instead.
2961 -XX:MaxRAMFraction=ratio
2963 Sets the maximum amount of memory that the JVM may use for the
2964 Java heap before applying ergonomics heuristics as a fraction of
2965 the maximum amount determined as described in the -XX:MaxRAM op‐
2966 tion. The default value is 4.
2967 Specifying this option disables automatic use of compressed oops
2969 if the combined result of this and other options influencing the
2970 maximum amount of memory is larger than the range of memory ad‐
2971 dressable by compressed oops. See -XX:UseCompressedOops for
2972 further information about compressed oops.
2973 Use the option -XX:MaxRAMPercentage instead.
2975 -XX:MinRAMFraction=ratio
2977 Sets the maximum amount of memory that the JVM may use for the
2978 Java heap before applying ergonomics heuristics as a fraction of
2979 the maximum amount determined as described in the -XX:MaxRAM op‐
2980 tion for small heaps. A small heap is a heap of approximately
2981 125 MB. The default value is 2.
2982 Use the option -XX:MinRAMPercentage instead.
2984
2986 These java options are still accepted but ignored, and a warning is is‐
2987 sued when they're used.
2988 --illegal-access=parameter
2990 Controlled relaxed strong encapsulation, as defined in JEP 261
2991 [https://openjdk.java.net/jeps/261#Relaxed-strong-encapsula‐
2992 tion]. This option was deprecated in JDK 16 by JEP 396
2993 [https://openjdk.java.net/jeps/396] and made obsolete in JDK 17
2994 by JEP 403 [https://openjdk.java.net/jeps/403].
2995 -XX:+UseBiasedLocking
2997 Enables the use of biased locking. Some applications with sig‐
2998 nificant amounts of uncontended synchronization may attain sig‐
2999 nificant speedups with this flag enabled, but applications with
3000 certain patterns of locking may see slowdowns.
3001 By default, this option is disabled.
3003
3005 No documented java options have been removed in JDK 18.
3006 For the lists and descriptions of options removed in previous releases
3008 see the Removed Java Options section in:
3009 • The java Command, Release 17 [https://docs.oracle.com/en/ja‐
3011 va/javase/17/docs/specs/man/java.html]
3012 • The java Command, Release 16 [https://docs.oracle.com/en/ja‐
3014 va/javase/16/docs/specs/man/java.html]
3015 • The java Command, Release 15 [https://docs.oracle.com/en/ja‐
3017 va/javase/15/docs/specs/man/java.html]
3018 • The java Command, Release 14 [https://docs.oracle.com/en/ja‐
3020 va/javase/14/docs/specs/man/java.html]
3021 • The java Command, Release 13 [https://docs.oracle.com/en/ja‐
3023 va/javase/13/docs/specs/man/java.html]
3024 • Java Platform, Standard Edition Tools Reference, Release 12
3026 [https://docs.oracle.com/en/java/javase/12/tools/ja‐
3027 va.html#GUID-3B1CE181-CD30-4178-9602-230B800D4FAE]
3028 • Java Platform, Standard Edition Tools Reference, Release 11
3030 [https://docs.oracle.com/en/java/javase/11/tools/ja‐
3031 va.html#GUID-741FC470-AA3E-494A-8D2B-1B1FE4A990D1]
3032 • Java Platform, Standard Edition Tools Reference, Release 10
3034 [https://docs.oracle.com/javase/10/tools/java.htm#JSWOR624]
3035 • Java Platform, Standard Edition Tools Reference, Release 9
3037 [https://docs.oracle.com/javase/9/tools/java.htm#JSWOR624]
3038 • Java Platform, Standard Edition Tools Reference, Release 8 for Oracle
3040 JDK on Windows [https://docs.oracle.com/javase/8/docs/tech‐
3041 notes/tools/windows/java.html#BGBCIEFC]
3042 • Java Platform, Standard Edition Tools Reference, Release 8 for Oracle
3044 JDK on Solaris, Linux, and macOS [https://docs.ora‐
3045 cle.com/javase/8/docs/technotes/tools/unix/java.html#BGBCIEFC]
3046
3048 You can shorten or simplify the java command by using @ argument files
3049 to specify one or more text files that contain arguments, such as op‐
3050 tions and class names, which are passed to the java command. This
3051 let's you to create java commands of any length on any operating sys‐
3052 tem.
3053 In the command line, use the at sign (@) prefix to identify an argument
3055 file that contains java options and class names. When the java command
3056 encounters a file beginning with the at sign (@), it expands the con‐
3057 tents of that file into an argument list just as they would be speci‐
3058 fied on the command line.
3059 The java launcher expands the argument file contents until it encoun‐
3061 ters the --disable-@files option. You can use the --disable-@files op‐
3062 tion anywhere on the command line, including in an argument file, to
3063 stop @ argument files expansion.
3064 The following items describe the syntax of java argument files:
3066 • The argument file must contain only ASCII characters or characters in
3068 system default encoding that's ASCII friendly, such as UTF-8.
3069 • The argument file size must not exceed MAXINT (2,147,483,647) bytes.
3071 • The launcher doesn't expand wildcards that are present within an ar‐
3073 gument file.
3074 • Use white space or new line characters to separate arguments included
3076 in the file.
3077 • White space includes a white space character, \t, \n, \r, and \f.
3079 For example, it is possible to have a path with a space, such as
3081 c:\Program Files that can be specified as either "c:\\Program Files"
3082 or, to avoid an escape, c:\Program" "Files.
3083 • Any option that contains spaces, such as a path component, must be
3085 within quotation marks using quotation ('"') characters in its en‐
3086 tirety.
3087 • A string within quotation marks may contain the characters \n, \r,
3089 \t, and \f. They are converted to their respective ASCII codes.
3090 • If a file name contains embedded spaces, then put the whole file name
3092 in double quotation marks.
3093 • File names in an argument file are relative to the current directory,
3095 not to the location of the argument file.
3096 • Use the number sign # in the argument file to identify comments. All
3098 characters following the # are ignored until the end of line.
3099 • Additional at sign @ prefixes to @ prefixed options act as an escape,
3101 (the first @ is removed and the rest of the arguments are presented
3102 to the launcher literally).
3103 • Lines may be continued using the continuation character (\) at the
3105 end-of-line. The two lines are concatenated with the leading white
3106 spaces trimmed. To prevent trimming the leading white spaces, a con‐
3107 tinuation character (\) may be placed at the first column.
3108 • Because backslash (\) is an escape character, a backslash character
3110 must be escaped with another backslash character.
3111 • Partial quote is allowed and is closed by an end-of-file.
3113 • An open quote stops at end-of-line unless \ is the last character,
3115 which then joins the next line by removing all leading white space
3116 characters.
3117 • Wildcards (*) aren't allowed in these lists (such as specifying *.ja‐
3119 va).
3120 • Use of the at sign (@) to recursively interpret files isn't support‐
3122 ed.
3123 Example of Open or Partial Quotes in an Argument File
3125 In the argument file,
3126 -cp "lib/
3128 cool/
3129 app/
3130 jars
3131 this is interpreted as:
3133 -cp lib/cool/app/jars
3135 Example of a Backslash Character Escaped with Another Backslash
3137 Character in an Argument File
3138 To output the following:
3140 -cp c:\Program Files (x86)\Java\jre\lib\ext;c:\Program Files\Ja‐
3142 va\jre9\lib\ext
3143 The backslash character must be specified in the argument file as:
3145 -cp "c:\\Program Files (x86)\\Java\\jre\\lib\\ext;c:\\Pro‐
3147 gram Files\\Java\\jre9\\lib\\ext"
3148 Example of an EOL Escape Used to Force Concatenation of Lines in an
3150 Argument File
3151 In the argument file,
3153 -cp "/lib/cool app/jars:\
3155 /lib/another app/jars"
3156 This is interpreted as:
3158 -cp /lib/cool app/jars:/lib/another app/jars
3160 Example of Line Continuation with Leading Spaces in an Argument File
3162 In the argument file,
3163 -cp "/lib/cool\
3165 \app/jars"
3166 This is interpreted as:
3168 -cp /lib/cool app/jars
3170 Examples of Using Single Argument File
3172 You can use a single argument file, such as myargumentfile in the fol‐
3173 lowing example, to hold all required java arguments:
3174 java @myargumentfile
3176 Examples of Using Argument Files with Paths
3178 You can include relative paths in argument files; however, they're rel‐
3179 ative to the current working directory and not to the paths of the ar‐
3180 gument files themselves. In the following example, path1/options and
3181 path2/options represent argument files with different paths. Any rela‐
3182 tive paths that they contain are relative to the current working direc‐
3183 tory and not to the argument files:
3184 java @path1/options @path2/classes
3186
3188 Overview
3189 There are occasions when having insight into the current state of the
3190 JVM code heap would be helpful to answer questions such as:
3191 • Why was the JIT turned off and then on again and again?
3193 • Where has all the code heap space gone?
3195 • Why is the method sweeper not working effectively?
3197 To provide this insight, a code heap state analytics feature has been
3199 implemented that enables on-the-fly analysis of the code heap. The an‐
3200 alytics process is divided into two parts. The first part examines the
3201 entire code heap and aggregates all information that is believed to be
3202 useful or important. The second part consists of several independent
3203 steps that print the collected information with an emphasis on differ‐
3204 ent aspects of the data. Data collection and printing are done on an
3205 "on request" basis.
3206 Syntax
3208 Requests for real-time, on-the-fly analysis can be issued with the fol‐
3209 lowing command:
3210 jcmd pid Compiler.CodeHeap_Analytics [function] [granularity]
3212 If you are only interested in how the code heap looks like after run‐
3214 ning a sample workload, you can use the command line option:
3215 -Xlog:codecache=Trace
3217 To see the code heap state when a "CodeCache full" condition exists,
3219 start the VM with the command line option:
3220 -Xlog:codecache=Debug
3222 See CodeHeap State Analytics (OpenJDK) [https://bugs.openjdk.ja‐
3224 va.net/secure/attachment/75649/JVM_CodeHeap_StateAnalytics_V2.pdf] for
3225 a detailed description of the code heap state analytics feature, the
3226 supported functions, and the granularity options.
3227
3229 You use the -Xlog option to configure or enable logging with the Java
3230 Virtual Machine (JVM) unified logging framework.
3231 Synopsis
3233 -Xlog[:[what][:[output][:[decorators][:output-options[,...]]]]]
3234 -Xlog:directive
3236 what Specifies a combination of tags and levels of the form
3238 tag1[+tag2...][*][=level][,...]. Unless the wildcard (*) is
3239 specified, only log messages tagged with exactly the tags speci‐
3240 fied are matched. See -Xlog Tags and Levels.
3241 output Sets the type of output. Omitting the output type defaults to
3243 stdout. See -Xlog Output.
3244 decorators
3246 Configures the output to use a custom set of decorators. Omit‐
3247 ting decorators defaults to uptime, level, and tags. See Deco‐
3248 rations.
3249 output-options
3251 Sets the -Xlog logging output options.
3252 directive
3254 A global option or subcommand: help, disable, async
3255 Description
3257 The Java Virtual Machine (JVM) unified logging framework provides a
3258 common logging system for all components of the JVM. GC logging for
3259 the JVM has been changed to use the new logging framework. The mapping
3260 of old GC flags to the corresponding new Xlog configuration is de‐
3261 scribed in Convert GC Logging Flags to Xlog. In addition, runtime log‐
3262 ging has also been changed to use the JVM unified logging framework.
3263 The mapping of legacy runtime logging flags to the corresponding new
3264 Xlog configuration is described in Convert Runtime Logging Flags to
3265 Xlog.
3266 The following provides quick reference to the -Xlog command and syntax
3268 for options:
3269 -Xlog Enables JVM logging on an info level.
3271 -Xlog:help
3273 Prints -Xlog usage syntax and available tags, levels, and deco‐
3274 rators along with example command lines with explanations.
3275 -Xlog:disable
3277 Turns off all logging and clears all configuration of the log‐
3278 ging framework including the default configuration for warnings
3279 and errors.
3280 -Xlog[:option]
3282 Applies multiple arguments in the order that they appear on the
3283 command line. Multiple -Xlog arguments for the same output
3284 override each other in their given order.
3285 The option is set as:
3287 [tag-selection][:[output][:[decorators][:output-op‐
3289 tions]]]
3290 Omitting the tag-selection defaults to a tag-set of all and a
3292 level of info.
3293 tag[+...] all
3295 The all tag is a meta tag consisting of all tag-sets available.
3297 The asterisk * in a tag set definition denotes a wildcard tag
3298 match. Matching with a wildcard selects all tag sets that con‐
3299 tain at least the specified tags. Without the wildcard, only
3300 exact matches of the specified tag sets are selected.
3301 output-options is
3303 filecount=file-count filesize=file size with optional K,
3305 M or G suffix foldmultilines=<true|false>
3306 When foldmultilines is true, a log event that consists of multi‐
3308 ple lines will be folded into a single line by replacing newline
3309 characters with the sequence '\' and 'n' in the output. Exist‐
3310 ing single backslash characters will also be replaced with a se‐
3311 quence of two backslashes so that the conversion can be re‐
3312 versed. This option is safe to use with UTF-8 character encod‐
3313 ings, but other encodings may not work. For example, it may in‐
3314 correctly convert multi-byte sequences in Shift JIS and BIG5.
3315 Default Configuration
3317 When the -Xlog option and nothing else is specified on the command
3318 line, the default configuration is used. The default configuration
3319 logs all messages with a level that matches either warning or error re‐
3320 gardless of what tags the message is associated with. The default con‐
3321 figuration is equivalent to entering the following on the command line:
3322 -Xlog:all=warning:stdout:uptime,level,tags
3324 Controlling Logging at Runtime
3326 Logging can also be controlled at run time through Diagnostic Commands
3327 (with the jcmd utility). Everything that can be specified on the com‐
3328 mand line can also be specified dynamically with the VM.log command.
3329 As the diagnostic commands are automatically exposed as MBeans, you can
3330 use JMX to change logging configuration at run time.
3331 -Xlog Tags and Levels
3333 Each log message has a level and a tag set associated with it. The
3334 level of the message corresponds to its details, and the tag set corre‐
3335 sponds to what the message contains or which JVM component it involves
3336 (such as, gc, jit, or os). Mapping GC flags to the Xlog configuration
3337 is described in Convert GC Logging Flags to Xlog. Mapping legacy run‐
3338 time logging flags to the corresponding Xlog configuration is described
3339 in Convert Runtime Logging Flags to Xlog.
3340 Available log levels:
3342 • off
3344 • trace
3346 • debug
3348 • info
3350 • warning
3352 • error
3354 Available log tags:
3356 There are literally dozens of log tags, which in the right combina‐
3358 tions, will enable a range of logging output. The full set of avail‐
3359 able log tags can be seen using -Xlog:help. Specifying all instead of
3360 a tag combination matches all tag combinations.
3361 -Xlog Output
3363 The -Xlog option supports the following types of outputs:
3364 • stdout --- Sends output to stdout
3366 • stderr --- Sends output to stderr
3368 • file=filename --- Sends output to text file(s).
3370 When using file=filename, specifying %p and/or %t in the file name ex‐
3372 pands to the JVM's PID and startup timestamp, respectively. You can
3373 also configure text files to handle file rotation based on file size
3374 and a number of files to rotate. For example, to rotate the log file
3375 every 10 MB and keep 5 files in rotation, specify the options file‐
3376 size=10M, filecount=5. The target size of the files isn't guaranteed
3377 to be exact, it's just an approximate value. Files are rotated by de‐
3378 fault with up to 5 rotated files of target size 20 MB, unless config‐
3379 ured otherwise. Specifying filecount=0 means that the log file
3380 shouldn't be rotated. There's a possibility of the pre-existing log
3381 file getting overwritten.
3382 -Xlog Output Mode
3384 By default logging messages are output synchronously - each log message
3385 is written to the designated output when the logging call is made. But
3386 you can instead use asynchronous logging mode by specifying:
3387 -Xlog:async
3389 Write all logging asynchronously.
3390 In asynchronous logging mode, log sites enqueue all logging messages to
3392 an intermediate buffer and a standalone thread is responsible for
3393 flushing them to the corresponding outputs. The intermediate buffer is
3394 bounded and on buffer exhaustion the enqueuing message is discarded.
3395 Log entry write operations are guaranteed non-blocking.
3396 The option -XX:AsyncLogBufferSize=N specifies the memory budget in
3398 bytes for the intermediate buffer. The default value should be big
3399 enough to cater for most cases. Users can provide a custom value to
3400 trade memory overhead for log accuracy if they need to.
3401 Decorations
3403 Logging messages are decorated with information about the message. You
3404 can configure each output to use a custom set of decorators. The order
3405 of the output is always the same as listed in the table. You can con‐
3406 figure the decorations to be used at run time. Decorations are
3407 prepended to the log message. For example:
3408 [6.567s][info][gc,old] Old collection complete
3410 Omitting decorators defaults to uptime, level, and tags. The none dec‐
3412 orator is special and is used to turn off all decorations.
3413 time (t), utctime (utc), uptime (u), timemillis (tm), uptimemillis
3415 (um), timenanos (tn), uptimenanos (un), hostname (hn), pid (p), tid
3416 (ti), level (l), tags (tg) decorators can also be specified as none for
3417 no decoration.
3418 Decorations Description
3420 ──────────────────────────────────────────────────────────────────────────
3421 time or t Current time and date in ISO-8601 format.
3422 utctime or utc Universal Time Coordinated or Coordinated Universal
3423 Time.
3424 uptime or u Time since the start of the JVM in seconds and mil‐
3425 liseconds. For example, 6.567s.
3426 timemillis or The same value as generated by System.currentTimeMil‐
3427 tm lis()
3428 uptimemillis or Milliseconds since the JVM started.
3429 um
3430 timenanos or tn The same value generated by System.nanoTime().
3431 uptimenanos or Nanoseconds since the JVM started.
3432 un
3433 hostname or hn The host name.
3434 pid or p The process identifier.
3435 tid or ti The thread identifier.
3436 level or l The level associated with the log message.
3437 tags or tg The tag-set associated with the log message.
3438 Convert GC Logging Flags to Xlog
3440 Legacy Garbage Collec‐ Xlog Configura‐ Comment
3441 tion (GC) Flag tion
3442 ───────────────────────────────────────────────────────────────────────────────────────
3443 G1PrintHeapRegions -Xlog:gc+re‐ Not Applicable
3444 gion=trace
3445 GCLogFileSize No configuration Log rotation is handled by the
3446 available framework.
3447 NumberOfGCLogFiles Not Applicable Log rotation is handled by the
3448 framework.
3449 PrintAdaptiveSizePoli‐ -Xlog:gc+er‐ Use a level of debug for most
3450 cy go*=level of the information, or a level
3451 of trace for all of what was
3452 logged for PrintAdaptive‐
3453 SizePolicy.
3454 PrintGC -Xlog:gc Not Applicable
3455 PrintGCApplicationCon‐ -Xlog:safepoint Note that PrintGCApplication‐
3456 currentTime ConcurrentTime and PrintGCAp‐
3457 plicationStoppedTime are logged
3458 on the same tag and aren't sep‐
3459 arated in the new logging.
3460 PrintGCApplication‐ -Xlog:safepoint Note that PrintGCApplication‐
3461 StoppedTime ConcurrentTime and PrintGCAp‐
3462 plicationStoppedTime are logged
3463 on the same tag and not sepa‐
3464 rated in the new logging.
3465 PrintGCCause Not Applicable GC cause is now always logged.
3466 PrintGCDateStamps Not Applicable Date stamps are logged by the
3467 framework.
3468 PrintGCDetails -Xlog:gc* Not Applicable
3469 PrintGCID Not Applicable GC ID is now always logged.
3470 PrintGCTaskTimeStamps -Xlog:gc+task*=de‐ Not Applicable
3471 bug
3472 PrintGCTimeStamps Not Applicable Time stamps are logged by the
3473 framework.
3474 PrintHeapAtGC -Xlog:gc+heap=trace Not Applicable
3475 PrintReferenceGC -Xlog:gc+ref*=debug Note that in the old logging,
3476 PrintReferenceGC had an effect
3477 only if PrintGCDetails was also
3478 enabled.
3479 PrintStringDeduplica‐ `-Xlog:gc+stringdedup*=de‐ ` Not Applicable
3480 tionStatistics bug
3481 PrintTenuringDistribu‐ -Xlog:gc+age*=level Use a level of debug for the
3482 tion most relevant information, or a
3483 level of trace for all of what
3484 was logged for PrintTenur‐
3485 ingDistribution.
3486 UseGCLogFileRotation Not Applicable What was logged for PrintTenur‐
3489 ingDistribution.
3490 Convert Runtime Logging Flags to Xlog
3492 These legacy flags are no longer recognized and will cause an error if
3493 used directly. Use their unified logging equivalent instead.
3494 Legacy Runtime Xlog Configuration Comment
3496 Flag
3497 ──────────────────────────────────────────────────────────────────────────────
3498 TraceExceptions -Xlog:exceptions=in‐ Not Applicable
3499 fo
3500 TraceClassLoad‐ -Xlog:class+load=lev‐ Use level=info for regular informa‐
3501 ing el tion, or level=debug for additional
3502 information. In Unified Logging
3503 syntax, -verbose:class equals
3504 -Xlog:class+load=info,class+un‐
3505 load=info.
3506 TraceClassLoad‐ -Xlog:class+pre‐ Not Applicable
3507 ingPreorder order=debug
3508 TraceClassUn‐ -Xlog:class+un‐ Use level=info for regular informa‐
3509 loading load=level tion, or level=trace for additional
3510 information. In Unified Logging
3511 syntax, -verbose:class equals
3512 -Xlog:class+load=info,class+un‐
3513 load=info.
3514 VerboseVerifi‐ -Xlog:verifica‐ Not Applicable
3515 cation tion=info
3516 TraceClassPaths -Xlog:class+path=info Not Applicable
3517 TraceClassReso‐ -Xlog:class+re‐ Not Applicable
3518 lution solve=debug
3519 TraceClassIni‐ -Xlog:class+init=info Not Applicable
3520 tialization
3521 TraceLoaderCon‐ -Xlog:class+load‐ Not Applicable
3522 straints er+constraints=info
3523 TraceClassLoad‐ -Xlog:class+load‐ Use level=debug for regular infor‐
3524 erData er+data=level mation or level=trace for addition‐
3525 al information.
3526 TraceSafepoint‐ -Xlog:safe‐ Not Applicable
3527 CleanupTime point+cleanup=info
3528 TraceSafepoint -Xlog:safepoint=debug Not Applicable
3529 TraceMonitorIn‐ -Xlog:monitorinfla‐ Not Applicable
3530 flation tion=debug
3531 TraceRede‐ -Xlog:rede‐ level=info, debug, and trace pro‐
3532 fineClasses fine+class*=level vide increasing amounts of informa‐
3533 tion.
3534 -Xlog Usage Examples
3536 The following are -Xlog examples.
3537 -Xlog Logs all messages by using the info level to stdout with uptime,
3539 levels, and tags decorations. This is equivalent to using:
3540 -Xlog:all=info:stdout:uptime,levels,tags
3542 -Xlog:gc
3544 Logs messages tagged with the gc tag using info level to stdout.
3545 The default configuration for all other messages at level warn‐
3546 ing is in effect.
3547 -Xlog:gc,safepoint
3549 Logs messages tagged either with the gc or safepoint tags, both
3550 using the info level, to stdout, with default decorations. Mes‐
3551 sages tagged with both gc and safepoint won't be logged.
3552 -Xlog:gc+ref=debug
3554 Logs messages tagged with both gc and ref tags, using the debug
3555 level to stdout, with default decorations. Messages tagged only
3556 with one of the two tags won't be logged.
3557 -Xlog:gc=debug:file=gc.txt:none
3559 Logs messages tagged with the gc tag using the debug level to a
3560 file called gc.txt with no decorations. The default configura‐
3561 tion for all other messages at level warning is still in effect.
3562 -Xlog:gc=trace:file=gctrace.txt:uptimemillis,pids:filecount=5,file‐
3564 size=1024
3565 Logs messages tagged with the gc tag using the trace level to a
3566 rotating file set with 5 files with size 1 MB with the base name
3567 gctrace.txt and uses decorations uptimemillis and pid.
3568 The default configuration for all other messages at level warn‐
3570 ing is still in effect.
3571 -Xlog:gc::uptime,tid
3573 Logs messages tagged with the gc tag using the default 'info'
3574 level to default the output stdout and uses decorations uptime
3575 and tid. The default configuration for all other messages at
3576 level warning is still in effect.
3577 -Xlog:gc*=info,safepoint*=off
3579 Logs messages tagged with at least gc using the info level, but
3580 turns off logging of messages tagged with safepoint. Messages
3581 tagged with both gc and safepoint won't be logged.
3582 -Xlog:disable -Xlog:safepoint=trace:safepointtrace.txt
3584 Turns off all logging, including warnings and errors, and then
3585 enables messages tagged with safepointusing tracelevel to the
3586 file safepointtrace.txt. The default configuration doesn't ap‐
3587 ply, because the command line started with -Xlog:disable.
3588 Complex -Xlog Usage Examples
3590 The following describes a few complex examples of using the -Xlog op‐
3591 tion.
3592 -Xlog:gc+class*=debug
3594 Logs messages tagged with at least gc and class tags using the
3595 debug level to stdout. The default configuration for all other
3596 messages at the level warning is still in effect
3597 -Xlog:gc+meta*=trace,class*=off:file=gcmetatrace.txt
3599 Logs messages tagged with at least the gc and meta tags using
3600 the trace level to the file metatrace.txt but turns off all mes‐
3601 sages tagged with class. Messages tagged with gc, meta, and
3602 class aren't be logged as class* is set to off. The default
3603 configuration for all other messages at level warning is in ef‐
3604 fect except for those that include class.
3605 -Xlog:gc+meta=trace
3607 Logs messages tagged with exactly the gc and meta tags using the
3608 trace level to stdout. The default configuration for all other
3609 messages at level warning is still be in effect.
3610 -Xlog:gc+class+heap*=debug,meta*=warning,threads*=off
3612 Logs messages tagged with at least gc, class, and heap tags us‐
3613 ing the trace level to stdout but only log messages tagged with
3614 meta with level. The default configuration for all other mes‐
3615 sages at the level warning is in effect except for those that
3616 include threads.
3617
3619 You use values provided to all Java Virtual Machine (JVM) command-line
3620 flags for validation and, if the input value is invalid or
3621 out-of-range, then an appropriate error message is displayed.
3622 Whether they're set ergonomically, in a command line, by an input tool,
3624 or through the APIs (for example, classes contained in the package ja‐
3625 va.lang.management) the values provided to all Java Virtual Machine
3626 (JVM) command-line flags are validated. Ergonomics are described in
3627 Java Platform, Standard Edition HotSpot Virtual Machine Garbage Collec‐
3628 tion Tuning Guide.
3629 Range and constraints are validated either when all flags have their
3631 values set during JVM initialization or a flag's value is changed dur‐
3632 ing runtime (for example using the jcmd tool). The JVM is terminated
3633 if a value violates either the range or constraint check and an appro‐
3634 priate error message is printed on the error stream.
3635 For example, if a flag violates a range or a constraint check, then the
3637 JVM exits with an error:
3638 java -XX:AllocatePrefetchStyle=5 -version
3640 intx AllocatePrefetchStyle=5 is outside the allowed range [ 0 ... 3 ]
3641 Improperly specified VM option 'AllocatePrefetchStyle=5'
3642 Error: Could not create the Java Virtual Machine.
3643 Error: A fatal exception has occurred. Program will exit.
3644 The flag -XX:+PrintFlagsRanges prints the range of all the flags. This
3646 flag allows automatic testing of the flags by the values provided by
3647 the ranges. For the flags that have the ranges specified, the type,
3648 name, and the actual range is printed in the output.
3649 For example,
3651 intx ThreadStackSize [ 0 ... 9007199254740987 ] {pd product}
3653 For the flags that don't have the range specified, the values aren't
3655 displayed in the print out. For example:
3656 size_t NewSize [ ... ] {product}
3658 This helps to identify the flags that need to be implemented. The au‐
3660 tomatic testing framework can skip those flags that don't have values
3661 and aren't implemented.
3662
3664 You use large pages, also known as huge pages, as memory pages that are
3665 significantly larger than the standard memory page size (which varies
3666 depending on the processor and operating system). Large pages optimize
3667 processor Translation-Lookaside Buffers.
3668 A Translation-Lookaside Buffer (TLB) is a page translation cache that
3670 holds the most-recently used virtual-to-physical address translations.
3671 A TLB is a scarce system resource. A TLB miss can be costly because
3672 the processor must then read from the hierarchical page table, which
3673 may require multiple memory accesses. By using a larger memory page
3674 size, a single TLB entry can represent a larger memory range. This re‐
3675 sults in less pressure on a TLB, and memory-intensive applications may
3676 have better performance.
3677 However, using large pages can negatively affect system performance.
3679 For example, when a large amount of memory is pinned by an application,
3680 it may create a shortage of regular memory and cause excessive paging
3681 in other applications and slow down the entire system. Also, a system
3682 that has been up for a long time could produce excessive fragmentation,
3683 which could make it impossible to reserve enough large page memory.
3684 When this happens, either the OS or JVM reverts to using regular pages.
3685 Linux and Windows support large pages.
3687 Large Pages Support for Linux
3689 Linux supports large pages since version 2.6. To check if your envi‐
3690 ronment supports large pages, try the following:
3691 # cat /proc/meminfo | grep Huge
3693 HugePages_Total: 0
3694 HugePages_Free: 0
3695 ...
3696 Hugepagesize: 2048 kB
3697 If the output contains items prefixed with "Huge", then your system
3699 supports large pages. The values may vary depending on environment.
3700 The Hugepagesize field shows the default large page size in your envi‐
3701 ronment, and the other fields show details for large pages of this
3702 size. Newer kernels have support for multiple large page sizes. To
3703 list the supported page sizes, run this:
3704 # ls /sys/kernel/mm/hugepages/
3706 hugepages-1048576kB hugepages-2048kB
3707 The above environment supports 2 MB and 1 GB large pages, but they need
3709 to be configured so that the JVM can use them. When using large pages
3710 and not enabling transparent huge pages (option -XX:+UseTransparen‐
3711 tHugePages), the number of large pages must be pre-allocated. For ex‐
3712 ample, to enable 8 GB of memory to be backed by 2 MB large pages, login
3713 as root and run:
3714 # echo 4096 > /sys/ker‐
3716 nel/mm/hugepages/hugepages-2048kB/nr_hugepages
3717 It is always recommended to check the value of nr_hugepages after the
3719 request to make sure the kernel was able to allocate the requested num‐
3720 ber of large pages.
3721 When using the option -XX:+UseSHM to enable large pages you also need
3723 to make sure the SHMMAX parameter is configured to allow large enough
3724 shared memory segments to be allocated. To allow a maximum shared seg‐
3725 ment of 8 GB, login as root and run:
3726 # echo 8589934592 > /proc/sys/kernel/shmmax
3728 In some environments this is not needed since the default value is
3730 large enough, but it is important to make sure the value is large
3731 enough to fit the amount of memory intended to be backed by large
3732 pages.
3733 Note: The values contained in /proc and /sys reset after you re‐
3735 boot your system, so may want to set them in an initialization
3736 script (for example, rc.local or sysctl.conf).
3737 If you configure the OS kernel parameters to enable use of large pages,
3739 the Java processes may allocate large pages for the Java heap as well
3740 as other internal areas, for example:
3741 • Code cache
3743 • Marking bitmaps
3745 Consequently, if you configure the nr_hugepages parameter to the size
3747 of the Java heap, then the JVM can still fail to allocate the heap us‐
3748 ing large pages because other areas such as the code cache might al‐
3749 ready have used some of the configured large pages.
3750 Large Pages Support for Windows
3752 To use large pages support on Windows, the administrator must first as‐
3753 sign additional privileges to the user who is running the application:
3754 1. Select Control Panel, Administrative Tools, and then Local Security
3756 Policy.
3757 2. Select Local Policies and then User Rights Assignment.
3759 3. Double-click Lock pages in memory, then add users and/or groups.
3761 4. Reboot your system.
3763 Note that these steps are required even if it's the administrator who's
3765 running the application, because administrators by default don't have
3766 the privilege to lock pages in memory.
3767
3769 Application Class Data Sharing (AppCDS) extends class data sharing
3770 (CDS) to enable application classes to be placed in a shared archive.
3771 In addition to the core library classes, AppCDS supports Class Data
3773 Sharing [https://docs.oracle.com/en/java/javase/12/vm/class-data-shar‐
3774 ing.html#GUID-7EAA3411-8CF0-4D19-BD05-DF5E1780AA91] from the following
3775 locations:
3776 • Platform classes from the runtime image
3778 • Application classes from the runtime image
3780 • Application classes from the class path
3782 • Application classes from the module path
3784 Archiving application classes provides better start up time at runtime.
3786 When running multiple JVM processes, AppCDS also reduces the runtime
3787 footprint with memory sharing for read-only metadata.
3788 CDS/AppCDS supports archiving classes from JAR files only.
3790 Prior to JDK 11, a non-empty directory was reported as a fatal error in
3792 the following conditions:
3793 • For base CDS, a non-empty directory cannot exist in the -Xbootclass‐
3795 path/a path
3796 • With -XX:+UseAppCDS, a non-empty directory could not exist in the
3798 -Xbootclasspath/a path, class path, and module path.
3799 In JDK 11 and later, -XX:+UseAppCDS is obsolete and the behavior for a
3801 non-empty directory is based on the class types in the classlist. A
3802 non-empty directory is reported as a fatal error in the following con‐
3803 ditions:
3804 • If application classes or platform classes are not loaded, dump time
3806 only reports an error if a non-empty directory exists in -Xbootclass‐
3807 path/a path
3808 • If application classes or platform classes are loaded, dump time re‐
3810 ports an error for a non-empty directory that exists in -Xbootclass‐
3811 path/a path, class path, or module path
3812 In JDK 11 and later, using -XX:DumpLoadedClassList=class_list_file re‐
3814 sults a generated classlist with all classes (both system library
3815 classes and application classes) included. You no longer have to spec‐
3816 ify -XX:+UseAppCDS with -XX:DumpLoadedClassList to produce a complete
3817 class list.
3818 In JDK 11 and later, because UseAppCDS is obsolete, SharedArchiveFile
3820 becomes a product flag by default. Specifying +UnlockDiagnosticVMOp‐
3821 tions for SharedArchiveFile is no longer needed in any configuration.
3822 Class Data Sharing (CDS)/AppCDS does not support archiving array class‐
3824 es in a class list. When an array in the class list is encountered,
3825 CDS dump time gives the explicit error message:
3826 Preload Warning: Cannot find array_name
3828 Although an array in the class list is not allowed, some array classes
3830 can still be created at CDS/AppCDS dump time. Those arrays are created
3831 during the execution of the Java code used by the Java class loaders
3832 (PlatformClassLoader and the system class loader) to load classes at
3833 dump time. The created arrays are archived with the rest of the loaded
3834 classes.
3835 Extending Class Data Sharing to Support the Module Path
3837 In JDK 11, Class Data Sharing (CDS) has been improved to support ar‐
3838 chiving classes from the module path.
3839 • To create a CDS archive using the --module-path VM option, use the
3841 following command line syntax:
3842 java -Xshare:dump -XX:SharedClassListFile=class_list_file
3844 -XX:SharedArchiveFile=shared_archive_file --mod‐
3845 ule-path=path_to_modular_jar -m module_name
3846 • To run with a CDS archive using the --module-path VM option, use the
3848 following the command line syntax:
3849 java -XX:SharedArchiveFile=shared_archive_file --mod‐
3851 ule-path=path_to_modular_jar -m module_name
3852 The following table describes how the VM options related to module
3854 paths can be used along with the -Xshare option.
3855 Option -Xshare:dump -Xshare:{on,auto}
3857 ────────────────────────────────────────────────────────────────
3858 --module-path[1] mp Allowed Allowed[2]
3859 --module Allowed Allowed
3860 --add-module Allowed Allowed
3861 --upgrade-mod‐ Disallowed (exits Allowed (disables
3862 ule-path[3] if specified) CDS)
3863 --patch-module[4] Disallowed (exits Allowed (disables
3864 if specified) CDS)
3865 --limit-modules[5] Disallowed (exits Allowed (disables
3866 if specified) CDS)
3867 [1] Although there are two ways of specifying a module in a --mod‐
3869 ule-path, that is, modular JAR or exploded module, only modular JARs
3870 are supported.
3871 [2] Different mp can be specified during dump time versus run time. If
3873 an archived class K was loaded from mp1.jar at dump time, but changes
3874 in mp cause it to be available from a different mp2.jar at run time,
3875 then the archived version of K will be disregarded at run time; K will
3876 be loaded dynamically.
3877 [3] Currently, only two system modules are upgradeable (java.compiler
3879 and jdk.internal.vm.compiler). However, these modules are seldom up‐
3880 graded in production software.
3881 [4] As documented in JEP 261, using --patch-module is strongly discour‐
3883 aged for production use.
3884 [5] --limit-modules is intended for testing purposes. It is seldom
3886 used in production software.
3887 If --upgrade-module-path, --patch-module, or --limit-modules is speci‐
3889 fied at dump time, an error will be printed and the JVM will exit. For
3890 example, if the --limit-modules option is specified at dump time, the
3891 user will see the following error:
3892 Error occurred during initialization of VM
3894 Cannot use the following option when dumping the shared archive: --limit-modules
3895 If --upgrade-module-path, --patch-module, or --limit-modules is speci‐
3897 fied at run time, a warning message will be printed indicating that CDS
3898 is disabled. For example, if the --limit-modules options is specified
3899 at run time, the user will see the following warning:
3900 Java HotSpot(TM) 64-Bit Server VM warning: CDS is disabled when the --limit-modules option is specified.
3902 Several other noteworthy things include:
3904 • Any valid combinations of -cp and --module-path are supported.
3906 • A non-empty directory in the module path causes a fatal error. The
3908 user will see the following error messages:
3909 Error: non-empty directory <directory> Hint: enable -Xlog:class+path=info to diagnose the failure Error occurred during initialization of VM Cannot have non-empty directory in paths
3911 • Unlike the class path, there's no restriction that the module path at
3913 dump time must be equal to or be a prefix of the module path at run
3914 time.
3915 • The archive is invalidated if an existing JAR in the module path is
3917 updated after archive generation.
3918 • Removing a JAR from the module path does not invalidate the shared
3920 archive. Archived classes from the removed JAR are not used at run‐
3921 time.
3922 Dynamic CDS archive
3924 Dynamic CDS archive extends AppCDS to allow archiving of classes when a
3925 Java application exits. It improves the usability of AppCDS by elimi‐
3926 nating the trial run step for creating a class list for each applica‐
3927 tion. The archived classes include all loaded application classes and
3928 library classes that are not present in the default CDS archive which
3929 is included in the JDK.
3930 A base archive is required when creating a dynamic archive. If the
3932 base archive is not specified, the default CDS archive is used as the
3933 base archive.
3934 To create a dynamic CDS archive with the default CDS archive as the
3936 base archive, just add the -XX:ArchiveClassesAtExit=<dynamic archive>
3937 option to the command line for running the Java application.
3938 If the default CDS archive does not exist, the VM will exit with the
3940 following error:
3941 ArchiveClassesAtExit not supported when base CDS archive is not loaded
3943 To run the Java application using a dynamic CDS archive, just add the
3945 -XX:SharedArchiveFile=<dynamic archive> option to the command line for
3946 running the Java application.
3947 The base archive is not required to be specified in the command line.
3949 The base archive information, including its name and full path, will be
3950 retrieved from the dynamic archive header. Note that the user could
3951 also use the -XX:SharedArchiveFile option for specifying a regular Ap‐
3952 pCDS archive. Therefore, the specified archive in the
3953 -XX:SharedArchiveFile option could be either a regular or dynamic ar‐
3954 chive. During VM start up the specified archive header will be read.
3955 If -XX:SharedArchiveFile refers to a regular archive, then the behavior
3956 will be unchanged. If -XX:SharedArchiveFile refers to a dynamic ar‐
3957 chive, the VM will retrieve the base archive location from the dynamic
3958 archive. If the dynamic archive was created with the default CDS ar‐
3959 chive, then the current default CDS archive will be used, and will be
3960 found relative to the current run time environment.
3961 Please refer to JDK-8221706 [https://bugs.openjdk.ja‐
3963 va.net/browse/JDK-8221706] for details on error checking during dynamic
3964 CDS archive dump time and run time.
3965 Creating a Shared Archive File and Using It to Run an Application
3967 AppCDS archive
3968 The following steps create a shared archive file that contains all the
3969 classes used by the test.Hello application. The last step runs the ap‐
3970 plication with the shared archive file.
3971 1. Create a list of all classes used by the test.Hello application.
3973 The following command creates a file named hello.classlist that con‐
3974 tains a list of all classes used by this application:
3975 java -Xshare:off -XX:DumpLoadedClassList=hel‐
3977 lo.classlist -cp hello.jar test.Hello
3978 Note that the classpath specified by the -cp parameter must contain
3980 only JAR files.
3981 2. Create a shared archive, named hello.jsa, that contains all the
3983 classes in hello.classlist:
3984 java -Xshare:dump -XX:SharedArchiveFile=hel‐
3986 lo.jsa -XX:SharedClassListFile=hello.classlist -cp hello.jar
3987 Note that the classpath used at archive creation time must be the
3989 same as (or a prefix of) the classpath used at run time.
3990 3. Run the application test.Hello with the shared archive hello.jsa:
3992 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hel‐
3994 lo
3995 4. Optional Verify that the test.Hello application is using the class
3997 contained in the hello.jsa shared archive:
3998 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar -ver‐
4000 bose:class test.Hello
4001 The output of this command should contain the following text:
4003 Loaded test.Hello from shared objects file by sun/misc/Launcher$AppClassLoader
4005 Dynamic CDS archive
4007 The following steps create a dynamic CDS archive file that contains the
4008 classes used by the test.Hello application and are not included in the
4009 default CDS archive. The second step runs the application with the dy‐
4010 namic CDS archive.
4011 1. Create a dynamic CDS archive, named hello.jsa, that contains all the
4013 classes in hello.jar loaded by the application test.Hello:
4014 java -XX:ArchiveClassesAtExit=hello.jsa -cp hello.jar Hello
4016 Note that the classpath used at archive creation time must be the
4018 same as (or a prefix of) the classpath used at run time.
4019 2. Run the application test.Hello with the shared archive hello.jsa:
4021 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hel‐
4023 lo
4024 3. Optional Repeat step 4 of the previous section to verify that the
4026 test.Hello application is using the class contained in the hello.jsa
4027 shared archive.
4028 To automate the above steps 1 and 2, one can write a script such as the
4030 following:
4031 ARCHIVE=hello.jsa
4033 if test -f $ARCHIVE; then
4034 FLAG="-XX:SharedArchiveFile=$ARCHIVE"
4035 else
4036 FLAG="-XX:ArchiveClassesAtExit=$ARCHIVE"
4037 fi
4038 $JAVA_HOME/bin/java -cp hello.jar $FLAG test.Hello
4039 Like an AppCDS archive, the archive needs to be re-generated if the Ja‐
4041 va version has changed. The above script could be adjusted to account
4042 for the Java version as follows:
4043 ARCHIVE=hello.jsa
4045 VERSION=foo.version
4046 if test -f $ARCHIVE -a -f $VERSION && cmp -s $VERSION $JAVA_HOME/release; then
4047 FLAG="-XX:SharedArchiveFile=$ARCHIVE"
4048 else
4049 FLAG="-XX:ArchiveClassesAtExit=$ARCHIVE"
4050 cp -f $JAVA_HOME/release $VERSION
4051 fi
4052 $JAVA_HOME/bin/java -cp hello.jar $FLAG test.Hello
4053 Currently, we don't support concurrent dumping operations to the same
4055 CDS archive. Care should be taken to avoid multiple writers to the
4056 same CDS archive.
4057 The user could also create a dynamic CDS archive with a specific base
4059 archive, e.g. named as base.jsa as follows:
4060 java -XX:SharedArchiveFile=base.jsa -XX:ArchiveClassesAtEx‐
4062 it=hello.jsa -cp hello.jar Hello
4063 To run the application using the dynamic CDS archive hello.jsa and a
4065 specific base CDS archive base.jsa:
4066 java -XX:SharedArchiveFile=base.jsa:hello.jsa -cp hello.jar Hel‐
4068 lo
4069 Note that on Windows, the above path delimiter : should be replaced
4071 with ;.
4072 The above command for specifying a base archive is useful if the base
4074 archive used for creating the dynamic archive has been moved. Normal‐
4075 ly, just specifying the dynamic archive should be sufficient since the
4076 base archive info can be retrieved from the dynamic archive header.
4077 Sharing a Shared Archive Across Multiple Application Processes
4079 You can share the same archive file across multiple applications pro‐
4080 cesses. This reduces memory usage because the archive is memory-mapped
4081 into the address space of the processes. The operating system automat‐
4082 ically shares the read-only pages across these processes.
4083 The following steps demonstrate how to create a common archive that can
4085 be shared by different applications. Classes from common.jar, hel‐
4086 lo.jar and hi.jar are archived in the common.jsa because they are all
4087 in the classpath during the archiving step (step 3).
4088 To include classes from hello.jar and hi.jar, the .jar files must be
4090 added to the classpath specified by the -cp parameter.
4091 1. Create a list of all classes used by the Hello application and an‐
4093 other list for the Hi application:
4094 java -XX:DumpLoadedClassList=hello.classlist -cp com‐
4096 mon.jar:hello.jar Hello
4097 java -XX:DumpLoadedClassList=hi.classlist -cp com‐
4099 mon.jar:hi.jar Hi
4100 2. Create a single list of classes used by all the applications that
4102 will share the shared archive file.
4103 Linux and macOS The following commands combine the files hel‐
4105 lo.classlist and hi.classlist into one file, common.classlist:
4106 cat hello.classlist hi.classlist > common.classlist
4108 Windows The following commands combine the files hello.classlist
4110 and hi.classlist into one file, common.classlist:
4111 type hello.classlist hi.classlist > common.classlist
4113 3. Create a shared archive named common.jsa that contains all the
4115 classes in common.classlist:
4116 java -Xshare:dump -XX:SharedArchiveFile=com‐
4118 mon.jsa -XX:SharedClassListFile=common.classlist -cp com‐
4119 mon.jar:hello.jar:hi.jar
4120 The classpath parameter used is the common class path prefix shared
4122 by the Hello and Hi applications.
4123 4. Run the Hello and Hi applications with the same shared archive:
4125 java -XX:SharedArchiveFile=common.jsa -cp common.jar:hel‐
4127 lo.jar:hi.jar Hello
4128 java -XX:SharedArchiveFile=common.jsa -cp common.jar:hel‐
4130 lo.jar:hi.jar Hi
4131 Specifying Additional Shared Data Added to an Archive File
4133 The SharedArchiveConfigFile option is used to specify additional shared
4134 data to add to the archive file.
4135 -XX:SharedArchiveConfigFile=shared_config_file
4137 JDK 9 and later supports adding both symbols and string objects to an
4139 archive for memory sharing when you have multiple JVM processes running
4140 on the same host. An example of this is having multiple JVM processes
4141 that use the same set of Java EE classes. When these common classes
4142 are loaded and used, new symbols and strings may be created and added
4143 to the JVM's internal "symbol" and "string" tables. At runtime, the
4144 symbols or string objects mapped from the archive file can be shared
4145 across multiple JVM processes, resulting in a reduction of overall mem‐
4146 ory usage. In addition, archiving strings also provides added perfor‐
4147 mance benefits in both startup time and runtime execution.
4148 In JDK 10 and later, CONSTANT_String entries in archived classes are
4150 resolved to interned String objects at dump time, and all interned
4151 String objects are archived. However, even though all CONSTANT_String
4152 literals in all archived classes are resolved, it might still benefi‐
4153 cial to add additional strings that are not string literals in class
4154 files, but are likely to be used by your application at run time.
4155 Symbol data should be generated by the jcmd tool attaching to a running
4157 JVM process. See jcmd.
4158 The following is an example of the symbol dumping command in jcmd:
4160 jcmd pid VM.symboltable -verbose
4162 Note: The first line (process ID) and the second line (@VER‐
4164 SION ...) of this jcmd output should be excluded from the con‐
4165 figuration file.
4166 Example of a Configuration File
4168 The following is an example of a configuration file:
4169 VERSION: 1.0
4171 @SECTION: Symbol
4172 10 -1: linkMethod
4173 In the configuration file example, the @SECTION: Symbol entry uses the
4175 following format:
4176 length refcount: symbol
4178 The refcount for a shared symbol is always -1.
4180 @SECTION specifies the type of the section that follows it. All data
4182 within the section must be the same type that's specified by @SECTION.
4183 Different types of data can't be mixed. Multiple separated data sec‐
4184 tions for the same type specified by different @SECTION are allowed
4185 within one shared_config_file .
4186
4188 You can use the Java advanced runtime options to optimize the perfor‐
4189 mance of your applications.
4190 Tuning for Higher Throughput
4192 Use the following commands and advanced options to achieve higher
4193 throughput performance for your application:
4194 java -server -XX:+UseParallelGC -XX:+Use‐
4196 LargePages -Xmn10g -Xms26g -Xmx26g
4197 Tuning for Lower Response Time
4199 Use the following commands and advanced options to achieve lower re‐
4200 sponse times for your application:
4201 java -XX:+UseG1GC -XX:MaxGCPauseMillis=100
4203 Keeping the Java Heap Small and Reducing the Dynamic Footprint of
4205 Embedded Applications
4206 Use the following advanced runtime options to keep the Java heap small
4208 and reduce the dynamic footprint of embedded applications:
4209 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
4211 Note: The defaults for these two options are 70% and 40% respec‐
4213 tively. Because performance sacrifices can occur when using
4214 these small settings, you should optimize for a small footprint
4215 by reducing these settings as much as possible without introduc‐
4216 ing unacceptable performance degradation.
4217
4219 The following exit values are typically returned by the launcher when
4220 the launcher is called with the wrong arguments, serious errors, or ex‐
4221 ceptions thrown by the JVM. However, a Java application may choose to
4222 return any value by using the API call System.exit(exitValue). The
4223 values are:
4224 • 0: Successful completion
4226 • >0: An error occurred
4228JDK 18 2022 JAVA(1)