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 Source-
61 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 Source-
79 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 (21) and a
123 limited number of previous releases, detailed in the command-
124 line help for javac, under the --source and --release options.
125 If the file does not have the .java extension, the --source option must
127 be used to tell the java command to use the source-file mode. The
128 --source option is used for cases when the source file is a "script" to
129 be executed and the name of the source file does not follow the normal
130 naming conventions for Java source files.
131 In source-file mode, the effect is as though the source file is com‐
133 piled into memory, and the first class found in the source file is exe‐
134 cuted. Any arguments placed after the name of the source file in the
135 original command line are passed to the compiled class when it is exe‐
136 cuted.
137 For example, if a file were named HelloWorld.java and contained a class
139 named hello.World, then the source-file mode command to launch the
140 class would be:
141 java HelloWorld.java
143 The example illustrates that the class can be in a named package, and
145 does not need to be in the unnamed package. This use of source-file
146 mode is informally equivalent to using the following two commands where
147 hello.World is the name of the class in the package:
148 javac -d <memory> HelloWorld.java
150 java -cp <memory> hello.World
151 In source-file mode, any additional command-line options are processed
153 as follows:
154 • The launcher scans the options specified before the source file for
156 any that are relevant in order to compile the source file.
157 This includes: --class-path, --module-path, --add-exports, --add-mod‐
159 ules, --limit-modules, --patch-module, --upgrade-module-path, and any
160 variant forms of those options. It also includes the new --enable-
161 preview option, described in JEP 12.
162 • No provision is made to pass any additional options to the compiler,
164 such as -processor or -Werror.
165 • Command-line argument files (@-files) may be used in the standard
167 way. Long lists of arguments for either the VM or the program being
168 invoked may be placed in files specified on the command-line by pre‐
169 fixing the filename with an @ character.
170 In source-file mode, compilation proceeds as follows:
172 • Any command-line options that are relevant to the compilation envi‐
174 ronment are taken into account.
175 • No other source files are found and compiled, as if the source path
177 is set to an empty value.
178 • Annotation processing is disabled, as if -proc:none is in effect.
180 • If a version is specified, via the --source option, the value is used
182 as the argument for an implicit --release option for the compilation.
183 This sets both the source version accepted by compiler and the system
184 API that may be used by the code in the source file.
185 • The source file is compiled in the context of an unnamed module.
187 • The source file should contain one or more top-level classes, the
189 first of which is taken as the class to be executed.
190 • The compiler does not enforce the optional restriction defined at the
192 end of JLS 7.6, that a type in a named package should exist in a file
193 whose name is composed from the type name followed by the .java ex‐
194 tension.
195 • If the source file contains errors, appropriate error messages are
197 written to the standard error stream, and the launcher exits with a
198 non-zero exit code.
199 In source-file mode, execution proceeds as follows:
201 • The class to be executed is the first top-level class found in the
203 source file. It must contain a declaration of the standard public
204 static void main(String[]) method.
205 • The compiled classes are loaded by a custom class loader, that dele‐
207 gates to the application class loader. This implies that classes ap‐
208 pearing on the application class path cannot refer to any classes de‐
209 clared in the source file.
210 • The compiled classes are executed in the context of an unnamed mod‐
212 ule, as though --add-modules=ALL-DEFAULT is in effect. This is in
213 addition to any other --add-module options that may be have been
214 specified on the command line.
215 • Any arguments appearing after the name of the file on the command
217 line are passed to the standard main method in the obvious way.
218 • It is an error if there is a class on the application class path
220 whose name is the same as that of the class to be executed.
221 See JEP 330: Launch Single-File Source-Code Programs [https://open‐
223 jdk.org/jeps/330] for complete details.
224
226 JDK_JAVA_OPTIONS prepends its content to the options parsed from the
227 command line. The content of the JDK_JAVA_OPTIONS environment variable
228 is a list of arguments separated by white-space characters (as deter‐
229 mined by isspace()). These are prepended to the command line arguments
230 passed to java launcher. The encoding requirement for the environment
231 variable is the same as the java command line on the system. JDK_JA‐
232 VA_OPTIONS environment variable content is treated in the same manner
233 as that specified in the command line.
234 Single (') or double (") quotes can be used to enclose arguments that
236 contain whitespace characters. All content between the open quote and
237 the first matching close quote are preserved by simply removing the
238 pair of quotes. In case a matching quote is not found, the launcher
239 will abort with an error message. @-files are supported as they are
240 specified in the command line. However, as in @-files, use of a wild‐
241 card is not supported. In order to mitigate potential misuse of
242 JDK_JAVA_OPTIONS behavior, options that specify the main class (such as
243 -jar) or cause the java launcher to exit without executing the main
244 class (such as -h) are disallowed in the environment variable. If any
245 of these options appear in the environment variable, the launcher will
246 abort with an error message. When JDK_JAVA_OPTIONS is set, the launch‐
247 er prints a message to stderr as a reminder.
248 Example:
250 $ export JDK_JAVA_OPTIONS='-g @file1 -Dprop=value @file2 -Dws.prop="white spaces"'
252 $ java -Xint @file3
253 is equivalent to the command line:
255 java -g @file1 -Dprop=value @file2 -Dws.prop="white spaces" -Xint @file3
257
259 The java command supports a wide range of options in the following cat‐
260 egories:
261 • Standard Options for Java: Options guaranteed to be supported by all
263 implementations of the Java Virtual Machine (JVM). They're used for
264 common actions, such as checking the version of the JRE, setting the
265 class path, enabling verbose output, and so on.
266 • Extra Options for Java: General purpose options that are specific to
268 the Java HotSpot Virtual Machine. They aren't guaranteed to be sup‐
269 ported by all JVM implementations, and are subject to change. These
270 options start with -X.
271 The advanced options aren't recommended for casual use. These are de‐
273 veloper options used for tuning specific areas of the Java HotSpot Vir‐
274 tual Machine operation that often have specific system requirements and
275 may require privileged access to system configuration parameters. Sev‐
276 eral examples of performance tuning are provided in Performance Tuning
277 Examples. These options aren't guaranteed to be supported by all JVM
278 implementations and are subject to change. Advanced options start with
279 -XX.
280 • Advanced Runtime Options for Java: Control the runtime behavior of
282 the Java HotSpot VM.
283 • Advanced JIT Compiler Options for java: Control the dynamic just-in-
285 time (JIT) compilation performed by the Java HotSpot VM.
286 • Advanced Serviceability Options for Java: Enable gathering system in‐
288 formation and performing extensive debugging.
289 • Advanced Garbage Collection Options for Java: Control how garbage
291 collection (GC) is performed by the Java HotSpot
292 Boolean options are used to either enable a feature that's disabled by
294 default or disable a feature that's enabled by default. Such options
295 don't require a parameter. Boolean -XX options are enabled using the
296 plus sign (-XX:+OptionName) and disabled using the minus sign (-XX:-Op‐
297 tionName).
298 For options that require an argument, the argument may be separated
300 from the option name by a space, a colon (:), or an equal sign (=), or
301 the argument may directly follow the option (the exact syntax differs
302 for each option). If you're expected to specify the size in bytes,
303 then you can use no suffix, or use the suffix k or K for kilobytes
304 (KB), m or M for megabytes (MB), or g or G for gigabytes (GB). For ex‐
305 ample, to set the size to 8 GB, you can specify either 8g, 8192m,
306 8388608k, or 8589934592 as the argument. If you are expected to speci‐
307 fy the percentage, then use a number from 0 to 1. For example, specify
308 0.25 for 25%.
309 The following sections describe the options that are deprecated, obso‐
311 lete, and removed:
312 • Deprecated Java Options: Accepted and acted upon --- a warning is is‐
314 sued when they're used.
315 • Obsolete Java Options: Accepted but ignored --- a warning is issued
317 when they're used.
318 • Removed Java Options: Removed --- using them results in an error.
320
322 These are the most commonly used options supported by all implementa‐
323 tions of the JVM.
324 Note: To specify an argument for a long option, you can use ei‐
326 ther --name=value or --name value.
327 -agentlib:libname[=options]
329 Loads the specified native agent library. After the library
330 name, a comma-separated list of options specific to the library
331 can be used. If the option -agentlib:foo is specified, then the
332 JVM attempts to load the library named foo using the platform
333 specific naming conventions and locations:
334 • Linux and other POSIX-like platforms: The JVM attempts to load
336 the library named libfoo.so in the location specified by the
337 LD_LIBRARY_PATH system variable.
338 • macOS: The JVM attempts to load the library named libfoo.dylib
340 in the location specified by the DYLD_LIBRARY_PATH system
341 variable.
342 • Windows: The JVM attempts to load the library named foo.dll in
344 the location specified by the PATH system variable.
345 The following example shows how to load the Java Debug Wire
347 Protocol (JDWP) library and listen for the socket connection
348 on port 8000, suspending the JVM before the main class loads:
349 -agentlib:jdwp=transport=dt_socket,server=y,ad‐
351 dress=8000
352 -agentpath:pathname[=options]
354 Loads the native agent library specified by the absolute path
355 name. This option is equivalent to -agentlib but uses the full
356 path and file name of the library.
357 --class-path classpath, -classpath classpath, or -cp classpath
359 Specifies a list of directories, JAR files, and ZIP archives to
360 search for class files.
361 On Windows, semicolons (;) separate entities in this list; on
363 other platforms it is a colon (:).
364 Specifying classpath overrides any setting of the CLASSPATH en‐
366 vironment variable. If the class path option isn't used and
367 classpath isn't set, then the user class path consists of the
368 current directory (.).
369 As a special convenience, a class path element that contains a
371 base name of an asterisk (*) is considered equivalent to speci‐
372 fying a list of all the files in the directory with the exten‐
373 sion .jar or .JAR . A Java program can't tell the difference
374 between the two invocations. For example, if the directory my‐
375 dir contains a.jar and b.JAR, then the class path element my‐
376 dir/* is expanded to A.jar:b.JAR, except that the order of JAR
377 files is unspecified. All .jar files in the specified directo‐
378 ry, even hidden ones, are included in the list. A class path
379 entry consisting of an asterisk (*) expands to a list of all the
380 jar files in the current directory. The CLASSPATH environment
381 variable, where defined, is similarly expanded. Any class path
382 wildcard expansion that occurs before the Java VM is started.
383 Java programs never see wildcards that aren't expanded except by
384 querying the environment, such as by calling Sys‐
385 tem.getenv("CLASSPATH").
386 --disable-@files
388 Can be used anywhere on the command line, including in an argu‐
389 ment file, to prevent further @filename expansion. This option
390 stops expanding @-argfiles after the option.
391 --enable-preview
393 Allows classes to depend on preview features [https://docs.ora‐
394 cle.com/en/java/javase/12/language/index.html#JSLAN-
395 GUID-5A82FE0E-0CA4-4F1F-B075-564874FE2823] of the release.
396 --finalization=value
398 Controls whether the JVM performs finalization of objects.
399 Valid values are "enabled" and "disabled". Finalization is en‐
400 abled by default, so the value "enabled" does nothing. The val‐
401 ue "disabled" disables finalization, so that no finalizers are
402 invoked.
403 --module-path modulepath... or -p modulepath
405 Specifies where to find application modules with a list of path
406 elements. The elements of a module path can be a file path to a
407 module or a directory containing modules. Each module is either
408 a modular JAR or an exploded-module directory.
409 On Windows, semicolons (;) separate path elements in this list;
411 on other platforms it is a colon (:).
412 --upgrade-module-path modulepath...
414 Specifies where to find module replacements of upgradeable mod‐
415 ules in the runtime image with a list of path elements. The el‐
416 ements of a module path can be a file path to a module or a di‐
417 rectory containing modules. Each module is either a modular JAR
418 or an exploded-module directory.
419 On Windows, semicolons (;) separate path elements in this list;
421 on other platforms it is a colon (:).
422 --add-modules module[,module...]
424 Specifies the root modules to resolve in addition to the initial
425 module. module also can be ALL-DEFAULT, ALL-SYSTEM, and ALL-
426 MODULE-PATH.
427 --list-modules
429 Lists the observable modules and then exits.
430 -d module_name or --describe-module module_name
432 Describes a specified module and then exits.
433 --dry-run
435 Creates the VM but doesn't execute the main method. This --dry-
436 run option might be useful for validating the command-line op‐
437 tions such as the module system configuration.
438 --validate-modules
440 Validates all modules and exit. This option is helpful for
441 finding conflicts and other errors with modules on the module
442 path.
443 -Dproperty=value
445 Sets a system property value. The property variable is a string
446 with no spaces that represents the name of the property. The
447 value variable is a string that represents the value of the
448 property. If value is a string with spaces, then enclose it in
449 quotation marks (for example -Dfoo="foo bar").
450 -disableassertions[:[packagename]...|:classname] or -da[:[package‐
452 name]...|:classname]
453 Disables assertions. By default, assertions are disabled in all
454 packages and classes. With no arguments, -disableassertions
455 (-da) disables assertions in all packages and classes. With the
456 packagename argument ending in ..., the switch disables asser‐
457 tions in the specified package and any subpackages. If the ar‐
458 gument is simply ..., then the switch disables assertions in the
459 unnamed package in the current working directory. With the
460 classname argument, the switch disables assertions in the speci‐
461 fied class.
462 The -disableassertions (-da) option applies to all class loaders
464 and to system classes (which don't have a class loader).
465 There's one exception to this rule: If the option is provided
466 with no arguments, then it doesn't apply to system classes.
467 This makes it easy to disable assertions in all classes except
468 for system classes. The -disablesystemassertions option enables
469 you to disable assertions in all system classes. To explicitly
470 enable assertions in specific packages or classes, use the -en‐
471 ableassertions (-ea) option. Both options can be used at the
472 same time. For example, to run the MyClass application with as‐
473 sertions enabled in the package com.wombat.fruitbat (and any
474 subpackages) but disabled in the class com.wombat.fruit‐
475 bat.Brickbat, use the following command:
476 java -ea:com.wombat.fruitbat... -da:com.wombat.fruit‐
478 bat.Brickbat MyClass
479 -disablesystemassertions or -dsa
481 Disables assertions in all system classes.
482 -enableassertions[:[packagename]...|:classname] or -ea[:[package‐
484 name]...|:classname]
485 Enables assertions. By default, assertions are disabled in all
486 packages and classes. With no arguments, -enableassertions
487 (-ea) enables assertions in all packages and classes. With the
488 packagename argument ending in ..., the switch enables asser‐
489 tions in the specified package and any subpackages. If the ar‐
490 gument is simply ..., then the switch enables assertions in the
491 unnamed package in the current working directory. With the
492 classname argument, the switch enables assertions in the speci‐
493 fied class.
494 The -enableassertions (-ea) option applies to all class loaders
496 and to system classes (which don't have a class loader).
497 There's one exception to this rule: If the option is provided
498 with no arguments, then it doesn't apply to system classes.
499 This makes it easy to enable assertions in all classes except
500 for system classes. The -enablesystemassertions option provides
501 a separate switch to enable assertions in all system classes.
502 To explicitly disable assertions in specific packages or class‐
503 es, use the -disableassertions (-da) option. If a single com‐
504 mand contains multiple instances of these switches, then they're
505 processed in order, before loading any classes. For example, to
506 run the MyClass application with assertions enabled only in the
507 package com.wombat.fruitbat (and any subpackages) but disabled
508 in the class com.wombat.fruitbat.Brickbat, use the following
509 command:
510 java -ea:com.wombat.fruitbat... -da:com.wombat.fruit‐
512 bat.Brickbat MyClass
513 -enablesystemassertions or -esa
515 Enables assertions in all system classes.
516 -help, -h, or -?
518 Prints the help message to the error stream.
519 --help Prints the help message to the output stream.
521 -javaagent:jarpath[=options]
523 Loads the specified Java programming language agent. See ja‐
524 va.lang.instrument.
525 --show-version
527 Prints the product version to the output stream and continues.
528 -showversion
530 Prints the product version to the error stream and continues.
531 --show-module-resolution
533 Shows module resolution output during startup.
534 -splash:imagepath
536 Shows the splash screen with the image specified by imagepath.
537 HiDPI scaled images are automatically supported and used if
538 available. The unscaled image file name, such as image.ext,
539 should always be passed as the argument to the -splash option.
540 The most appropriate scaled image provided is picked up automat‐
541 ically.
542 For example, to show the splash.gif file from the images direc‐
544 tory when starting your application, use the following option:
545 -splash:images/splash.gif
547 See the SplashScreen API documentation for more information.
549 -verbose:class
551 Displays information about each loaded class.
552 -verbose:gc
554 Displays information about each garbage collection (GC) event.
555 -verbose:jni
557 Displays information about the use of native methods and other
558 Java Native Interface (JNI) activity.
559 -verbose:module
561 Displays information about the modules in use.
562 --version
564 Prints product version to the output stream and exits.
565 -version
567 Prints product version to the error stream and exits.
568 -X Prints the help on extra options to the error stream.
570 --help-extra
572 Prints the help on extra options to the output stream.
573 @argfile
575 Specifies one or more argument files prefixed by @ used by the
576 java command. It isn't uncommon for the java command line to be
577 very long because of the .jar files needed in the classpath.
578 The @argfile option overcomes command-line length limitations by
579 enabling the launcher to expand the contents of argument files
580 after shell expansion, but before argument processing. Contents
581 in the argument files are expanded because otherwise, they would
582 be specified on the command line until the --disable-@files op‐
583 tion was encountered.
584 The argument files can also contain the main class name and all
586 options. If an argument file contains all of the options re‐
587 quired by the java command, then the command line could simply
588 be:
589 java @argfile
591 See java Command-Line Argument Files for a description and exam‐
593 ples of using @-argfiles.
594
596 The following java options are general purpose options that are specif‐
597 ic to the Java HotSpot Virtual Machine.
598 -Xbatch
600 Disables background compilation. By default, the JVM compiles
601 the method as a background task, running the method in inter‐
602 preter mode until the background compilation is finished. The
603 -Xbatch flag disables background compilation so that compilation
604 of all methods proceeds as a foreground task until completed.
605 This option is equivalent to -XX:-BackgroundCompilation.
606 -Xbootclasspath/a:directories|zip|JAR-files
608 Specifies a list of directories, JAR files, and ZIP archives to
609 append to the end of the default bootstrap class path.
610 On Windows, semicolons (;) separate entities in this list; on
612 other platforms it is a colon (:).
613 -Xcheck:jni
615 Performs additional checks for Java Native Interface (JNI) func‐
616 tions.
617 The following checks are considered indicative of significant
619 problems with the native code, and the JVM terminates with an
620 irrecoverable error in such cases:
621 • The thread doing the call is not attached to the JVM.
623 • The thread doing the call is using the JNIEnv belonging to an‐
625 other thread.
626 • A parameter validation check fails:
628 • A jfieldID, or jmethodID, is detected as being invalid. For
630 example:
631 • Of the wrong type
633 • Associated with the wrong class
635 • A parameter of the wrong type is detected.
637 • An invalid parameter value is detected. For example:
639 • NULL where not permitted
641 • An out-of-bounds array index, or frame capacity
643 • A non-UTF-8 string
645 • An invalid JNI reference
647 • An attempt to use a ReleaseXXX function on a parameter not
649 produced by the corresponding GetXXX function
650 The following checks only result in warnings being printed:
652 • A JNI call was made without checking for a pending exception
654 from a previous JNI call, and the current call is not safe
655 when an exception may be pending.
656 • A class descriptor is in decorated format (Lname;) when it
658 should not be.
659 • A NULL parameter is allowed, but its use is questionable.
661 • Calling other JNI functions in the scope of Get/ReleasePrimi‐
663 tiveArrayCritical or Get/ReleaseStringCritical
664 Expect a performance degradation when this option is used.
666 -Xcomp Testing mode to exercise JIT compilers. This option should not
668 be used in production environments.
669 -Xdebug
671 Does nothing. Provided for backward compatibility.
672 -Xdiag Shows additional diagnostic messages.
674 -Xint Runs the application in interpreted-only mode. Compilation to
676 native code is disabled, and all bytecode is executed by the in‐
677 terpreter. The performance benefits offered by the just-in-time
678 (JIT) compiler aren't present in this mode.
679 -Xinternalversion
681 Displays more detailed JVM version information than the -version
682 option, and then exits.
683 -Xlog:option
685 Configure or enable logging with the Java Virtual Machine (JVM)
686 unified logging framework. See Enable Logging with the JVM Uni‐
687 fied Logging Framework.
688 -Xmixed
690 Executes all bytecode by the interpreter except for hot methods,
691 which are compiled to native code. On by default. Use -Xint to
692 switch off.
693 -Xmn size
695 Sets the initial and maximum size (in bytes) of the heap for the
696 young generation (nursery) in the generational collectors. Ap‐
697 pend the letter k or K to indicate kilobytes, m or M to indicate
698 megabytes, or g or G to indicate gigabytes. The young genera‐
699 tion region of the heap is used for new objects. GC is per‐
700 formed in this region more often than in other regions. If the
701 size for the young generation is too small, then a lot of minor
702 garbage collections are performed. If the size is too large,
703 then only full garbage collections are performed, which can take
704 a long time to complete. It is recommended that you do not set
705 the size for the young generation for the G1 collector, and keep
706 the size for the young generation greater than 25% and less than
707 50% of the overall heap size for other collectors. The follow‐
708 ing examples show how to set the initial and maximum size of
709 young generation to 256 MB using various units:
710 -Xmn256m
712 -Xmn262144k
713 -Xmn268435456
714 Instead of the -Xmn option to set both the initial and maximum
716 size of the heap for the young generation, you can use -XX:New‐
717 Size to set the initial size and -XX:MaxNewSize to set the maxi‐
718 mum size.
719 -Xms size
721 Sets the minimum and the initial size (in bytes) of the heap.
722 This value must be a multiple of 1024 and greater than 1 MB.
723 Append the letter k or K to indicate kilobytes, m or M to indi‐
724 cate megabytes, or g or G to indicate gigabytes. The following
725 examples show how to set the size of allocated memory to 6 MB
726 using various units:
727 -Xms6291456
729 -Xms6144k
730 -Xms6m
731 If you do not set this option, then the initial size will be set
733 as the sum of the sizes allocated for the old generation and the
734 young generation. The initial size of the heap for the young
735 generation can be set using the -Xmn option or the -XX:NewSize
736 option.
737 Note that the -XX:InitialHeapSize option can also be used to set
739 the initial heap size. If it appears after -Xms on the command
740 line, then the initial heap size gets set to the value specified
741 with -XX:InitialHeapSize.
742 -Xmx size
744 Specifies the maximum size (in bytes) of the heap. This value
745 must be a multiple of 1024 and greater than 2 MB. Append the
746 letter k or K to indicate kilobytes, m or M to indicate
747 megabytes, or g or G to indicate gigabytes. The default value
748 is chosen at runtime based on system configuration. For server
749 deployments, -Xms and -Xmx are often set to the same value. The
750 following examples show how to set the maximum allowed size of
751 allocated memory to 80 MB using various units:
752 -Xmx83886080
754 -Xmx81920k
755 -Xmx80m
756 The -Xmx option is equivalent to -XX:MaxHeapSize.
758 -Xnoclassgc
760 Disables garbage collection (GC) of classes. This can save some
761 GC time, which shortens interruptions during the application
762 run. When you specify -Xnoclassgc at startup, the class objects
763 in the application are left untouched during GC and are always
764 be considered live. This can result in more memory being perma‐
765 nently occupied which, if not used carefully, throws an out-of-
766 memory exception.
767 -Xrs Reduces the use of operating system signals by the JVM. Shut‐
769 down hooks enable the orderly shutdown of a Java application by
770 running user cleanup code (such as closing database connections)
771 at shutdown, even if the JVM terminates abruptly.
772 • Non-Windows:
774 • The JVM catches signals to implement shutdown hooks for un‐
776 expected termination. The JVM uses SIGHUP, SIGINT, and
777 SIGTERM to initiate the running of shutdown hooks.
778 • Applications embedding the JVM frequently need to trap sig‐
780 nals such as SIGINT or SIGTERM, which can lead to interfer‐
781 ence with the JVM signal handlers. The -Xrs option is
782 available to address this issue. When -Xrs is used, the
783 signal masks for SIGINT, SIGTERM, SIGHUP, and SIGQUIT aren't
784 changed by the JVM, and signal handlers for these signals
785 aren't installed.
786 • Windows:
788 • The JVM watches for console control events to implement
790 shutdown hooks for unexpected termination. Specifically,
791 the JVM registers a console control handler that begins
792 shutdown-hook processing and returns TRUE for CTRL_C_EVENT,
793 CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUT‐
794 DOWN_EVENT.
795 • The JVM uses a similar mechanism to implement the feature of
797 dumping thread stacks for debugging purposes. The JVM uses
798 CTRL_BREAK_EVENT to perform thread dumps.
799 • If the JVM is run as a service (for example, as a servlet
801 engine for a web server), then it can receive CTRL_LO‐
802 GOFF_EVENT but shouldn't initiate shutdown because the oper‐
803 ating system doesn't actually terminate the process. To
804 avoid possible interference such as this, the -Xrs option
805 can be used. When the -Xrs option is used, the JVM doesn't
806 install a console control handler, implying that it doesn't
807 watch for or process CTRL_C_EVENT, CTRL_CLOSE_EVENT,
808 CTRL_LOGOFF_EVENT, or CTRL_SHUTDOWN_EVENT.
809 There are two consequences of specifying -Xrs:
811 • Non-Windows: SIGQUIT thread dumps aren't available.
813 • Windows: Ctrl + Break thread dumps aren't available.
815 User code is responsible for causing shutdown hooks to run, for
817 example, by calling System.exit() when the JVM is to be termi‐
818 nated.
819 -Xshare:mode
821 Sets the class data sharing (CDS) mode.
822 Possible mode arguments for this option include the following:
824 auto Use shared class data if possible (default).
826 on Require using shared class data, otherwise fail.
828 Note: The -Xshare:on option is used for testing purposes
830 only. It may cause the VM to unexpectedly exit during
831 start-up when the CDS archive cannot be used (for exam‐
832 ple, when certain VM parameters are changed, or when a
833 different JDK is used). This option should not be used
834 in production environments.
835 off Do not attempt to use shared class data.
837 -XshowSettings
839 Shows all settings and then continues.
840 -XshowSettings:category
842 Shows settings and continues. Possible category arguments for
843 this option include the following:
844 all Shows all categories of settings. This is the default
846 value.
847 locale Shows settings related to locale.
849 properties
851 Shows settings related to system properties.
852 vm Shows the settings of the JVM.
854 system Linux only: Shows host system or container configuration
856 and continues.
857 -Xss size
859 Sets the thread stack size (in bytes). Append the letter k or K
860 to indicate KB, m or M to indicate MB, or g or G to indicate GB.
861 The actual size may be rounded up to a multiple of the system
862 page size as required by the operating system. The default val‐
863 ue depends on the platform. For example:
864 • Linux/x64: 1024 KB
866 • Linux/Aarch64: 2048 KB
868 • macOS/x64: 1024 KB
870 • macOS/Aarch64: 2048 KB
872 • Windows: The default value depends on virtual memory
874 The following examples set the thread stack size to 1024 KB in
876 different units:
877 -Xss1m
879 -Xss1024k
880 -Xss1048576
881 This option is similar to -XX:ThreadStackSize.
883 --add-reads module=target-module(,target-module)*
885 Updates module to read the target-module, regardless of the mod‐
886 ule declaration. target-module can be all unnamed to read all
887 unnamed modules.
888 --add-exports module/package=target-module(,target-module)*
890 Updates module to export package to target-module, regardless of
891 module declaration. The target-module can be all unnamed to ex‐
892 port to all unnamed modules.
893 --add-opens module/package=target-module(,target-module)*
895 Updates module to open package to target-module, regardless of
896 module declaration.
897 --limit-modules module[,module...]
899 Specifies the limit of the universe of observable modules.
900 --patch-module module=file(;file)*
902 Overrides or augments a module with classes and resources in JAR
903 files or directories.
904 --source version
906 Sets the version of the source in source-file mode.
907
909 The following extra options are macOS specific.
910 -XstartOnFirstThread
912 Runs the main() method on the first (AppKit) thread.
913 -Xdock:name=application_name
915 Overrides the default application name displayed in dock.
916 -Xdock:icon=path_to_icon_file
918 Overrides the default icon displayed in dock.
919
921 These java options can be used to enable other advanced options.
922 -XX:+UnlockDiagnosticVMOptions
924 Unlocks the options intended for diagnosing the JVM. By de‐
925 fault, this option is disabled and diagnostic options aren't
926 available.
927 Command line options that are enabled with the use of this op‐
929 tion are not supported. If you encounter issues while using any
930 of these options, it is very likely that you will be required to
931 reproduce the problem without using any of these unsupported op‐
932 tions before Oracle Support can assist with an investigation.
933 It is also possible that any of these options may be removed or
934 their behavior changed without any warning.
935 -XX:+UnlockExperimentalVMOptions
937 Unlocks the options that provide experimental features in the
938 JVM. By default, this option is disabled and experimental fea‐
939 tures aren't available.
940
942 These java options control the runtime behavior of the Java HotSpot VM.
943 -XX:ActiveProcessorCount=x
945 Overrides the number of CPUs that the VM will use to calculate
946 the size of thread pools it will use for various operations such
947 as Garbage Collection and ForkJoinPool.
948 The VM normally determines the number of available processors
950 from the operating system. This flag can be useful for parti‐
951 tioning CPU resources when running multiple Java processes in
952 docker containers. This flag is honored even if UseContainer‐
953 Support is not enabled. See -XX:-UseContainerSupport for a de‐
954 scription of enabling and disabling container support.
955 -XX:AllocateHeapAt=path
957 Takes a path to the file system and uses memory mapping to allo‐
958 cate the object heap on the memory device. Using this option
959 enables the HotSpot VM to allocate the Java object heap on an
960 alternative memory device, such as an NV-DIMM, specified by the
961 user.
962 Alternative memory devices that have the same semantics as DRAM,
964 including the semantics of atomic operations, can be used in‐
965 stead of DRAM for the object heap without changing the existing
966 application code. All other memory structures (such as the code
967 heap, metaspace, and thread stacks) continue to reside in DRAM.
968 Some operating systems expose non-DRAM memory through the file
970 system. Memory-mapped files in these file systems bypass the
971 page cache and provide a direct mapping of virtual memory to the
972 physical memory on the device. The existing heap related flags
973 (such as -Xmx and -Xms) and garbage-collection related flags
974 continue to work as before.
975 -XX:-CompactStrings
977 Disables the Compact Strings feature. By default, this option
978 is enabled. When this option is enabled, Java Strings contain‐
979 ing only single-byte characters are internally represented and
980 stored as single-byte-per-character Strings using ISO-8859-1 /
981 Latin-1 encoding. This reduces, by 50%, the amount of space re‐
982 quired for Strings containing only single-byte characters. For
983 Java Strings containing at least one multibyte character: these
984 are represented and stored as 2 bytes per character using UTF-16
985 encoding. Disabling the Compact Strings feature forces the use
986 of UTF-16 encoding as the internal representation for all Java
987 Strings.
988 Cases where it may be beneficial to disable Compact Strings in‐
990 clude the following:
991 • When it's known that an application overwhelmingly will be al‐
993 locating multibyte character Strings
994 • In the unexpected event where a performance regression is ob‐
996 served in migrating from Java SE 8 to Java SE 9 and an analy‐
997 sis shows that Compact Strings introduces the regression
998 In both of these scenarios, disabling Compact Strings makes
1000 sense.
1001 -XX:ErrorFile=filename
1003 Specifies the path and file name to which error data is written
1004 when an irrecoverable error occurs. By default, this file is
1005 created in the current working directory and named hs_err_pid‐
1006 pid.log where pid is the identifier of the process that encoun‐
1007 tered the error.
1008 The following example shows how to set the default log file
1010 (note that the identifier of the process is specified as %p):
1011 -XX:ErrorFile=./hs_err_pid%p.log
1013 • Non-Windows: The following example shows how to set the error
1015 log to /var/log/java/java_error.log:
1016 -XX:ErrorFile=/var/log/java/java_error.log
1018 • Windows: The following example shows how to set the error log
1020 file to C:/log/java/java_error.log:
1021 -XX:ErrorFile=C:/log/java/java_error.log
1023 If the file exists, and is writeable, then it will be overwrit‐
1025 ten. Otherwise, if the file can't be created in the specified
1026 directory (due to insufficient space, permission problem, or an‐
1027 other issue), then the file is created in the temporary directo‐
1028 ry for the operating system:
1029 • Non-Windows: The temporary directory is /tmp.
1031 • Windows: The temporary directory is specified by the value of
1033 the TMP environment variable; if that environment variable
1034 isn't defined, then the value of the TEMP environment variable
1035 is used.
1036 -XX:+ExtensiveErrorReports
1038 Enables the reporting of more extensive error information in the
1039 ErrorFile. This option can be turned on in environments where
1040 maximal information is desired - even if the resulting logs may
1041 be quite large and/or contain information that might be consid‐
1042 ered sensitive. The information can vary from release to re‐
1043 lease, and across different platforms. By default this option
1044 is disabled.
1045 -XX:FlightRecorderOptions=parameter=value (or) -XX:FlightRecorderOp‐
1047 tions:parameter=value
1048 Sets the parameters that control the behavior of JFR. Multiple
1049 parameters can be specified by separating them with a comma.
1050 The following list contains the available JFR parameter=value
1052 entries:
1053 globalbuffersize=size
1055 Specifies the total amount of primary memory used for da‐
1056 ta retention. The default value is based on the value
1057 specified for memorysize. Change the memorysize parame‐
1058 ter to alter the size of global buffers.
1059 maxchunksize=size
1061 Specifies the maximum size (in bytes) of the data chunks
1062 in a recording. Append m or M to specify the size in
1063 megabytes (MB), or g or G to specify the size in giga‐
1064 bytes (GB). By default, the maximum size of data chunks
1065 is set to 12 MB. The minimum allowed is 1 MB.
1066 memorysize=size
1068 Determines how much buffer memory should be used, and
1069 sets the globalbuffersize and numglobalbuffers parameters
1070 based on the size specified. Append m or M to specify
1071 the size in megabytes (MB), or g or G to specify the size
1072 in gigabytes (GB). By default, the memory size is set to
1073 10 MB.
1074 numglobalbuffers
1076 Specifies the number of global buffers used. The default
1077 value is based on the memory size specified. Change the
1078 memorysize parameter to alter the number of global buf‐
1079 fers.
1080 old-object-queue-size=number-of-objects
1082 Maximum number of old objects to track. By default, the
1083 number of objects is set to 256.
1084 preserve-repository={true|false}
1086 Specifies whether files stored in the disk repository
1087 should be kept after the JVM has exited. If false, files
1088 are deleted. By default, this parameter is disabled.
1089 repository=path
1091 Specifies the repository (a directory) for temporary disk
1092 storage. By default, the system's temporary directory is
1093 used.
1094 retransform={true|false}
1096 Specifies whether event classes should be retransformed
1097 using JVMTI. If false, instrumentation is added when
1098 event classes are loaded. By default, this parameter is
1099 enabled.
1100 stackdepth=depth
1102 Stack depth for stack traces. By default, the depth is
1103 set to 64 method calls. The maximum is 2048. Values
1104 greater than 64 could create significant overhead and re‐
1105 duce performance.
1106 threadbuffersize=size
1108 Specifies the per-thread local buffer size (in bytes).
1109 By default, the local buffer size is set to 8 kilobytes,
1110 with a minimum value of 4 kilobytes. Overriding this pa‐
1111 rameter could reduce performance and is not recommended.
1112 -XX:LargePageSizeInBytes=size
1114 Sets the maximum large page size (in bytes) used by the JVM.
1115 The size argument must be a valid page size supported by the en‐
1116 vironment to have any effect. Append the letter k or K to indi‐
1117 cate kilobytes, m or M to indicate megabytes, or g or G to indi‐
1118 cate gigabytes. By default, the size is set to 0, meaning that
1119 the JVM will use the default large page size for the environment
1120 as the maximum size for large pages. See Large Pages.
1121 The following example describes how to set the large page size
1123 to 1 gigabyte (GB):
1124 -XX:LargePageSizeInBytes=1g
1126 -XX:MaxDirectMemorySize=size
1128 Sets the maximum total size (in bytes) of the java.nio package,
1129 direct-buffer allocations. Append the letter k or K to indicate
1130 kilobytes, m or M to indicate megabytes, or g or G to indicate
1131 gigabytes. If not set, the flag is ignored and the JVM chooses
1132 the size for NIO direct-buffer allocations automatically.
1133 The following examples illustrate how to set the NIO size to
1135 1024 KB in different units:
1136 -XX:MaxDirectMemorySize=1m
1138 -XX:MaxDirectMemorySize=1024k
1139 -XX:MaxDirectMemorySize=1048576
1140 -XX:-MaxFDLimit
1142 Disables the attempt to set the soft limit for the number of
1143 open file descriptors to the hard limit. By default, this op‐
1144 tion is enabled on all platforms, but is ignored on Windows.
1145 The only time that you may need to disable this is on macOS,
1146 where its use imposes a maximum of 10240, which is lower than
1147 the actual system maximum.
1148 -XX:NativeMemoryTracking=mode
1150 Specifies the mode for tracking JVM native memory usage. Possi‐
1151 ble mode arguments for this option include the following:
1152 off Instructs not to track JVM native memory usage. This is
1154 the default behavior if you don't specify the -XX:Native‐
1155 MemoryTracking option.
1156 summary
1158 Tracks memory usage only by JVM subsystems, such as Java
1159 heap, class, code, and thread.
1160 detail In addition to tracking memory usage by JVM subsystems,
1162 track memory usage by individual CallSite, individual
1163 virtual memory region and its committed regions.
1164 -XX:+NeverActAsServerClassMachine
1166 Enable the "Client VM emulation" mode which only uses the C1 JIT
1167 compiler, a 32Mb CodeCache and the Serial GC. The maximum
1168 amount of memory that the JVM may use (controlled by the
1169 -XX:MaxRAM=n flag) is set to 1GB by default. The string "emu‐
1170 lated-client" is added to the JVM version string.
1171 By default the flag is set to true only on Windows in 32-bit
1173 mode and false in all other cases.
1174 The "Client VM emulation" mode will not be enabled if any of the
1176 following flags are used on the command line:
1177 -XX:{+|-}TieredCompilation
1179 -XX:CompilationMode=mode
1180 -XX:TieredStopAtLevel=n
1181 -XX:{+|-}EnableJVMCI
1182 -XX:{+|-}UseJVMCICompiler
1183 -XX:ObjectAlignmentInBytes=alignment
1185 Sets the memory alignment of Java objects (in bytes). By de‐
1186 fault, the value is set to 8 bytes. The specified value should
1187 be a power of 2, and must be within the range of 8 and 256 (in‐
1188 clusive). This option makes it possible to use compressed
1189 pointers with large Java heap sizes.
1190 The heap size limit in bytes is calculated as:
1192 4GB * ObjectAlignmentInBytes
1194 Note: As the alignment value increases, the unused space
1196 between objects also increases. As a result, you may not
1197 realize any benefits from using compressed pointers with
1198 large Java heap sizes.
1199 -XX:OnError=string
1201 Sets a custom command or a series of semicolon-separated com‐
1202 mands to run when an irrecoverable error occurs. If the string
1203 contains spaces, then it must be enclosed in quotation marks.
1204 • Non-Windows: The following example shows how the -XX:OnError
1206 option can be used to run the gcore command to create a core
1207 image, and start the gdb debugger to attach to the process in
1208 case of an irrecoverable error (the %p designates the current
1209 process identifier):
1210 -XX:OnError="gcore %p;gdb -p %p"
1212 • Windows: The following example shows how the -XX:OnError op‐
1214 tion can be used to run the userdump.exe utility to obtain a
1215 crash dump in case of an irrecoverable error (the %p desig‐
1216 nates the current process identifier). This example assumes
1217 that the path to the userdump.exe utility is specified in the
1218 PATH environment variable:
1219 -XX:OnError="userdump.exe %p"
1221 -XX:OnOutOfMemoryError=string
1223 Sets a custom command or a series of semicolon-separated com‐
1224 mands to run when an OutOfMemoryError exception is first thrown.
1225 If the string contains spaces, then it must be enclosed in quo‐
1226 tation marks. For an example of a command string, see the de‐
1227 scription of the -XX:OnError option.
1228 -XX:+PrintCommandLineFlags
1230 Enables printing of ergonomically selected JVM flags that ap‐
1231 peared on the command line. It can be useful to know the ergo‐
1232 nomic values set by the JVM, such as the heap space size and the
1233 selected garbage collector. By default, this option is disabled
1234 and flags aren't printed.
1235 -XX:+PreserveFramePointer
1237 Selects between using the RBP register as a general purpose reg‐
1238 ister (-XX:-PreserveFramePointer) and using the RBP register to
1239 hold the frame pointer of the currently executing method
1240 (-XX:+PreserveFramePointer . If the frame pointer is available,
1241 then external profiling tools (for example, Linux perf) can con‐
1242 struct more accurate stack traces.
1243 -XX:+PrintNMTStatistics
1245 Enables printing of collected native memory tracking data at JVM
1246 exit when native memory tracking is enabled (see -XX:NativeMemo‐
1247 ryTracking). By default, this option is disabled and native
1248 memory tracking data isn't printed.
1249 -XX:SharedArchiveFile=path
1251 Specifies the path and name of the class data sharing (CDS) ar‐
1252 chive file
1253 See Application Class Data Sharing.
1255 -XX:SharedArchiveConfigFile=shared_config_file
1257 Specifies additional shared data added to the archive file.
1258 -XX:SharedClassListFile=file_name
1260 Specifies the text file that contains the names of the classes
1261 to store in the class data sharing (CDS) archive. This file
1262 contains the full name of one class per line, except slashes (/)
1263 replace dots (.). For example, to specify the classes ja‐
1264 va.lang.Object and hello.Main, create a text file that contains
1265 the following two lines:
1266 java/lang/Object
1268 hello/Main
1269 The classes that you specify in this text file should include
1271 the classes that are commonly used by the application. They may
1272 include any classes from the application, extension, or boot‐
1273 strap class paths.
1274 See Application Class Data Sharing.
1276 -XX:+ShowCodeDetailsInExceptionMessages
1278 Enables printing of improved NullPointerException messages.
1279 When an application throws a NullPointerException, the option
1280 enables the JVM to analyze the program's bytecode instructions
1281 to determine precisely which reference is null, and describes
1282 the source with a null-detail message. The null-detail message
1283 is calculated and returned by NullPointerException.getMessage(),
1284 and will be printed as the exception message along with the
1285 method, filename, and line number. By default, this option is
1286 enabled.
1287 -XX:+ShowMessageBoxOnError
1289 Enables the display of a dialog box when the JVM experiences an
1290 irrecoverable error. This prevents the JVM from exiting and
1291 keeps the process active so that you can attach a debugger to it
1292 to investigate the cause of the error. By default, this option
1293 is disabled.
1294 -XX:StartFlightRecording=parameter=value
1296 Starts a JFR recording for the Java application. This option is
1297 equivalent to the JFR.start diagnostic command that starts a
1298 recording during runtime. You can set the following parame‐
1299 ter=value entries when starting a JFR recording:
1300 delay=time
1302 Specifies the delay between the Java application launch
1303 time and the start of the recording. Append s to specify
1304 the time in seconds, m for minutes, h for hours, or d for
1305 days (for example, specifying 10m means 10 minutes). By
1306 default, there's no delay, and this parameter is set to
1307 0.
1308 disk={true|false}
1310 Specifies whether to write data to disk while recording.
1311 By default, this parameter is enabled.
1312 dumponexit={true|false}
1314 Specifies if the running recording is dumped when the JVM
1315 shuts down. If enabled and a filename is not entered,
1316 the recording is written to a file in the directory where
1317 the process was started. The file name is a system-gen‐
1318 erated name that contains the process ID, recording ID,
1319 and current timestamp, similar to hotspot-
1320 pid-47496-id-1-2018_01_25_19_10_41.jfr. By default, this
1321 parameter is disabled.
1322 duration=time
1324 Specifies the duration of the recording. Append s to
1325 specify the time in seconds, m for minutes, h for hours,
1326 or d for days (for example, specifying 5h means 5 hours).
1327 By default, the duration isn't limited, and this parame‐
1328 ter is set to 0.
1329 filename=path
1331 Specifies the path and name of the file to which the
1332 recording is written when the recording is stopped, for
1333 example:
1334 • recording.jfr
1336 • /home/user/recordings/recording.jfr
1338 • c:\recordings\recording.jfr
1340 If %p and/or %t is specified in the filename, it expands
1342 to the JVM's PID and the current timestamp, respectively.
1343 name=identifier
1345 Takes both the name and the identifier of a recording.
1346 maxage=time
1348 Specifies the maximum age of disk data to keep for the
1349 recording. This parameter is valid only when the disk
1350 parameter is set to true. Append s to specify the time
1351 in seconds, m for minutes, h for hours, or d for days
1352 (for example, specifying 30s means 30 seconds). By de‐
1353 fault, the maximum age isn't limited, and this parameter
1354 is set to 0s.
1355 maxsize=size
1357 Specifies the maximum size (in bytes) of disk data to
1358 keep for the recording. This parameter is valid only
1359 when the disk parameter is set to true. The value must
1360 not be less than the value for the maxchunksize parameter
1361 set with -XX:FlightRecorderOptions. Append m or M to
1362 specify the size in megabytes, or g or G to specify the
1363 size in gigabytes. By default, the maximum size of disk
1364 data isn't limited, and this parameter is set to 0.
1365 path-to-gc-roots={true|false}
1367 Specifies whether to collect the path to garbage collec‐
1368 tion (GC) roots at the end of a recording. By default,
1369 this parameter is disabled.
1370 The path to GC roots is useful for finding memory leaks,
1372 but collecting it is time-consuming. Enable this option
1373 only when you start a recording for an application that
1374 you suspect has a memory leak. If the settings parameter
1375 is set to profile, the stack trace from where the poten‐
1376 tial leaking object was allocated is included in the in‐
1377 formation collected.
1378 settings=path
1380 Specifies the path and name of the event settings file
1381 (of type JFC). By default, the default.jfc file is used,
1382 which is located in JAVA_HOME/lib/jfr. This default set‐
1383 tings file collects a predefined set of information with
1384 low overhead, so it has minimal impact on performance and
1385 can be used with recordings that run continuously.
1386 A second settings file is also provided, profile.jfc,
1388 which provides more data than the default configuration,
1389 but can have more overhead and impact performance. Use
1390 this configuration for short periods of time when more
1391 information is needed.
1392 You can specify values for multiple parameters by separating
1394 them with a comma. Event settings and .jfc options can be spec‐
1395 ified using the following syntax:
1396 option=value
1398 Specifies the option value to modify. To list available
1399 options, use the JAVA_HOME/bin/jfr tool.
1400 event-setting=value
1402 Specifies the event setting value to modify. Use the
1403 form: <event-name>#<setting-name>=<value>. To add a new
1404 event setting, prefix the event name with '+'.
1405 You can specify values for multiple event settings and .jfc op‐
1407 tions by separating them with a comma. In case of a conflict
1408 between a parameter and a .jfc option, the parameter will take
1409 precedence. The whitespace delimiter can be omitted for times‐
1410 pan values, i.e. 20ms. For more information about the settings
1411 syntax, see Javadoc of the jdk.jfr package.
1412 -XX:ThreadStackSize=size
1414 Sets the Java thread stack size (in kilobytes). Use of a scal‐
1415 ing suffix, such as k, results in the scaling of the kilobytes
1416 value so that -XX:ThreadStackSize=1k sets the Java thread stack
1417 size to 1024*1024 bytes or 1 megabyte. The default value de‐
1418 pends on the platform. For example:
1419 • Linux/x64: 1024 KB
1421 • Linux/Aarch64: 2048 KB
1423 • macOS/x64: 1024 KB
1425 • macOS/Aarch64: 2048 KB
1427 • Windows: The default value depends on virtual memory
1429 The following examples show how to set the thread stack size to
1431 1 megabyte in different units:
1432 -XX:ThreadStackSize=1k
1434 -XX:ThreadStackSize=1024
1435 This option is similar to -Xss.
1437 -XX:-UseCompressedOops
1439 Disables the use of compressed pointers. By default, this op‐
1440 tion is enabled, and compressed pointers are used. This will
1441 automatically limit the maximum ergonomically determined Java
1442 heap size to the maximum amount of memory that can be covered by
1443 compressed pointers. By default this range is 32 GB.
1444 With compressed oops enabled, object references are represented
1446 as 32-bit offsets instead of 64-bit pointers, which typically
1447 increases performance when running the application with Java
1448 heap sizes smaller than the compressed oops pointer range. This
1449 option works only for 64-bit JVMs.
1450 It's possible to use compressed pointers with Java heap sizes
1452 greater than 32 GB. See the -XX:ObjectAlignmentInBytes option.
1453 -XX:-UseContainerSupport
1455 Linux only: The VM now provides automatic container detection
1456 support, which allows the VM to determine the amount of memory
1457 and number of processors that are available to a Java process
1458 running in docker containers. It uses this information to allo‐
1459 cate system resources. The default for this flag is true, and
1460 container support is enabled by default. It can be disabled
1461 with -XX:-UseContainerSupport.
1462 Unified Logging is available to help to diagnose issues related
1464 to this support.
1465 Use -Xlog:os+container=trace for maximum logging of container
1467 information. See Enable Logging with the JVM Unified Logging
1468 Framework for a description of using Unified Logging.
1469 -XX:+UseHugeTLBFS
1471 Linux only: This option is the equivalent of specifying
1472 -XX:+UseLargePages. This option is disabled by default. This
1473 option pre-allocates all large pages up-front, when memory is
1474 reserved; consequently the JVM can't dynamically grow or shrink
1475 large pages memory areas; see -XX:UseTransparentHugePages if you
1476 want this behavior.
1477 See Large Pages.
1479 -XX:+UseLargePages
1481 Enables the use of large page memory. By default, this option
1482 is disabled and large page memory isn't used.
1483 See Large Pages.
1485 -XX:+UseTransparentHugePages
1487 Linux only: Enables the use of large pages that can dynamically
1488 grow or shrink. This option is disabled by default. You may
1489 encounter performance problems with transparent huge pages as
1490 the OS moves other pages around to create huge pages; this op‐
1491 tion is made available for experimentation.
1492 -XX:+AllowUserSignalHandlers
1494 Non-Windows: Enables installation of signal handlers by the ap‐
1495 plication. By default, this option is disabled and the applica‐
1496 tion isn't allowed to install signal handlers.
1497 -XX:VMOptionsFile=filename
1499 Allows user to specify VM options in a file, for example, java
1500 -XX:VMOptionsFile=/var/my_vm_options HelloWorld.
1501 -XX:UseBranchProtection=mode
1503 Linux AArch64 only: Specifies the branch protection mode. All
1504 options other than none require the VM to have been built with
1505 branch protection enabled. In addition, for full protection,
1506 any native libraries provided by applications should be compiled
1507 with the same level of protection.
1508 Possible mode arguments for this option include the following:
1510 none Do not use branch protection. This is the default value.
1512 standard
1514 Enables all branch protection modes available on the cur‐
1515 rent platform.
1516 pac-ret
1518 Enables protection against ROP based attacks. (AArch64
1519 8.3+ only)
1520
1522 These java options control the dynamic just-in-time (JIT) compilation
1523 performed by the Java HotSpot VM.
1524 -XX:AllocateInstancePrefetchLines=lines
1526 Sets the number of lines to prefetch ahead of the instance allo‐
1527 cation pointer. By default, the number of lines to prefetch is
1528 set to 1:
1529 -XX:AllocateInstancePrefetchLines=1
1531 -XX:AllocatePrefetchDistance=size
1533 Sets the size (in bytes) of the prefetch distance for object al‐
1534 location. Memory about to be written with the value of new ob‐
1535 jects is prefetched up to this distance starting from the ad‐
1536 dress of the last allocated object. Each Java thread has its
1537 own allocation point.
1538 Negative values denote that prefetch distance is chosen based on
1540 the platform. Positive values are bytes to prefetch. Append
1541 the letter k or K to indicate kilobytes, m or M to indicate
1542 megabytes, or g or G to indicate gigabytes. The default value
1543 is set to -1.
1544 The following example shows how to set the prefetch distance to
1546 1024 bytes:
1547 -XX:AllocatePrefetchDistance=1024
1549 -XX:AllocatePrefetchInstr=instruction
1551 Sets the prefetch instruction to prefetch ahead of the alloca‐
1552 tion pointer. Possible values are from 0 to 3. The actual in‐
1553 structions behind the values depend on the platform. By de‐
1554 fault, the prefetch instruction is set to 0:
1555 -XX:AllocatePrefetchInstr=0
1557 -XX:AllocatePrefetchLines=lines
1559 Sets the number of cache lines to load after the last object al‐
1560 location by using the prefetch instructions generated in com‐
1561 piled code. The default value is 1 if the last allocated object
1562 was an instance, and 3 if it was an array.
1563 The following example shows how to set the number of loaded
1565 cache lines to 5:
1566 -XX:AllocatePrefetchLines=5
1568 -XX:AllocatePrefetchStepSize=size
1570 Sets the step size (in bytes) for sequential prefetch instruc‐
1571 tions. Append the letter k or K to indicate kilobytes, m or M
1572 to indicate megabytes, g or G to indicate gigabytes. By de‐
1573 fault, the step size is set to 16 bytes:
1574 -XX:AllocatePrefetchStepSize=16
1576 -XX:AllocatePrefetchStyle=style
1578 Sets the generated code style for prefetch instructions. The
1579 style argument is an integer from 0 to 3:
1580 0 Don't generate prefetch instructions.
1582 1 Execute prefetch instructions after each allocation.
1584 This is the default setting.
1585 2 Use the thread-local allocation block (TLAB) watermark
1587 pointer to determine when prefetch instructions are exe‐
1588 cuted.
1589 3 Generate one prefetch instruction per cache line.
1591 -XX:+BackgroundCompilation
1593 Enables background compilation. This option is enabled by de‐
1594 fault. To disable background compilation, specify -XX:-Back‐
1595 groundCompilation (this is equivalent to specifying -Xbatch).
1596 -XX:CICompilerCount=threads
1598 Sets the number of compiler threads to use for compilation. By
1599 default, the number of compiler threads is selected automatical‐
1600 ly depending on the number of CPUs and memory available for com‐
1601 piled code. The following example shows how to set the number
1602 of threads to 2:
1603 -XX:CICompilerCount=2
1605 -XX:+UseDynamicNumberOfCompilerThreads
1607 Dynamically create compiler thread up to the limit specified by
1608 -XX:CICompilerCount. This option is enabled by default.
1609 -XX:CompileCommand=command,method[,option]
1611 Specifies a command to perform on a method. For example, to ex‐
1612 clude the indexOf() method of the String class from being com‐
1613 piled, use the following:
1614 -XX:CompileCommand=exclude,java/lang/String.indexOf
1616 Note that the full class name is specified, including all pack‐
1618 ages and subpackages separated by a slash (/). For easier cut-
1619 and-paste operations, it's also possible to use the method name
1620 format produced by the -XX:+PrintCompilation and -XX:+LogCompi‐
1621 lation options:
1622 -XX:CompileCommand=exclude,java.lang.String::indexOf
1624 If the method is specified without the signature, then the com‐
1626 mand is applied to all methods with the specified name. Howev‐
1627 er, you can also specify the signature of the method in the
1628 class file format. In this case, you should enclose the argu‐
1629 ments in quotation marks, because otherwise the shell treats the
1630 semicolon as a command end. For example, if you want to exclude
1631 only the indexOf(String) method of the String class from being
1632 compiled, use the following:
1633 -XX:CompileCommand="exclude,java/lang/String.index‐
1635 Of,(Ljava/lang/String;)I"
1636 You can also use the asterisk (*) as a wildcard for class and
1638 method names. For example, to exclude all indexOf() methods in
1639 all classes from being compiled, use the following:
1640 -XX:CompileCommand=exclude,*.indexOf
1642 The commas and periods are aliases for spaces, making it easier
1644 to pass compiler commands through a shell. You can pass argu‐
1645 ments to -XX:CompileCommand using spaces as separators by en‐
1646 closing the argument in quotation marks:
1647 -XX:CompileCommand="exclude java/lang/String indexOf"
1649 Note that after parsing the commands passed on the command line
1651 using the -XX:CompileCommand options, the JIT compiler then
1652 reads commands from the .hotspot_compiler file. You can add
1653 commands to this file or specify a different file using the
1654 -XX:CompileCommandFile option.
1655 To add several commands, either specify the -XX:CompileCommand
1657 option multiple times, or separate each argument with the new
1658 line separator (\n). The following commands are available:
1659 break Sets a breakpoint when debugging the JVM to stop at the
1661 beginning of compilation of the specified method.
1662 compileonly
1664 Excludes all methods from compilation except for the
1665 specified method. As an alternative, you can use the
1666 -XX:CompileOnly option, which lets you specify several
1667 methods.
1668 dontinline
1670 Prevents inlining of the specified method.
1671 exclude
1673 Excludes the specified method from compilation.
1674 help Prints a help message for the -XX:CompileCommand option.
1676 inline Attempts to inline the specified method.
1678 log Excludes compilation logging (with the -XX:+LogCompila‐
1680 tion option) for all methods except for the specified
1681 method. By default, logging is performed for all com‐
1682 piled methods.
1683 option Passes a JIT compilation option to the specified method
1685 in place of the last argument (option). The compilation
1686 option is set at the end, after the method name. For ex‐
1687 ample, to enable the BlockLayoutByFrequency option for
1688 the append() method of the StringBuffer class, use the
1689 following:
1690 -XX:CompileCommand=option,java/lang/String‐
1692 Buffer.append,BlockLayoutByFrequency
1693 You can specify multiple compilation options, separated
1695 by commas or spaces.
1696 print Prints generated assembler code after compilation of the
1698 specified method.
1699 quiet Instructs not to print the compile commands. By default,
1701 the commands that you specify with the -XX:CompileCommand
1702 option are printed; for example, if you exclude from com‐
1703 pilation the indexOf() method of the String class, then
1704 the following is printed to standard output:
1705 CompilerOracle: exclude java/lang/String.indexOf
1707 You can suppress this by specifying the -XX:CompileCom‐
1709 mand=quiet option before other -XX:CompileCommand op‐
1710 tions.
1711 -XX:CompileCommandFile=filename
1713 Sets the file from which JIT compiler commands are read. By de‐
1714 fault, the .hotspot_compiler file is used to store commands per‐
1715 formed by the JIT compiler.
1716 Each line in the command file represents a command, a class
1718 name, and a method name for which the command is used. For ex‐
1719 ample, this line prints assembly code for the toString() method
1720 of the String class:
1721 print java/lang/String toString
1723 If you're using commands for the JIT compiler to perform on
1725 methods, then see the -XX:CompileCommand option.
1726 -XX:CompilerDirectivesFile=file
1728 Adds directives from a file to the directives stack when a pro‐
1729 gram starts. See Compiler Control [https://docs.ora‐
1730 cle.com/en/java/javase/12/vm/compiler-con‐
1731 trol1.html#GUID-94AD8194-786A-4F19-BFFF-278F8E237F3A].
1732 The -XX:CompilerDirectivesFile option has to be used together
1734 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1735 nostic JVM options.
1736 -XX:+CompilerDirectivesPrint
1738 Prints the directives stack when the program starts or when a
1739 new directive is added.
1740 The -XX:+CompilerDirectivesPrint option has to be used together
1742 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1743 nostic JVM options.
1744 -XX:CompileOnly=methods
1746 Sets the list of methods (separated by commas) to which compila‐
1747 tion should be restricted. Only the specified methods are com‐
1748 piled. Specify each method with the full class name (including
1749 the packages and subpackages). For example, to compile only the
1750 length() method of the String class and the size() method of the
1751 List class, use the following:
1752 -XX:CompileOnly=java/lang/String.length,ja‐
1754 va/util/List.size
1755 Note that the full class name is specified, including all pack‐
1757 ages and subpackages separated by a slash (/). For easier cut
1758 and paste operations, it's also possible to use the method name
1759 format produced by the -XX:+PrintCompilation and -XX:+LogCompi‐
1760 lation options:
1761 -XX:CompileOnly=java.lang.String::length,ja‐
1763 va.util.List::size
1764 Although wildcards aren't supported, you can specify only the
1766 class or package name to compile all methods in that class or
1767 package, as well as specify just the method to compile methods
1768 with this name in any class:
1769 -XX:CompileOnly=java/lang/String
1771 -XX:CompileOnly=java/lang
1772 -XX:CompileOnly=.length
1773 -XX:CompileThresholdScaling=scale
1775 Provides unified control of first compilation. This option con‐
1776 trols when methods are first compiled for both the tiered and
1777 the nontiered modes of operation. The CompileThresholdScaling
1778 option has a floating point value between 0 and +Inf and scales
1779 the thresholds corresponding to the current mode of operation
1780 (both tiered and nontiered). Setting CompileThresholdScaling to
1781 a value less than 1.0 results in earlier compilation while val‐
1782 ues greater than 1.0 delay compilation. Setting CompileThresh‐
1783 oldScaling to 0 is equivalent to disabling compilation.
1784 -XX:+DoEscapeAnalysis
1786 Enables the use of escape analysis. This option is enabled by
1787 default. To disable the use of escape analysis, specify
1788 -XX:-DoEscapeAnalysis.
1789 -XX:InitialCodeCacheSize=size
1791 Sets the initial code cache size (in bytes). Append the letter
1792 k or K to indicate kilobytes, m or M to indicate megabytes, or g
1793 or G to indicate gigabytes. The default value depends on the
1794 platform. The initial code cache size shouldn't be less than
1795 the system's minimal memory page size. The following example
1796 shows how to set the initial code cache size to 32 KB:
1797 -XX:InitialCodeCacheSize=32k
1799 -XX:+Inline
1801 Enables method inlining. This option is enabled by default to
1802 increase performance. To disable method inlining, specify
1803 -XX:-Inline.
1804 -XX:InlineSmallCode=size
1806 Sets the maximum code size (in bytes) for already compiled meth‐
1807 ods that may be inlined. This flag only applies to the C2 com‐
1808 piler. Append the letter k or K to indicate kilobytes, m or M
1809 to indicate megabytes, or g or G to indicate gigabytes. The de‐
1810 fault value depends on the platform and on whether tiered compi‐
1811 lation is enabled. In the following example it is set to 1000
1812 bytes:
1813 -XX:InlineSmallCode=1000
1815 -XX:+LogCompilation
1817 Enables logging of compilation activity to a file named
1818 hotspot.log in the current working directory. You can specify a
1819 different log file path and name using the -XX:LogFile option.
1820 By default, this option is disabled and compilation activity
1822 isn't logged. The -XX:+LogCompilation option has to be used to‐
1823 gether with the -XX:UnlockDiagnosticVMOptions option that un‐
1824 locks diagnostic JVM options.
1825 You can enable verbose diagnostic output with a message printed
1827 to the console every time a method is compiled by using the
1828 -XX:+PrintCompilation option.
1829 -XX:FreqInlineSize=size
1831 Sets the maximum bytecode size (in bytes) of a hot method to be
1832 inlined. This flag only applies to the C2 compiler. Append the
1833 letter k or K to indicate kilobytes, m or M to indicate
1834 megabytes, or g or G to indicate gigabytes. The default value
1835 depends on the platform. In the following example it is set to
1836 325 bytes:
1837 -XX:FreqInlineSize=325
1839 -XX:MaxInlineSize=size
1841 Sets the maximum bytecode size (in bytes) of a cold method to be
1842 inlined. This flag only applies to the C2 compiler. Append the
1843 letter k or K to indicate kilobytes, m or M to indicate
1844 megabytes, or g or G to indicate gigabytes. By default, the
1845 maximum bytecode size is set to 35 bytes:
1846 -XX:MaxInlineSize=35
1848 -XX:C1MaxInlineSize=size
1850 Sets the maximum bytecode size (in bytes) of a cold method to be
1851 inlined. This flag only applies to the C1 compiler. Append the
1852 letter k or K to indicate kilobytes, m or M to indicate
1853 megabytes, or g or G to indicate gigabytes. By default, the
1854 maximum bytecode size is set to 35 bytes:
1855 -XX:MaxInlineSize=35
1857 -XX:MaxTrivialSize=size
1859 Sets the maximum bytecode size (in bytes) of a trivial method to
1860 be inlined. This flag only applies to the C2 compiler. Append
1861 the letter k or K to indicate kilobytes, m or M to indicate
1862 megabytes, or g or G to indicate gigabytes. By default, the
1863 maximum bytecode size of a trivial method is set to 6 bytes:
1864 -XX:MaxTrivialSize=6
1866 -XX:C1MaxTrivialSize=size
1868 Sets the maximum bytecode size (in bytes) of a trivial method to
1869 be inlined. This flag only applies to the C1 compiler. Append
1870 the letter k or K to indicate kilobytes, m or M to indicate
1871 megabytes, or g or G to indicate gigabytes. By default, the
1872 maximum bytecode size of a trivial method is set to 6 bytes:
1873 -XX:MaxTrivialSize=6
1875 -XX:MaxNodeLimit=nodes
1877 Sets the maximum number of nodes to be used during single method
1878 compilation. By default the value depends on the features en‐
1879 abled. In the following example the maximum number of nodes is
1880 set to 100,000:
1881 -XX:MaxNodeLimit=100000
1883 -XX:NonNMethodCodeHeapSize=size
1885 Sets the size in bytes of the code segment containing nonmethod
1886 code.
1887 A nonmethod code segment containing nonmethod code, such as com‐
1889 piler buffers and the bytecode interpreter. This code type
1890 stays in the code cache forever. This flag is used only if
1891 -XX:SegmentedCodeCache is enabled.
1892 -XX:NonProfiledCodeHeapSize=size
1894 Sets the size in bytes of the code segment containing nonpro‐
1895 filed methods. This flag is used only if -XX:SegmentedCodeCache
1896 is enabled.
1897 -XX:+OptimizeStringConcat
1899 Enables the optimization of String concatenation operations.
1900 This option is enabled by default. To disable the optimization
1901 of String concatenation operations, specify -XX:-OptimizeString‐
1902 Concat.
1903 -XX:+PrintAssembly
1905 Enables printing of assembly code for bytecoded and native meth‐
1906 ods by using the external hsdis-<arch>.so or .dll library. For
1907 64-bit VM on Windows, it's hsdis-amd64.dll. This lets you to
1908 see the generated code, which may help you to diagnose perfor‐
1909 mance issues.
1910 By default, this option is disabled and assembly code isn't
1912 printed. The -XX:+PrintAssembly option has to be used together
1913 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1914 nostic JVM options.
1915 -XX:ProfiledCodeHeapSize=size
1917 Sets the size in bytes of the code segment containing profiled
1918 methods. This flag is used only if -XX:SegmentedCodeCache is
1919 enabled.
1920 -XX:+PrintCompilation
1922 Enables verbose diagnostic output from the JVM by printing a
1923 message to the console every time a method is compiled. This
1924 lets you to see which methods actually get compiled. By de‐
1925 fault, this option is disabled and diagnostic output isn't
1926 printed.
1927 You can also log compilation activity to a file by using the
1929 -XX:+LogCompilation option.
1930 -XX:+PrintInlining
1932 Enables printing of inlining decisions. This let's you see
1933 which methods are getting inlined.
1934 By default, this option is disabled and inlining information
1936 isn't printed. The -XX:+PrintInlining option has to be used to‐
1937 gether with the -XX:+UnlockDiagnosticVMOptions option that un‐
1938 locks diagnostic JVM options.
1939 -XX:ReservedCodeCacheSize=size
1941 Sets the maximum code cache size (in bytes) for JIT-compiled
1942 code. Append the letter k or K to indicate kilobytes, m or M to
1943 indicate megabytes, or g or G to indicate gigabytes. The de‐
1944 fault maximum code cache size is 240 MB; if you disable tiered
1945 compilation with the option -XX:-TieredCompilation, then the de‐
1946 fault size is 48 MB. This option has a limit of 2 GB; other‐
1947 wise, an error is generated. The maximum code cache size
1948 shouldn't be less than the initial code cache size; see the op‐
1949 tion -XX:InitialCodeCacheSize.
1950 -XX:RTMAbortRatio=abort_ratio
1952 Specifies the RTM abort ratio is specified as a percentage (%)
1953 of all executed RTM transactions. If a number of aborted trans‐
1954 actions becomes greater than this ratio, then the compiled code
1955 is deoptimized. This ratio is used when the -XX:+UseRTMDeopt
1956 option is enabled. The default value of this option is 50.
1957 This means that the compiled code is deoptimized if 50% of all
1958 transactions are aborted.
1959 -XX:RTMRetryCount=number_of_retries
1961 Specifies the number of times that the RTM locking code is re‐
1962 tried, when it is aborted or busy, before falling back to the
1963 normal locking mechanism. The default value for this option is
1964 5. The -XX:UseRTMLocking option must be enabled.
1965 -XX:+SegmentedCodeCache
1967 Enables segmentation of the code cache, without which the code
1968 cache consists of one large segment. With -XX:+SegmentedCode‐
1969 Cache, separate segments will be used for non-method, profiled
1970 method, and non-profiled method code. The segments are not re‐
1971 sized at runtime. The advantages are better control of the mem‐
1972 ory footprint, reduced code fragmentation, and better CPU iTLB
1973 (instruction translation lookaside buffer) and instruction cache
1974 behavior due to improved locality.
1975 The feature is enabled by default if tiered compilation is en‐
1977 abled (-XX:+TieredCompilation ) and the reserved code cache size
1978 (-XX:ReservedCodeCacheSize) is at least 240 MB.
1979 -XX:StartAggressiveSweepingAt=percent
1981 Forces stack scanning of active methods to aggressively remove
1982 unused code when only the given percentage of the code cache is
1983 free. The default value is 10%.
1984 -XX:-TieredCompilation
1986 Disables the use of tiered compilation. By default, this option
1987 is enabled.
1988 -XX:UseSSE=version
1990 Enables the use of SSE instruction set of a specified version.
1991 Is set by default to the highest supported version available
1992 (x86 only).
1993 -XX:UseAVX=version
1995 Enables the use of AVX instruction set of a specified version.
1996 Is set by default to the highest supported version available
1997 (x86 only).
1998 -XX:+UseAES
2000 Enables hardware-based AES intrinsics for hardware that supports
2001 it. This option is on by default on hardware that has the nec‐
2002 essary instructions. The -XX:+UseAES is used in conjunction
2003 with UseAESIntrinsics. Flags that control intrinsics now re‐
2004 quire the option -XX:+UnlockDiagnosticVMOptions.
2005 -XX:+UseAESIntrinsics
2007 Enables AES intrinsics. Specifying -XX:+UseAESIntrinsics is
2008 equivalent to also enabling -XX:+UseAES. To disable hardware-
2009 based AES intrinsics, specify -XX:-UseAES -XX:-UseAESIntrinsics.
2010 For example, to enable hardware AES, use the following flags:
2011 -XX:+UseAES -XX:+UseAESIntrinsics
2013 Flags that control intrinsics now require the option -XX:+Un‐
2015 lockDiagnosticVMOptions.
2016 -XX:+UseAESCTRIntrinsics
2018 Analogous to -XX:+UseAESIntrinsics enables AES/CTR intrinsics.
2019 -XX:+UseGHASHIntrinsics
2021 Controls the use of GHASH intrinsics. Enabled by default on
2022 platforms that support the corresponding instructions. Flags
2023 that control intrinsics now require the option -XX:+UnlockDiag‐
2024 nosticVMOptions.
2025 -XX:+UseChaCha20Intrinsics
2027 Enable ChaCha20 intrinsics. This option is on by default for
2028 supported platforms. To disable ChaCha20 intrinsics, specify
2029 -XX:-UseChaCha20Intrinsics. Flags that control intrinsics now
2030 require the option -XX:+UnlockDiagnosticVMOptions.
2031 -XX:+UsePoly1305Intrinsics
2033 Enable Poly1305 intrinsics. This option is on by default for
2034 supported platforms. To disable Poly1305 intrinsics, specify
2035 -XX:-UsePoly1305Intrinsics. Flags that control intrinsics now
2036 require the option -XX:+UnlockDiagnosticVMOptions.
2037 -XX:+UseBASE64Intrinsics
2039 Controls the use of accelerated BASE64 encoding routines for ja‐
2040 va.util.Base64. Enabled by default on platforms that support
2041 it. Flags that control intrinsics now require the option
2042 -XX:+UnlockDiagnosticVMOptions.
2043 -XX:+UseAdler32Intrinsics
2045 Controls the use of Adler32 checksum algorithm intrinsic for ja‐
2046 va.util.zip.Adler32. Enabled by default on platforms that sup‐
2047 port it. Flags that control intrinsics now require the option
2048 -XX:+UnlockDiagnosticVMOptions.
2049 -XX:+UseCRC32Intrinsics
2051 Controls the use of CRC32 intrinsics for java.util.zip.CRC32.
2052 Enabled by default on platforms that support it. Flags that
2053 control intrinsics now require the option -XX:+UnlockDiagnos‐
2054 ticVMOptions.
2055 -XX:+UseCRC32CIntrinsics
2057 Controls the use of CRC32C intrinsics for java.util.zip.CRC32C.
2058 Enabled by default on platforms that support it. Flags that
2059 control intrinsics now require the option -XX:+UnlockDiagnos‐
2060 ticVMOptions.
2061 -XX:+UseSHA
2063 Enables hardware-based intrinsics for SHA crypto hash functions
2064 for some hardware. The UseSHA option is used in conjunction
2065 with the UseSHA1Intrinsics, UseSHA256Intrinsics, and Use‐
2066 SHA512Intrinsics options.
2067 The UseSHA and UseSHA*Intrinsics flags are enabled by default on
2069 machines that support the corresponding instructions.
2070 This feature is applicable only when using the sun.securi‐
2072 ty.provider.Sun provider for SHA operations. Flags that control
2073 intrinsics now require the option -XX:+UnlockDiagnosticVMOp‐
2074 tions.
2075 To disable all hardware-based SHA intrinsics, specify the
2077 -XX:-UseSHA. To disable only a particular SHA intrinsic, use
2078 the appropriate corresponding option. For example: -XX:-Use‐
2079 SHA256Intrinsics.
2080 -XX:+UseSHA1Intrinsics
2082 Enables intrinsics for SHA-1 crypto hash function. Flags that
2083 control intrinsics now require the option -XX:+UnlockDiagnos‐
2084 ticVMOptions.
2085 -XX:+UseSHA256Intrinsics
2087 Enables intrinsics for SHA-224 and SHA-256 crypto hash func‐
2088 tions. Flags that control intrinsics now require the option
2089 -XX:+UnlockDiagnosticVMOptions.
2090 -XX:+UseSHA512Intrinsics
2092 Enables intrinsics for SHA-384 and SHA-512 crypto hash func‐
2093 tions. Flags that control intrinsics now require the option
2094 -XX:+UnlockDiagnosticVMOptions.
2095 -XX:+UseMathExactIntrinsics
2097 Enables intrinsification of various java.lang.Math.*Exact()
2098 functions. Enabled by default. Flags that control intrinsics
2099 now require the option -XX:+UnlockDiagnosticVMOptions.
2100 -XX:+UseMultiplyToLenIntrinsic
2102 Enables intrinsification of BigInteger.multiplyToLen(). Enabled
2103 by default on platforms that support it. Flags that control in‐
2104 trinsics now require the option -XX:+UnlockDiagnosticVMOptions.
2105 -XX:+UseSquareToLenIntrinsic
2107 Enables intrinsification of BigInteger.squareToLen(). Enabled
2108 by default on platforms that support it. Flags that control in‐
2109 trinsics now require the option -XX:+UnlockDiagnosticVMOptions.
2110 -XX:+UseMulAddIntrinsic
2112 Enables intrinsification of BigInteger.mulAdd(). Enabled by de‐
2113 fault on platforms that support it. Flags that control intrin‐
2114 sics now require the option -XX:+UnlockDiagnosticVMOptions.
2115 -XX:+UseMontgomeryMultiplyIntrinsic
2117 Enables intrinsification of BigInteger.montgomeryMultiply().
2118 Enabled by default on platforms that support it. Flags that
2119 control intrinsics now require the option -XX:+UnlockDiagnos‐
2120 ticVMOptions.
2121 -XX:+UseMontgomerySquareIntrinsic
2123 Enables intrinsification of BigInteger.montgomerySquare(). En‐
2124 abled by default on platforms that support it. Flags that con‐
2125 trol intrinsics now require the option -XX:+UnlockDiagnosticV‐
2126 MOptions.
2127 -XX:+UseCMoveUnconditionally
2129 Generates CMove (scalar and vector) instructions regardless of
2130 profitability analysis.
2131 -XX:+UseCodeCacheFlushing
2133 Enables flushing of the code cache before shutting down the com‐
2134 piler. This option is enabled by default. To disable flushing
2135 of the code cache before shutting down the compiler, specify
2136 -XX:-UseCodeCacheFlushing.
2137 -XX:+UseCondCardMark
2139 Enables checking if the card is already marked before updating
2140 the card table. This option is disabled by default. It should
2141 be used only on machines with multiple sockets, where it in‐
2142 creases the performance of Java applications that rely on con‐
2143 current operations.
2144 -XX:+UseCountedLoopSafepoints
2146 Keeps safepoints in counted loops. Its default value depends on
2147 whether the selected garbage collector requires low latency
2148 safepoints.
2149 -XX:LoopStripMiningIter=number_of_iterations
2151 Controls the number of iterations in the inner strip mined loop.
2152 Strip mining transforms counted loops into two level nested
2153 loops. Safepoints are kept in the outer loop while the inner
2154 loop can execute at full speed. This option controls the maxi‐
2155 mum number of iterations in the inner loop. The default value
2156 is 1,000.
2157 -XX:LoopStripMiningIterShortLoop=number_of_iterations
2159 Controls loop strip mining optimization. Loops with the number
2160 of iterations less than specified will not have safepoints in
2161 them. Default value is 1/10th of -XX:LoopStripMiningIter.
2162 -XX:+UseFMA
2164 Enables hardware-based FMA intrinsics for hardware where FMA in‐
2165 structions are available (such as, Intel and ARM64). FMA in‐
2166 trinsics are generated for the java.lang.Math.fma(a, b, c) meth‐
2167 ods that calculate the value of ( a * b + c ) expressions.
2168 -XX:+UseRTMDeopt
2170 Autotunes RTM locking depending on the abort ratio. This ratio
2171 is specified by the -XX:RTMAbortRatio option. If the number of
2172 aborted transactions exceeds the abort ratio, then the method
2173 containing the lock is deoptimized and recompiled with all locks
2174 as normal locks. This option is disabled by default. The
2175 -XX:+UseRTMLocking option must be enabled.
2176 -XX:+UseRTMLocking
2178 Generates Restricted Transactional Memory (RTM) locking code for
2179 all inflated locks, with the normal locking mechanism as the
2180 fallback handler. This option is disabled by default. Options
2181 related to RTM are available only on x86 CPUs that support
2182 Transactional Synchronization Extensions (TSX).
2183 RTM is part of Intel's TSX, which is an x86 instruction set ex‐
2185 tension and facilitates the creation of multithreaded applica‐
2186 tions. RTM introduces the new instructions XBEGIN, XABORT,
2187 XEND, and XTEST. The XBEGIN and XEND instructions enclose a set
2188 of instructions to run as a transaction. If no conflict is
2189 found when running the transaction, then the memory and register
2190 modifications are committed together at the XEND instruction.
2191 The XABORT instruction can be used to explicitly abort a trans‐
2192 action and the XTEST instruction checks if a set of instructions
2193 is being run in a transaction.
2194 A lock on a transaction is inflated when another thread tries to
2196 access the same transaction, thereby blocking the thread that
2197 didn't originally request access to the transaction. RTM re‐
2198 quires that a fallback set of operations be specified in case a
2199 transaction aborts or fails. An RTM lock is a lock that has
2200 been delegated to the TSX's system.
2201 RTM improves performance for highly contended locks with low
2203 conflict in a critical region (which is code that must not be
2204 accessed by more than one thread concurrently). RTM also im‐
2205 proves the performance of coarse-grain locking, which typically
2206 doesn't perform well in multithreaded applications. (Coarse-
2207 grain locking is the strategy of holding locks for long periods
2208 to minimize the overhead of taking and releasing locks, while
2209 fine-grained locking is the strategy of trying to achieve maxi‐
2210 mum parallelism by locking only when necessary and unlocking as
2211 soon as possible.) Also, for lightly contended locks that are
2212 used by different threads, RTM can reduce false cache line shar‐
2213 ing, also known as cache line ping-pong. This occurs when mul‐
2214 tiple threads from different processors are accessing different
2215 resources, but the resources share the same cache line. As a
2216 result, the processors repeatedly invalidate the cache lines of
2217 other processors, which forces them to read from main memory in‐
2218 stead of their cache.
2219 -XX:+UseSuperWord
2221 Enables the transformation of scalar operations into superword
2222 operations. Superword is a vectorization optimization. This
2223 option is enabled by default. To disable the transformation of
2224 scalar operations into superword operations, specify -XX:-UseSu‐
2225 perWord.
2226
2228 These java options provide the ability to gather system information and
2229 perform extensive debugging.
2230 -XX:+DisableAttachMechanism
2232 Disables the mechanism that lets tools attach to the JVM. By
2233 default, this option is disabled, meaning that the attach mecha‐
2234 nism is enabled and you can use diagnostics and troubleshooting
2235 tools such as jcmd, jstack, jmap, and jinfo.
2236 Note: The tools such as jcmd, jinfo, jmap, and jstack
2238 shipped with the JDK aren't supported when using the
2239 tools from one JDK version to troubleshoot a different
2240 JDK version.
2241 -XX:+DTraceAllocProbes
2243 Linux and macOS: Enable dtrace tool probes for object alloca‐
2244 tion.
2245 -XX:+DTraceMethodProbes
2247 Linux and macOS: Enable dtrace tool probes for method-entry and
2248 method-exit.
2249 -XX:+DTraceMonitorProbes
2251 Linux and macOS: Enable dtrace tool probes for monitor events.
2252 -XX:+HeapDumpOnOutOfMemoryError
2254 Enables the dumping of the Java heap to a file in the current
2255 directory by using the heap profiler (HPROF) when a ja‐
2256 va.lang.OutOfMemoryError exception is thrown. You can explicit‐
2257 ly set the heap dump file path and name using the -XX:HeapDump‐
2258 Path option. By default, this option is disabled and the heap
2259 isn't dumped when an OutOfMemoryError exception is thrown.
2260 -XX:HeapDumpPath=path
2262 Sets the path and file name for writing the heap dump provided
2263 by the heap profiler (HPROF) when the -XX:+HeapDumpOnOutOfMemo‐
2264 ryError option is set. By default, the file is created in the
2265 current working directory, and it's named java_pid<pid>.hprof
2266 where <pid> is the identifier of the process that caused the er‐
2267 ror. The following example shows how to set the default file
2268 explicitly (%p represents the current process identifier):
2269 -XX:HeapDumpPath=./java_pid%p.hprof
2271 • Non-Windows: The following example shows how to set the heap
2273 dump file to /var/log/java/java_heapdump.hprof:
2274 -XX:HeapDumpPath=/var/log/java/java_heapdump.hprof
2276 • Windows: The following example shows how to set the heap dump
2278 file to C:/log/java/java_heapdump.log:
2279 -XX:HeapDumpPath=C:/log/java/java_heapdump.log
2281 -XX:LogFile=path
2283 Sets the path and file name to where log data is written. By
2284 default, the file is created in the current working directory,
2285 and it's named hotspot.log.
2286 • Non-Windows: The following example shows how to set the log
2288 file to /var/log/java/hotspot.log:
2289 -XX:LogFile=/var/log/java/hotspot.log
2291 • Windows: The following example shows how to set the log file
2293 to C:/log/java/hotspot.log:
2294 -XX:LogFile=C:/log/java/hotspot.log
2296 -XX:+PrintClassHistogram
2298 Enables printing of a class instance histogram after one of the
2299 following events:
2300 • Non-Windows: Control+\ (SIGQUIT)
2302 • Windows: Control+C (SIGTERM)
2304 By default, this option is disabled.
2306 Setting this option is equivalent to running the jmap -histo
2308 command, or the jcmd pid GC.class_histogram command, where pid
2309 is the current Java process identifier.
2310 -XX:+PrintConcurrentLocks
2312 Enables printing of java.util.concurrent locks after one of the
2313 following events:
2314 • Non-Windows: Control+\ (SIGQUIT)
2316 • Windows: Control+C (SIGTERM)
2318 By default, this option is disabled.
2320 Setting this option is equivalent to running the jstack -l com‐
2322 mand or the jcmd pid Thread.print -l command, where pid is the
2323 current Java process identifier.
2324 -XX:+PrintFlagsRanges
2326 Prints the range specified and allows automatic testing of the
2327 values. See Validate Java Virtual Machine Flag Arguments.
2328 -XX:+PerfDataSaveToFile
2330 If enabled, saves jstat binary data when the Java application
2331 exits. This binary data is saved in a file named hsperfda‐
2332 ta_pid, where pid is the process identifier of the Java applica‐
2333 tion that you ran. Use the jstat command to display the perfor‐
2334 mance data contained in this file as follows:
2335 jstat -class file:///path/hsperfdata_pid
2337 jstat -gc file:///path/hsperfdata_pid
2339 -XX:+UsePerfData
2341 Enables the perfdata feature. This option is enabled by default
2342 to allow JVM monitoring and performance testing. Disabling it
2343 suppresses the creation of the hsperfdata_userid directories.
2344 To disable the perfdata feature, specify -XX:-UsePerfData.
2345
2347 These java options control how garbage collection (GC) is performed by
2348 the Java HotSpot VM.
2349 -XX:+AggressiveHeap
2351 Enables Java heap optimization. This sets various parameters to
2352 be optimal for long-running jobs with intensive memory alloca‐
2353 tion, based on the configuration of the computer (RAM and CPU).
2354 By default, the option is disabled and the heap sizes are con‐
2355 figured less aggressively.
2356 -XX:+AlwaysPreTouch
2358 Requests the VM to touch every page on the Java heap after re‐
2359 questing it from the operating system and before handing memory
2360 out to the application. By default, this option is disabled and
2361 all pages are committed as the application uses the heap space.
2362 -XX:ConcGCThreads=threads
2364 Sets the number of threads used for concurrent GC. Sets threads
2365 to approximately 1/4 of the number of parallel garbage collec‐
2366 tion threads. The default value depends on the number of CPUs
2367 available to the JVM.
2368 For example, to set the number of threads for concurrent GC to
2370 2, specify the following option:
2371 -XX:ConcGCThreads=2
2373 -XX:+DisableExplicitGC
2375 Enables the option that disables processing of calls to the Sys‐
2376 tem.gc() method. This option is disabled by default, meaning
2377 that calls to System.gc() are processed. If processing of calls
2378 to System.gc() is disabled, then the JVM still performs GC when
2379 necessary.
2380 -XX:+ExplicitGCInvokesConcurrent
2382 Enables invoking of concurrent GC by using the System.gc() re‐
2383 quest. This option is disabled by default and can be enabled
2384 only with the -XX:+UseG1GC option.
2385 -XX:G1AdaptiveIHOPNumInitialSamples=number
2387 When -XX:UseAdaptiveIHOP is enabled, this option sets the number
2388 of completed marking cycles used to gather samples until G1
2389 adaptively determines the optimum value of -XX:InitiatingHeapOc‐
2390 cupancyPercent. Before, G1 uses the value of -XX:Initiat‐
2391 ingHeapOccupancyPercent directly for this purpose. The default
2392 value is 3.
2393 -XX:G1HeapRegionSize=size
2395 Sets the size of the regions into which the Java heap is subdi‐
2396 vided when using the garbage-first (G1) collector. The value is
2397 a power of 2 and can range from 1 MB to 32 MB. The default re‐
2398 gion size is determined ergonomically based on the heap size
2399 with a goal of approximately 2048 regions.
2400 The following example sets the size of the subdivisions to 16
2402 MB:
2403 -XX:G1HeapRegionSize=16m
2405 -XX:G1HeapWastePercent=percent
2407 Sets the percentage of heap that you're willing to waste. The
2408 Java HotSpot VM doesn't initiate the mixed garbage collection
2409 cycle when the reclaimable percentage is less than the heap
2410 waste percentage. The default is 5 percent.
2411 -XX:G1MaxNewSizePercent=percent
2413 Sets the percentage of the heap size to use as the maximum for
2414 the young generation size. The default value is 60 percent of
2415 your Java heap.
2416 This is an experimental flag. This setting replaces the -XX:De‐
2418 faultMaxNewGenPercent setting.
2419 -XX:G1MixedGCCountTarget=number
2421 Sets the target number of mixed garbage collections after a
2422 marking cycle to collect old regions with at most G1MixedG‐
2423 CLIveThresholdPercent live data. The default is 8 mixed garbage
2424 collections. The goal for mixed collections is to be within
2425 this target number.
2426 -XX:G1MixedGCLiveThresholdPercent=percent
2428 Sets the occupancy threshold for an old region to be included in
2429 a mixed garbage collection cycle. The default occupancy is 85
2430 percent.
2431 This is an experimental flag. This setting replaces the
2433 -XX:G1OldCSetRegionLiveThresholdPercent setting.
2434 -XX:G1NewSizePercent=percent
2436 Sets the percentage of the heap to use as the minimum for the
2437 young generation size. The default value is 5 percent of your
2438 Java heap.
2439 This is an experimental flag. This setting replaces the -XX:De‐
2441 faultMinNewGenPercent setting.
2442 -XX:G1OldCSetRegionThresholdPercent=percent
2444 Sets an upper limit on the number of old regions to be collected
2445 during a mixed garbage collection cycle. The default is 10 per‐
2446 cent of the Java heap.
2447 -XX:G1ReservePercent=percent
2449 Sets the percentage of the heap (0 to 50) that's reserved as a
2450 false ceiling to reduce the possibility of promotion failure for
2451 the G1 collector. When you increase or decrease the percentage,
2452 ensure that you adjust the total Java heap by the same amount.
2453 By default, this option is set to 10%.
2454 The following example sets the reserved heap to 20%:
2456 -XX:G1ReservePercent=20
2458 -XX:+G1UseAdaptiveIHOP
2460 Controls adaptive calculation of the old generation occupancy to
2461 start background work preparing for an old generation collec‐
2462 tion. If enabled, G1 uses -XX:InitiatingHeapOccupancyPercent
2463 for the first few times as specified by the value of -XX:G1Adap‐
2464 tiveIHOPNumInitialSamples, and after that adaptively calculates
2465 a new optimum value for the initiating occupancy automatically.
2466 Otherwise, the old generation collection process always starts
2467 at the old generation occupancy determined by -XX:Initiat‐
2468 ingHeapOccupancyPercent.
2469 The default is enabled.
2471 -XX:InitialHeapSize=size
2473 Sets the initial size (in bytes) of the memory allocation pool.
2474 This value must be either 0, or a multiple of 1024 and greater
2475 than 1 MB. Append the letter k or K to indicate kilobytes, m or
2476 M to indicate megabytes, or g or G to indicate gigabytes. The
2477 default value is selected at run time based on the system con‐
2478 figuration.
2479 The following examples show how to set the size of allocated
2481 memory to 6 MB using various units:
2482 -XX:InitialHeapSize=6291456
2484 -XX:InitialHeapSize=6144k
2485 -XX:InitialHeapSize=6m
2486 If you set this option to 0, then the initial size is set as the
2488 sum of the sizes allocated for the old generation and the young
2489 generation. The size of the heap for the young generation can
2490 be set using the -XX:NewSize option. Note that the -Xms option
2491 sets both the minimum and the initial heap size of the heap. If
2492 -Xms appears after -XX:InitialHeapSize on the command line, then
2493 the initial heap size gets set to the value specified with -Xms.
2494 -XX:InitialRAMPercentage=percent
2496 Sets the initial amount of memory that the JVM will use for the
2497 Java heap before applying ergonomics heuristics as a percentage
2498 of the maximum amount determined as described in the -XX:MaxRAM
2499 option. The default value is 1.5625 percent.
2500 The following example shows how to set the percentage of the
2502 initial amount of memory used for the Java heap:
2503 -XX:InitialRAMPercentage=5
2505 -XX:InitialSurvivorRatio=ratio
2507 Sets the initial survivor space ratio used by the throughput
2508 garbage collector (which is enabled by the -XX:+UseParallelGC
2509 option). Adaptive sizing is enabled by default with the
2510 throughput garbage collector by using the -XX:+UseParallelGC op‐
2511 tion, and the survivor space is resized according to the appli‐
2512 cation behavior, starting with the initial value. If adaptive
2513 sizing is disabled (using the -XX:-UseAdaptiveSizePolicy op‐
2514 tion), then the -XX:SurvivorRatio option should be used to set
2515 the size of the survivor space for the entire execution of the
2516 application.
2517 The following formula can be used to calculate the initial size
2519 of survivor space (S) based on the size of the young generation
2520 (Y), and the initial survivor space ratio (R):
2521 S=Y/(R+2)
2523 The 2 in the equation denotes two survivor spaces. The larger
2525 the value specified as the initial survivor space ratio, the
2526 smaller the initial survivor space size.
2527 By default, the initial survivor space ratio is set to 8. If
2529 the default value for the young generation space size is used (2
2530 MB), then the initial size of the survivor space is 0.2 MB.
2531 The following example shows how to set the initial survivor
2533 space ratio to 4:
2534 -XX:InitialSurvivorRatio=4
2536 -XX:InitiatingHeapOccupancyPercent=percent
2538 Sets the percentage of the old generation occupancy (0 to 100)
2539 at which to start the first few concurrent marking cycles for
2540 the G1 garbage collector.
2541 By default, the initiating value is set to 45%. A value of 0
2543 implies nonstop concurrent GC cycles from the beginning until G1
2544 adaptively sets this value.
2545 See also the -XX:G1UseAdaptiveIHOP and -XX:G1AdaptiveIHOPNumIni‐
2547 tialSamples options.
2548 The following example shows how to set the initiating heap occu‐
2550 pancy to 75%:
2551 -XX:InitiatingHeapOccupancyPercent=75
2553 -XX:MaxGCPauseMillis=time
2555 Sets a target for the maximum GC pause time (in milliseconds).
2556 This is a soft goal, and the JVM will make its best effort to
2557 achieve it. The specified value doesn't adapt to your heap
2558 size. By default, for G1 the maximum pause time target is 200
2559 milliseconds. The other generational collectors do not use a
2560 pause time goal by default.
2561 The following example shows how to set the maximum target pause
2563 time to 500 ms:
2564 -XX:MaxGCPauseMillis=500
2566 -XX:MaxHeapSize=size
2568 Sets the maximum size (in byes) of the memory allocation pool.
2569 This value must be a multiple of 1024 and greater than 2 MB.
2570 Append the letter k or K to indicate kilobytes, m or M to indi‐
2571 cate megabytes, or g or G to indicate gigabytes. The default
2572 value is selected at run time based on the system configuration.
2573 For server deployments, the options -XX:InitialHeapSize and
2574 -XX:MaxHeapSize are often set to the same value.
2575 The following examples show how to set the maximum allowed size
2577 of allocated memory to 80 MB using various units:
2578 -XX:MaxHeapSize=83886080
2580 -XX:MaxHeapSize=81920k
2581 -XX:MaxHeapSize=80m
2582 The -XX:MaxHeapSize option is equivalent to -Xmx.
2584 -XX:MaxHeapFreeRatio=percent
2586 Sets the maximum allowed percentage of free heap space (0 to
2587 100) after a GC event. If free heap space expands above this
2588 value, then the heap is shrunk. By default, this value is set
2589 to 70%.
2590 Minimize the Java heap size by lowering the values of the param‐
2592 eters MaxHeapFreeRatio (default value is 70%) and MinHeapFreeRa‐
2593 tio (default value is 40%) with the command-line options
2594 -XX:MaxHeapFreeRatio and -XX:MinHeapFreeRatio. Lowering Max‐
2595 HeapFreeRatio to as low as 10% and MinHeapFreeRatio to 5% has
2596 successfully reduced the heap size without too much performance
2597 regression; however, results may vary greatly depending on your
2598 application. Try different values for these parameters until
2599 they're as low as possible yet still retain acceptable perfor‐
2600 mance.
2601 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
2603 Customers trying to keep the heap small should also add the op‐
2605 tion -XX:-ShrinkHeapInSteps. See Performance Tuning Examples
2606 for a description of using this option to keep the Java heap
2607 small by reducing the dynamic footprint for embedded applica‐
2608 tions.
2609 -XX:MaxMetaspaceSize=size
2611 Sets the maximum amount of native memory that can be allocated
2612 for class metadata. By default, the size isn't limited. The
2613 amount of metadata for an application depends on the application
2614 itself, other running applications, and the amount of memory
2615 available on the system.
2616 The following example shows how to set the maximum class metada‐
2618 ta size to 256 MB:
2619 -XX:MaxMetaspaceSize=256m
2621 -XX:MaxNewSize=size
2623 Sets the maximum size (in bytes) of the heap for the young gen‐
2624 eration (nursery). The default value is set ergonomically.
2625 -XX:MaxRAM=size
2627 Sets the maximum amount of memory that the JVM may use for the
2628 Java heap before applying ergonomics heuristics. The default
2629 value is the maximum amount of available memory to the JVM
2630 process or 128 GB, whichever is lower.
2631 The maximum amount of available memory to the JVM process is the
2633 minimum of the machine's physical memory and any constraints set
2634 by the environment (e.g. container).
2635 Specifying this option disables automatic use of compressed oops
2637 if the combined result of this and other options influencing the
2638 maximum amount of memory is larger than the range of memory ad‐
2639 dressable by compressed oops. See -XX:UseCompressedOops for
2640 further information about compressed oops.
2641 The following example shows how to set the maximum amount of
2643 available memory for sizing the Java heap to 2 GB:
2644 -XX:MaxRAM=2G
2646 -XX:MaxRAMPercentage=percent
2648 Sets the maximum amount of memory that the JVM may use for the
2649 Java heap before applying ergonomics heuristics as a percentage
2650 of the maximum amount determined as described in the -XX:MaxRAM
2651 option. The default value is 25 percent.
2652 Specifying this option disables automatic use of compressed oops
2654 if the combined result of this and other options influencing the
2655 maximum amount of memory is larger than the range of memory ad‐
2656 dressable by compressed oops. See -XX:UseCompressedOops for
2657 further information about compressed oops.
2658 The following example shows how to set the percentage of the
2660 maximum amount of memory used for the Java heap:
2661 -XX:MaxRAMPercentage=75
2663 -XX:MinRAMPercentage=percent
2665 Sets the maximum amount of memory that the JVM may use for the
2666 Java heap before applying ergonomics heuristics as a percentage
2667 of the maximum amount determined as described in the -XX:MaxRAM
2668 option for small heaps. A small heap is a heap of approximately
2669 125 MB. The default value is 50 percent.
2670 The following example shows how to set the percentage of the
2672 maximum amount of memory used for the Java heap for small heaps:
2673 -XX:MinRAMPercentage=75
2675 -XX:MaxTenuringThreshold=threshold
2677 Sets the maximum tenuring threshold for use in adaptive GC siz‐
2678 ing. The largest value is 15. The default value is 15 for the
2679 parallel (throughput) collector.
2680 The following example shows how to set the maximum tenuring
2682 threshold to 10:
2683 -XX:MaxTenuringThreshold=10
2685 -XX:MetaspaceSize=size
2687 Sets the size of the allocated class metadata space that trig‐
2688 gers a garbage collection the first time it's exceeded. This
2689 threshold for a garbage collection is increased or decreased de‐
2690 pending on the amount of metadata used. The default size de‐
2691 pends on the platform.
2692 -XX:MinHeapFreeRatio=percent
2694 Sets the minimum allowed percentage of free heap space (0 to
2695 100) after a GC event. If free heap space falls below this val‐
2696 ue, then the heap is expanded. By default, this value is set to
2697 40%.
2698 Minimize Java heap size by lowering the values of the parameters
2700 MaxHeapFreeRatio (default value is 70%) and MinHeapFreeRatio
2701 (default value is 40%) with the command-line options -XX:Max‐
2702 HeapFreeRatio and -XX:MinHeapFreeRatio. Lowering MaxHeapFreeRa‐
2703 tio to as low as 10% and MinHeapFreeRatio to 5% has successfully
2704 reduced the heap size without too much performance regression;
2705 however, results may vary greatly depending on your application.
2706 Try different values for these parameters until they're as low
2707 as possible, yet still retain acceptable performance.
2708 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
2710 Customers trying to keep the heap small should also add the op‐
2712 tion -XX:-ShrinkHeapInSteps. See Performance Tuning Examples
2713 for a description of using this option to keep the Java heap
2714 small by reducing the dynamic footprint for embedded applica‐
2715 tions.
2716 -XX:MinHeapSize=size
2718 Sets the minimum size (in bytes) of the memory allocation pool.
2719 This value must be either 0, or a multiple of 1024 and greater
2720 than 1 MB. Append the letter k or K to indicate kilobytes, m or
2721 M to indicate megabytes, or g or G to indicate gigabytes. The
2722 default value is selected at run time based on the system con‐
2723 figuration.
2724 The following examples show how to set the minimum size of allo‐
2726 cated memory to 6 MB using various units:
2727 -XX:MinHeapSize=6291456
2729 -XX:MinHeapSize=6144k
2730 -XX:MinHeapSize=6m
2731 If you set this option to 0, then the minimum size is set to the
2733 same value as the initial size.
2734 -XX:NewRatio=ratio
2736 Sets the ratio between young and old generation sizes. By de‐
2737 fault, this option is set to 2. The following example shows how
2738 to set the young-to-old ratio to 1:
2739 -XX:NewRatio=1
2741 -XX:NewSize=size
2743 Sets the initial size (in bytes) of the heap for the young gen‐
2744 eration (nursery). Append the letter k or K to indicate kilo‐
2745 bytes, m or M to indicate megabytes, or g or G to indicate giga‐
2746 bytes.
2747 The young generation region of the heap is used for new objects.
2749 GC is performed in this region more often than in other regions.
2750 If the size for the young generation is too low, then a large
2751 number of minor GCs are performed. If the size is too high,
2752 then only full GCs are performed, which can take a long time to
2753 complete. It is recommended that you keep the size for the
2754 young generation greater than 25% and less than 50% of the over‐
2755 all heap size.
2756 The following examples show how to set the initial size of the
2758 young generation to 256 MB using various units:
2759 -XX:NewSize=256m
2761 -XX:NewSize=262144k
2762 -XX:NewSize=268435456
2763 The -XX:NewSize option is equivalent to -Xmn.
2765 -XX:ParallelGCThreads=threads
2767 Sets the number of the stop-the-world (STW) worker threads. The
2768 default value depends on the number of CPUs available to the JVM
2769 and the garbage collector selected.
2770 For example, to set the number of threads for G1 GC to 2, speci‐
2772 fy the following option:
2773 -XX:ParallelGCThreads=2
2775 -XX:+ParallelRefProcEnabled
2777 Enables parallel reference processing. By default, this option
2778 is disabled.
2779 -XX:+PrintAdaptiveSizePolicy
2781 Enables printing of information about adaptive-generation siz‐
2782 ing. By default, this option is disabled.
2783 -XX:+ScavengeBeforeFullGC
2785 Enables GC of the young generation before each full GC. This
2786 option is enabled by default. It is recommended that you don't
2787 disable it, because scavenging the young generation before a
2788 full GC can reduce the number of objects reachable from the old
2789 generation space into the young generation space. To disable GC
2790 of the young generation before each full GC, specify the option
2791 -XX:-ScavengeBeforeFullGC.
2792 -XX:SoftRefLRUPolicyMSPerMB=time
2794 Sets the amount of time (in milliseconds) a softly reachable ob‐
2795 ject is kept active on the heap after the last time it was ref‐
2796 erenced. The default value is one second of lifetime per free
2797 megabyte in the heap. The -XX:SoftRefLRUPolicyMSPerMB option
2798 accepts integer values representing milliseconds per one
2799 megabyte of the current heap size (for Java HotSpot Client VM)
2800 or the maximum possible heap size (for Java HotSpot Server VM).
2801 This difference means that the Client VM tends to flush soft
2802 references rather than grow the heap, whereas the Server VM
2803 tends to grow the heap rather than flush soft references. In
2804 the latter case, the value of the -Xmx option has a significant
2805 effect on how quickly soft references are garbage collected.
2806 The following example shows how to set the value to 2.5 seconds:
2808 -XX:SoftRefLRUPolicyMSPerMB=2500
2810 -XX:-ShrinkHeapInSteps
2812 Incrementally reduces the Java heap to the target size, speci‐
2813 fied by the option -XX:MaxHeapFreeRatio. This option is enabled
2814 by default. If disabled, then it immediately reduces the Java
2815 heap to the target size instead of requiring multiple garbage
2816 collection cycles. Disable this option if you want to minimize
2817 the Java heap size. You will likely encounter performance
2818 degradation when this option is disabled.
2819 See Performance Tuning Examples for a description of using the
2821 MaxHeapFreeRatio option to keep the Java heap small by reducing
2822 the dynamic footprint for embedded applications.
2823 -XX:StringDeduplicationAgeThreshold=threshold
2825 Identifies String objects reaching the specified age that are
2826 considered candidates for deduplication. An object's age is a
2827 measure of how many times it has survived garbage collection.
2828 This is sometimes referred to as tenuring.
2829 Note: String objects that are promoted to an old heap re‐
2831 gion before this age has been reached are always consid‐
2832 ered candidates for deduplication. The default value for
2833 this option is 3. See the -XX:+UseStringDeduplication
2834 option.
2835 -XX:SurvivorRatio=ratio
2837 Sets the ratio between eden space size and survivor space size.
2838 By default, this option is set to 8. The following example
2839 shows how to set the eden/survivor space ratio to 4:
2840 -XX:SurvivorRatio=4
2842 -XX:TargetSurvivorRatio=percent
2844 Sets the desired percentage of survivor space (0 to 100) used
2845 after young garbage collection. By default, this option is set
2846 to 50%.
2847 The following example shows how to set the target survivor space
2849 ratio to 30%:
2850 -XX:TargetSurvivorRatio=30
2852 -XX:TLABSize=size
2854 Sets the initial size (in bytes) of a thread-local allocation
2855 buffer (TLAB). Append the letter k or K to indicate kilobytes,
2856 m or M to indicate megabytes, or g or G to indicate gigabytes.
2857 If this option is set to 0, then the JVM selects the initial
2858 size automatically.
2859 The following example shows how to set the initial TLAB size to
2861 512 KB:
2862 -XX:TLABSize=512k
2864 -XX:+UseAdaptiveSizePolicy
2866 Enables the use of adaptive generation sizing. This option is
2867 enabled by default. To disable adaptive generation sizing,
2868 specify -XX:-UseAdaptiveSizePolicy and set the size of the memo‐
2869 ry allocation pool explicitly. See the -XX:SurvivorRatio op‐
2870 tion.
2871 -XX:+UseG1GC
2873 Enables the use of the garbage-first (G1) garbage collector.
2874 It's a server-style garbage collector, targeted for multiproces‐
2875 sor machines with a large amount of RAM. This option meets GC
2876 pause time goals with high probability, while maintaining good
2877 throughput. The G1 collector is recommended for applications
2878 requiring large heaps (sizes of around 6 GB or larger) with lim‐
2879 ited GC latency requirements (a stable and predictable pause
2880 time below 0.5 seconds). By default, this option is enabled and
2881 G1 is used as the default garbage collector.
2882 -XX:+UseGCOverheadLimit
2884 Enables the use of a policy that limits the proportion of time
2885 spent by the JVM on GC before an OutOfMemoryError exception is
2886 thrown. This option is enabled, by default, and the parallel GC
2887 will throw an OutOfMemoryError if more than 98% of the total
2888 time is spent on garbage collection and less than 2% of the heap
2889 is recovered. When the heap is small, this feature can be used
2890 to prevent applications from running for long periods of time
2891 with little or no progress. To disable this option, specify the
2892 option -XX:-UseGCOverheadLimit.
2893 -XX:+UseNUMA
2895 Enables performance optimization of an application on a machine
2896 with nonuniform memory architecture (NUMA) by increasing the ap‐
2897 plication's use of lower latency memory. By default, this op‐
2898 tion is disabled and no optimization for NUMA is made. The op‐
2899 tion is available only when the parallel garbage collector is
2900 used (-XX:+UseParallelGC).
2901 -XX:+UseParallelGC
2903 Enables the use of the parallel scavenge garbage collector (also
2904 known as the throughput collector) to improve the performance of
2905 your application by leveraging multiple processors.
2906 By default, this option is disabled and the default collector is
2908 used.
2909 -XX:+UseSerialGC
2911 Enables the use of the serial garbage collector. This is gener‐
2912 ally the best choice for small and simple applications that
2913 don't require any special functionality from garbage collection.
2914 By default, this option is disabled and the default collector is
2915 used.
2916 -XX:+UseSHM
2918 Linux only: Enables the JVM to use shared memory to set up large
2919 pages.
2920 See Large Pages for setting up large pages.
2922 -XX:+UseStringDeduplication
2924 Enables string deduplication. By default, this option is dis‐
2925 abled. To use this option, you must enable the garbage-first
2926 (G1) garbage collector.
2927 String deduplication reduces the memory footprint of String ob‐
2929 jects on the Java heap by taking advantage of the fact that many
2930 String objects are identical. Instead of each String object
2931 pointing to its own character array, identical String objects
2932 can point to and share the same character array.
2933 -XX:+UseTLAB
2935 Enables the use of thread-local allocation blocks (TLABs) in the
2936 young generation space. This option is enabled by default. To
2937 disable the use of TLABs, specify the option -XX:-UseTLAB.
2938 -XX:+UseZGC
2940 Enables the use of the Z garbage collector (ZGC). This is a low
2941 latency garbage collector, providing max pause times of a few
2942 milliseconds, at some throughput cost. Pause times are indepen‐
2943 dent of what heap size is used. Supports heap sizes from 8MB to
2944 16TB.
2945 -XX:ZAllocationSpikeTolerance=factor
2947 Sets the allocation spike tolerance for ZGC. By default, this
2948 option is set to 2.0. This factor describes the level of allo‐
2949 cation spikes to expect. For example, using a factor of 3.0
2950 means the current allocation rate can be expected to triple at
2951 any time.
2952 -XX:ZCollectionInterval=seconds
2954 Sets the maximum interval (in seconds) between two GC cycles
2955 when using ZGC. By default, this option is set to 0 (disabled).
2956 -XX:ZFragmentationLimit=percent
2958 Sets the maximum acceptable heap fragmentation (in percent) for
2959 ZGC. By default, this option is set to 25. Using a lower value
2960 will cause the heap to be compacted more aggressively, to re‐
2961 claim more memory at the cost of using more CPU time.
2962 -XX:+ZProactive
2964 Enables proactive GC cycles when using ZGC. By default, this
2965 option is enabled. ZGC will start a proactive GC cycle if doing
2966 so is expected to have minimal impact on the running applica‐
2967 tion. This is useful if the application is mostly idle or allo‐
2968 cates very few objects, but you still want to keep the heap size
2969 down and allow reference processing to happen even when there
2970 are a lot of free space on the heap.
2971 -XX:+ZUncommit
2973 Enables uncommitting of unused heap memory when using ZGC. By
2974 default, this option is enabled. Uncommitting unused heap memo‐
2975 ry will lower the memory footprint of the JVM, and make that
2976 memory available for other processes to use.
2977 -XX:ZUncommitDelay=seconds
2979 Sets the amount of time (in seconds) that heap memory must have
2980 been unused before being uncommitted. By default, this option
2981 is set to 300 (5 minutes). Committing and uncommitting memory
2982 are relatively expensive operations. Using a lower value will
2983 cause heap memory to be uncommitted earlier, at the risk of soon
2984 having to commit it again.
2985
2987 These java options are deprecated and might be removed in a future JDK
2988 release. They're still accepted and acted upon, but a warning is is‐
2989 sued when they're used.
2990 -Xfuture
2992 Enables strict class-file format checks that enforce close con‐
2993 formance to the class-file format specification. Developers
2994 should use this flag when developing new code. Stricter checks
2995 may become the default in future releases.
2996 -Xloggc:filename
2998 Sets the file to which verbose GC events information should be
2999 redirected for logging. The -Xloggc option overrides -ver‐
3000 bose:gc if both are given with the same java command. -Xlog‐
3001 gc:filename is replaced by -Xlog:gc:filename. See Enable Log‐
3002 ging with the JVM Unified Logging Framework.
3003 Example:
3005 -Xlog:gc:garbage-collection.log
3007 -XX:+FlightRecorder
3009 Enables the use of Java Flight Recorder (JFR) during the runtime
3010 of the application. Since JDK 8u40 this option has not been re‐
3011 quired to use JFR.
3012 -XX:InitialRAMFraction=ratio
3014 Sets the initial amount of memory that the JVM may use for the
3015 Java heap before applying ergonomics heuristics as a ratio of
3016 the maximum amount determined as described in the -XX:MaxRAM op‐
3017 tion. The default value is 64.
3018 Use the option -XX:InitialRAMPercentage instead.
3020 -XX:MaxRAMFraction=ratio
3022 Sets the maximum amount of memory that the JVM may use for the
3023 Java heap before applying ergonomics heuristics as a fraction of
3024 the maximum amount determined as described in the -XX:MaxRAM op‐
3025 tion. The default value is 4.
3026 Specifying this option disables automatic use of compressed oops
3028 if the combined result of this and other options influencing the
3029 maximum amount of memory is larger than the range of memory ad‐
3030 dressable by compressed oops. See -XX:UseCompressedOops for
3031 further information about compressed oops.
3032 Use the option -XX:MaxRAMPercentage instead.
3034 -XX:MinRAMFraction=ratio
3036 Sets the maximum amount of memory that the JVM may use for the
3037 Java heap before applying ergonomics heuristics as a fraction of
3038 the maximum amount determined as described in the -XX:MaxRAM op‐
3039 tion for small heaps. A small heap is a heap of approximately
3040 125 MB. The default value is 2.
3041 Use the option -XX:MinRAMPercentage instead.
3043
3045 These java options are still accepted but ignored, and a warning is is‐
3046 sued when they're used.
3047 --illegal-access=parameter
3049 Controlled relaxed strong encapsulation, as defined in JEP 261
3050 [https://openjdk.org/jeps/261#Relaxed-strong-encapsulation].
3051 This option was deprecated in JDK 16 by JEP 396 [https://open‐
3052 jdk.org/jeps/396] and made obsolete in JDK 17 by JEP 403
3053 [https://openjdk.org/jeps/403].
3054
3056 These java options have been removed in JDK 21 and using them results
3057 in an error of:
3058 Unrecognized VM option option-name
3060 -XX:+ExtendedDTraceProbes
3062 Linux and macOS: Enables additional dtrace tool probes that af‐
3063 fect performance. By default, this option is disabled and
3064 dtrace performs only standard probes. Use the combination of
3065 these flags instead: -XX:+DTraceMethodProbes, -XX:+DTraceAl‐
3066 locProbes, -XX:+DTraceMonitorProbes.
3067 For the lists and descriptions of options removed in previous releases
3069 see the Removed Java Options section in:
3070 • The java Command, Release 20 [https://docs.oracle.com/en/ja‐
3072 va/javase/20/docs/specs/man/java.html]
3073 • The java Command, Release 19 [https://docs.oracle.com/en/ja‐
3075 va/javase/19/docs/specs/man/java.html]
3076 • The java Command, Release 18 [https://docs.oracle.com/en/ja‐
3078 va/javase/18/docs/specs/man/java.html]
3079 • The java Command, Release 17 [https://docs.oracle.com/en/ja‐
3081 va/javase/17/docs/specs/man/java.html]
3082 • The java Command, Release 16 [https://docs.oracle.com/en/ja‐
3084 va/javase/16/docs/specs/man/java.html]
3085 • The java Command, Release 15 [https://docs.oracle.com/en/ja‐
3087 va/javase/15/docs/specs/man/java.html]
3088 • The java Command, Release 14 [https://docs.oracle.com/en/ja‐
3090 va/javase/14/docs/specs/man/java.html]
3091 • The java Command, Release 13 [https://docs.oracle.com/en/ja‐
3093 va/javase/13/docs/specs/man/java.html]
3094 • Java Platform, Standard Edition Tools Reference, Release 12
3096 [https://docs.oracle.com/en/java/javase/12/tools/ja‐
3097 va.html#GUID-3B1CE181-CD30-4178-9602-230B800D4FAE]
3098 • Java Platform, Standard Edition Tools Reference, Release 11
3100 [https://docs.oracle.com/en/java/javase/11/tools/ja‐
3101 va.html#GUID-741FC470-AA3E-494A-8D2B-1B1FE4A990D1]
3102 • Java Platform, Standard Edition Tools Reference, Release 10
3104 [https://docs.oracle.com/javase/10/tools/java.htm#JSWOR624]
3105 • Java Platform, Standard Edition Tools Reference, Release 9
3107 [https://docs.oracle.com/javase/9/tools/java.htm#JSWOR624]
3108 • Java Platform, Standard Edition Tools Reference, Release 8 for Oracle
3110 JDK on Windows [https://docs.oracle.com/javase/8/docs/tech‐
3111 notes/tools/windows/java.html#BGBCIEFC]
3112 • Java Platform, Standard Edition Tools Reference, Release 8 for Oracle
3114 JDK on Solaris, Linux, and macOS [https://docs.ora‐
3115 cle.com/javase/8/docs/technotes/tools/unix/java.html#BGBCIEFC]
3116
3118 You can shorten or simplify the java command by using @ argument files
3119 to specify one or more text files that contain arguments, such as op‐
3120 tions and class names, which are passed to the java command. This
3121 let's you to create java commands of any length on any operating sys‐
3122 tem.
3123 In the command line, use the at sign (@) prefix to identify an argument
3125 file that contains java options and class names. When the java command
3126 encounters a file beginning with the at sign (@), it expands the con‐
3127 tents of that file into an argument list just as they would be speci‐
3128 fied on the command line.
3129 The java launcher expands the argument file contents until it encoun‐
3131 ters the --disable-@files option. You can use the --disable-@files op‐
3132 tion anywhere on the command line, including in an argument file, to
3133 stop @ argument files expansion.
3134 The following items describe the syntax of java argument files:
3136 • The argument file must contain only ASCII characters or characters in
3138 system default encoding that's ASCII friendly, such as UTF-8.
3139 • The argument file size must not exceed MAXINT (2,147,483,647) bytes.
3141 • The launcher doesn't expand wildcards that are present within an ar‐
3143 gument file.
3144 • Use white space or new line characters to separate arguments included
3146 in the file.
3147 • White space includes a white space character, \t, \n, \r, and \f.
3149 For example, it is possible to have a path with a space, such as
3151 c:\Program Files that can be specified as either "c:\\Program Files"
3152 or, to avoid an escape, c:\Program" "Files.
3153 • Any option that contains spaces, such as a path component, must be
3155 within quotation marks using quotation ('"') characters in its en‐
3156 tirety.
3157 • A string within quotation marks may contain the characters \n, \r,
3159 \t, and \f. They are converted to their respective ASCII codes.
3160 • If a file name contains embedded spaces, then put the whole file name
3162 in double quotation marks.
3163 • File names in an argument file are relative to the current directory,
3165 not to the location of the argument file.
3166 • Use the number sign # in the argument file to identify comments. All
3168 characters following the # are ignored until the end of line.
3169 • Additional at sign @ prefixes to @ prefixed options act as an escape,
3171 (the first @ is removed and the rest of the arguments are presented
3172 to the launcher literally).
3173 • Lines may be continued using the continuation character (\) at the
3175 end-of-line. The two lines are concatenated with the leading white
3176 spaces trimmed. To prevent trimming the leading white spaces, a con‐
3177 tinuation character (\) may be placed at the first column.
3178 • Because backslash (\) is an escape character, a backslash character
3180 must be escaped with another backslash character.
3181 • Partial quote is allowed and is closed by an end-of-file.
3183 • An open quote stops at end-of-line unless \ is the last character,
3185 which then joins the next line by removing all leading white space
3186 characters.
3187 • Wildcards (*) aren't allowed in these lists (such as specifying *.ja‐
3189 va).
3190 • Use of the at sign (@) to recursively interpret files isn't support‐
3192 ed.
3193 Example of Open or Partial Quotes in an Argument File
3195 In the argument file,
3196 -cp "lib/
3198 cool/
3199 app/
3200 jars
3201 this is interpreted as:
3203 -cp lib/cool/app/jars
3205 Example of a Backslash Character Escaped with Another Backslash Character
3207 in an Argument File
3208 To output the following:
3209 -cp c:\Program Files (x86)\Java\jre\lib\ext;c:\Program Files\Ja‐
3211 va\jre9\lib\ext
3212 The backslash character must be specified in the argument file as:
3214 -cp "c:\\Program Files (x86)\\Java\\jre\\lib\\ext;c:\\Program
3216 Files\\Java\\jre9\\lib\\ext"
3217 Example of an EOL Escape Used to Force Concatenation of Lines in an Argu‐
3219 ment File
3220 In the argument file,
3221 -cp "/lib/cool app/jars:\
3223 /lib/another app/jars"
3224 This is interpreted as:
3226 -cp /lib/cool app/jars:/lib/another app/jars
3228 Example of Line Continuation with Leading Spaces in an Argument File
3230 In the argument file,
3231 -cp "/lib/cool\
3233 \app/jars"
3234 This is interpreted as:
3236 -cp /lib/cool app/jars
3238 Examples of Using Single Argument File
3240 You can use a single argument file, such as myargumentfile in the fol‐
3241 lowing example, to hold all required java arguments:
3242 java @myargumentfile
3244 Examples of Using Argument Files with Paths
3246 You can include relative paths in argument files; however, they're rel‐
3247 ative to the current working directory and not to the paths of the ar‐
3248 gument files themselves. In the following example, path1/options and
3249 path2/options represent argument files with different paths. Any rela‐
3250 tive paths that they contain are relative to the current working direc‐
3251 tory and not to the argument files:
3252 java @path1/options @path2/classes
3254
3256 Overview
3257 There are occasions when having insight into the current state of the
3258 JVM code heap would be helpful to answer questions such as:
3259 • Why was the JIT turned off and then on again and again?
3261 • Where has all the code heap space gone?
3263 • Why is the method sweeper not working effectively?
3265 To provide this insight, a code heap state analytics feature has been
3267 implemented that enables on-the-fly analysis of the code heap. The an‐
3268 alytics process is divided into two parts. The first part examines the
3269 entire code heap and aggregates all information that is believed to be
3270 useful or important. The second part consists of several independent
3271 steps that print the collected information with an emphasis on differ‐
3272 ent aspects of the data. Data collection and printing are done on an
3273 "on request" basis.
3274 Syntax
3276 Requests for real-time, on-the-fly analysis can be issued with the fol‐
3277 lowing command:
3278 jcmd pid Compiler.CodeHeap_Analytics [function] [granularity]
3280 If you are only interested in how the code heap looks like after run‐
3282 ning a sample workload, you can use the command line option:
3283 -Xlog:codecache=Trace
3285 To see the code heap state when a "CodeCache full" condition exists,
3287 start the VM with the command line option:
3288 -Xlog:codecache=Debug
3290 See CodeHeap State Analytics (OpenJDK) [https://bugs.openjdk.org/se‐
3292 cure/attachment/75649/JVM_CodeHeap_StateAnalytics_V2.pdf] for a de‐
3293 tailed description of the code heap state analytics feature, the sup‐
3294 ported functions, and the granularity options.
3295
3297 You use the -Xlog option to configure or enable logging with the Java
3298 Virtual Machine (JVM) unified logging framework.
3299 Synopsis
3301 -Xlog[:[what][:[output][:[decorators][:output-options[,...]]]]]
3302 -Xlog:directive
3304 what Specifies a combination of tags and levels of the form
3306 tag1[+tag2...][*][=level][,...]. Unless the wildcard (*) is
3307 specified, only log messages tagged with exactly the tags speci‐
3308 fied are matched. See -Xlog Tags and Levels.
3309 output Sets the type of output. Omitting the output type defaults to
3311 stdout. See -Xlog Output.
3312 decorators
3314 Configures the output to use a custom set of decorators. Omit‐
3315 ting decorators defaults to uptime, level, and tags. See Deco‐
3316 rations.
3317 output-options
3319 Sets the -Xlog logging output options.
3320 directive
3322 A global option or subcommand: help, disable, async
3323 Description
3325 The Java Virtual Machine (JVM) unified logging framework provides a
3326 common logging system for all components of the JVM. GC logging for
3327 the JVM has been changed to use the new logging framework. The mapping
3328 of old GC flags to the corresponding new Xlog configuration is de‐
3329 scribed in Convert GC Logging Flags to Xlog. In addition, runtime log‐
3330 ging has also been changed to use the JVM unified logging framework.
3331 The mapping of legacy runtime logging flags to the corresponding new
3332 Xlog configuration is described in Convert Runtime Logging Flags to
3333 Xlog.
3334 The following provides quick reference to the -Xlog command and syntax
3336 for options:
3337 -Xlog Enables JVM logging on an info level.
3339 -Xlog:help
3341 Prints -Xlog usage syntax and available tags, levels, and deco‐
3342 rators along with example command lines with explanations.
3343 -Xlog:disable
3345 Turns off all logging and clears all configuration of the log‐
3346 ging framework including the default configuration for warnings
3347 and errors.
3348 -Xlog[:option]
3350 Applies multiple arguments in the order that they appear on the
3351 command line. Multiple -Xlog arguments for the same output
3352 override each other in their given order.
3353 The option is set as:
3355 [tag-selection][:[output][:[decorators][:output-op‐
3357 tions]]]
3358 Omitting the tag-selection defaults to a tag-set of all and a
3360 level of info.
3361 tag[+...] all
3363 The all tag is a meta tag consisting of all tag-sets available.
3365 The asterisk * in a tag set definition denotes a wildcard tag
3366 match. Matching with a wildcard selects all tag sets that con‐
3367 tain at least the specified tags. Without the wildcard, only
3368 exact matches of the specified tag sets are selected.
3369 output-options is
3371 filecount=file-count filesize=file size with optional K,
3373 M or G suffix foldmultilines=<true|false>
3374 When foldmultilines is true, a log event that consists of multi‐
3376 ple lines will be folded into a single line by replacing newline
3377 characters with the sequence '\' and 'n' in the output. Exist‐
3378 ing single backslash characters will also be replaced with a se‐
3379 quence of two backslashes so that the conversion can be re‐
3380 versed. This option is safe to use with UTF-8 character encod‐
3381 ings, but other encodings may not work. For example, it may in‐
3382 correctly convert multi-byte sequences in Shift JIS and BIG5.
3383 Default Configuration
3385 When the -Xlog option and nothing else is specified on the command
3386 line, the default configuration is used. The default configuration
3387 logs all messages with a level that matches either warning or error re‐
3388 gardless of what tags the message is associated with. The default con‐
3389 figuration is equivalent to entering the following on the command line:
3390 -Xlog:all=warning:stdout:uptime,level,tags
3392 Controlling Logging at Runtime
3394 Logging can also be controlled at run time through Diagnostic Commands
3395 (with the jcmd utility). Everything that can be specified on the com‐
3396 mand line can also be specified dynamically with the VM.log command.
3397 As the diagnostic commands are automatically exposed as MBeans, you can
3398 use JMX to change logging configuration at run time.
3399 -Xlog Tags and Levels
3401 Each log message has a level and a tag set associated with it. The
3402 level of the message corresponds to its details, and the tag set corre‐
3403 sponds to what the message contains or which JVM component it involves
3404 (such as, gc, jit, or os). Mapping GC flags to the Xlog configuration
3405 is described in Convert GC Logging Flags to Xlog. Mapping legacy run‐
3406 time logging flags to the corresponding Xlog configuration is described
3407 in Convert Runtime Logging Flags to Xlog.
3408 Available log levels:
3410 • off
3412 • trace
3414 • debug
3416 • info
3418 • warning
3420 • error
3422 Available log tags:
3424 There are literally dozens of log tags, which in the right combina‐
3426 tions, will enable a range of logging output. The full set of avail‐
3427 able log tags can be seen using -Xlog:help. Specifying all instead of
3428 a tag combination matches all tag combinations.
3429 -Xlog Output
3431 The -Xlog option supports the following types of outputs:
3432 • stdout --- Sends output to stdout
3434 • stderr --- Sends output to stderr
3436 • file=filename --- Sends output to text file(s).
3438 When using file=filename, specifying %p and/or %t in the file name ex‐
3440 pands to the JVM's PID and startup timestamp, respectively. You can
3441 also configure text files to handle file rotation based on file size
3442 and a number of files to rotate. For example, to rotate the log file
3443 every 10 MB and keep 5 files in rotation, specify the options file‐
3444 size=10M, filecount=5. The target size of the files isn't guaranteed
3445 to be exact, it's just an approximate value. Files are rotated by de‐
3446 fault with up to 5 rotated files of target size 20 MB, unless config‐
3447 ured otherwise. Specifying filecount=0 means that the log file
3448 shouldn't be rotated. There's a possibility of the pre-existing log
3449 file getting overwritten.
3450 -Xlog Output Mode
3452 By default logging messages are output synchronously - each log message
3453 is written to the designated output when the logging call is made. But
3454 you can instead use asynchronous logging mode by specifying:
3455 -Xlog:async
3457 Write all logging asynchronously.
3458 In asynchronous logging mode, log sites enqueue all logging messages to
3460 an intermediate buffer and a standalone thread is responsible for
3461 flushing them to the corresponding outputs. The intermediate buffer is
3462 bounded and on buffer exhaustion the enqueuing message is discarded.
3463 Log entry write operations are guaranteed non-blocking.
3464 The option -XX:AsyncLogBufferSize=N specifies the memory budget in
3466 bytes for the intermediate buffer. The default value should be big
3467 enough to cater for most cases. Users can provide a custom value to
3468 trade memory overhead for log accuracy if they need to.
3469 Decorations
3471 Logging messages are decorated with information about the message. You
3472 can configure each output to use a custom set of decorators. The order
3473 of the output is always the same as listed in the table. You can con‐
3474 figure the decorations to be used at run time. Decorations are
3475 prepended to the log message. For example:
3476 [6.567s][info][gc,old] Old collection complete
3478 Omitting decorators defaults to uptime, level, and tags. The none dec‐
3480 orator is special and is used to turn off all decorations.
3481 time (t), utctime (utc), uptime (u), timemillis (tm), uptimemillis
3483 (um), timenanos (tn), uptimenanos (un), hostname (hn), pid (p), tid
3484 (ti), level (l), tags (tg) decorators can also be specified as none for
3485 no decoration.
3486 Logging Messages Decorations
3488 Decorations Description
3490 ──────────────────────────────────────────────────────────────────────────
3491 time or t Current time and date in ISO-8601 format.
3492 utctime or utc Universal Time Coordinated or Coordinated Universal
3493 Time.
3494 uptime or u Time since the start of the JVM in seconds and mil‐
3495 liseconds. For example, 6.567s.
3496 timemillis or The same value as generated by System.currentTimeMil‐
3497 tm lis()
3498 uptimemillis or Milliseconds since the JVM started.
3499 um
3500 timenanos or tn The same value generated by System.nanoTime().
3501 uptimenanos or Nanoseconds since the JVM started.
3502 un
3503 hostname or hn The host name.
3504 pid or p The process identifier.
3505 tid or ti The thread identifier.
3506 level or l The level associated with the log message.
3507 tags or tg The tag-set associated with the log message.
3508 Convert GC Logging Flags to Xlog
3510 Legacy GC Logging Flags to Xlog Configuration Mapping
3511 Legacy Garbage Collec‐ Xlog Configura‐ Comment
3513 tion (GC) Flag tion
3514 ───────────────────────────────────────────────────────────────────────────────────────
3515 G1PrintHeapRegions -Xlog:gc+re‐ Not Applicable
3516 gion=trace
3517 GCLogFileSize No configuration Log rotation is handled by the
3518 available framework.
3519 NumberOfGCLogFiles Not Applicable Log rotation is handled by the
3520 framework.
3521 PrintAdaptiveSizePoli‐ -Xlog:gc+er‐ Use a level of debug for most
3522 cy go*=level of the information, or a level
3523 of trace for all of what was
3524 logged for PrintAdaptive‐
3525 SizePolicy.
3526 PrintGC -Xlog:gc Not Applicable
3527 PrintGCApplicationCon‐ -Xlog:safepoint Note that PrintGCApplication‐
3531 currentTime ConcurrentTime and PrintGCAp‐
3532 plicationStoppedTime are logged
3533 on the same tag and aren't sep‐
3534 arated in the new logging.
3535 PrintGCApplication‐ -Xlog:safepoint Note that PrintGCApplication‐
3536 StoppedTime ConcurrentTime and PrintGCAp‐
3537 plicationStoppedTime are logged
3538 on the same tag and not sepa‐
3539 rated in the new logging.
3540 PrintGCCause Not Applicable GC cause is now always logged.
3541 PrintGCDateStamps Not Applicable Date stamps are logged by the
3542 framework.
3543 PrintGCDetails -Xlog:gc* Not Applicable
3544 PrintGCID Not Applicable GC ID is now always logged.
3545 PrintGCTaskTimeStamps -Xlog:gc+task*=de‐ Not Applicable
3546 bug
3547 PrintGCTimeStamps Not Applicable Time stamps are logged by the
3548 framework.
3549 PrintHeapAtGC -Xlog:gc+heap=trace Not Applicable
3550 PrintReferenceGC -Xlog:gc+ref*=debug Note that in the old logging,
3551 PrintReferenceGC had an effect
3552 only if PrintGCDetails was also
3553 enabled.
3554 PrintStringDeduplica‐ `-Xlog:gc+stringdedup*=de‐ ` Not Applicable
3555 tionStatistics bug
3556 PrintTenuringDistribu‐ -Xlog:gc+age*=level Use a level of debug for the
3557 tion most relevant information, or a
3558 level of trace for all of what
3559 was logged for PrintTenur‐
3560 ingDistribution.
3561 UseGCLogFileRotation Not Applicable What was logged for PrintTenur‐
3562 ingDistribution.
3563 Convert Runtime Logging Flags to Xlog
3565 These legacy flags are no longer recognized and will cause an error if
3566 used directly. Use their unified logging equivalent instead.
3567 Runtime Logging Flags to Xlog Configuration Mapping
3569 Legacy Runtime Xlog Configuration Comment
3571 Flag
3572 ──────────────────────────────────────────────────────────────────────────────
3573 TraceExceptions -Xlog:exceptions=in‐ Not Applicable
3574 fo
3575 TraceClassLoad‐ -Xlog:class+load=lev‐ Use level=info for regular informa‐
3576 ing el tion, or level=debug for additional
3577 information. In Unified Logging
3578 syntax, -verbose:class equals
3579 -Xlog:class+load=info,class+un‐
3580 load=info.
3581 TraceClassLoad‐ -Xlog:class+pre‐ Not Applicable
3582 ingPreorder order=debug
3583 TraceClassUn‐ -Xlog:class+un‐ Use level=info for regular informa‐
3584 loading load=level tion, or level=trace for additional
3585 information. In Unified Logging
3586 syntax, -verbose:class equals
3587 -Xlog:class+load=info,class+un‐
3588 load=info.
3589 VerboseVerifi‐ -Xlog:verifica‐ Not Applicable
3590 cation tion=info
3591 TraceClassPaths -Xlog:class+path=info Not Applicable
3592 TraceClassReso‐ -Xlog:class+re‐ Not Applicable
3593 lution solve=debug
3594 TraceClassIni‐ -Xlog:class+init=info Not Applicable
3595 tialization
3596 TraceLoaderCon‐ -Xlog:class+load‐ Not Applicable
3597 straints er+constraints=info
3598 TraceClassLoad‐ -Xlog:class+load‐ Use level=debug for regular infor‐
3599 erData er+data=level mation or level=trace for addition‐
3600 al information.
3601 TraceSafepoint‐ -Xlog:safe‐ Not Applicable
3602 CleanupTime point+cleanup=info
3603 TraceSafepoint -Xlog:safepoint=debug Not Applicable
3604 TraceMonitorIn‐ -Xlog:monitorinfla‐ Not Applicable
3605 flation tion=debug
3606 TraceRede‐ -Xlog:rede‐ level=info, debug, and trace pro‐
3607 fineClasses fine+class*=level vide increasing amounts of informa‐
3608 tion.
3609 -Xlog Usage Examples
3611 The following are -Xlog examples.
3612 -Xlog Logs all messages by using the info level to stdout with uptime,
3614 levels, and tags decorations. This is equivalent to using:
3615 -Xlog:all=info:stdout:uptime,levels,tags
3617 -Xlog:gc
3619 Logs messages tagged with the gc tag using info level to stdout.
3620 The default configuration for all other messages at level warn‐
3621 ing is in effect.
3622 -Xlog:gc,safepoint
3624 Logs messages tagged either with the gc or safepoint tags, both
3625 using the info level, to stdout, with default decorations. Mes‐
3626 sages tagged with both gc and safepoint won't be logged.
3627 -Xlog:gc+ref=debug
3629 Logs messages tagged with both gc and ref tags, using the debug
3630 level to stdout, with default decorations. Messages tagged only
3631 with one of the two tags won't be logged.
3632 -Xlog:gc=debug:file=gc.txt:none
3634 Logs messages tagged with the gc tag using the debug level to a
3635 file called gc.txt with no decorations. The default configura‐
3636 tion for all other messages at level warning is still in effect.
3637 -Xlog:gc=trace:file=gctrace.txt:uptimemillis,pids:filecount=5,file‐
3639 size=1024
3640 Logs messages tagged with the gc tag using the trace level to a
3641 rotating file set with 5 files with size 1 MB with the base name
3642 gctrace.txt and uses decorations uptimemillis and pid.
3643 The default configuration for all other messages at level warn‐
3645 ing is still in effect.
3646 -Xlog:gc::uptime,tid
3648 Logs messages tagged with the gc tag using the default 'info'
3649 level to default the output stdout and uses decorations uptime
3650 and tid. The default configuration for all other messages at
3651 level warning is still in effect.
3652 -Xlog:gc*=info,safepoint*=off
3654 Logs messages tagged with at least gc using the info level, but
3655 turns off logging of messages tagged with safepoint. Messages
3656 tagged with both gc and safepoint won't be logged.
3657 -Xlog:disable -Xlog:safepoint=trace:safepointtrace.txt
3659 Turns off all logging, including warnings and errors, and then
3660 enables messages tagged with safepointusing tracelevel to the
3661 file safepointtrace.txt. The default configuration doesn't ap‐
3662 ply, because the command line started with -Xlog:disable.
3663 Complex -Xlog Usage Examples
3665 The following describes a few complex examples of using the -Xlog op‐
3666 tion.
3667 -Xlog:gc+class*=debug
3669 Logs messages tagged with at least gc and class tags using the
3670 debug level to stdout. The default configuration for all other
3671 messages at the level warning is still in effect
3672 -Xlog:gc+meta*=trace,class*=off:file=gcmetatrace.txt
3674 Logs messages tagged with at least the gc and meta tags using
3675 the trace level to the file metatrace.txt but turns off all mes‐
3676 sages tagged with class. Messages tagged with gc, meta, and
3677 class aren't be logged as class* is set to off. The default
3678 configuration for all other messages at level warning is in ef‐
3679 fect except for those that include class.
3680 -Xlog:gc+meta=trace
3682 Logs messages tagged with exactly the gc and meta tags using the
3683 trace level to stdout. The default configuration for all other
3684 messages at level warning is still be in effect.
3685 -Xlog:gc+class+heap*=debug,meta*=warning,threads*=off
3687 Logs messages tagged with at least gc, class, and heap tags us‐
3688 ing the trace level to stdout but only log messages tagged with
3689 meta with level. The default configuration for all other mes‐
3690 sages at the level warning is in effect except for those that
3691 include threads.
3692
3694 You use values provided to all Java Virtual Machine (JVM) command-line
3695 flags for validation and, if the input value is invalid or out-of-
3696 range, then an appropriate error message is displayed.
3697 Whether they're set ergonomically, in a command line, by an input tool,
3699 or through the APIs (for example, classes contained in the package ja‐
3700 va.lang.management) the values provided to all Java Virtual Machine
3701 (JVM) command-line flags are validated. Ergonomics are described in
3702 Java Platform, Standard Edition HotSpot Virtual Machine Garbage Collec‐
3703 tion Tuning Guide.
3704 Range and constraints are validated either when all flags have their
3706 values set during JVM initialization or a flag's value is changed dur‐
3707 ing runtime (for example using the jcmd tool). The JVM is terminated
3708 if a value violates either the range or constraint check and an appro‐
3709 priate error message is printed on the error stream.
3710 For example, if a flag violates a range or a constraint check, then the
3712 JVM exits with an error:
3713 java -XX:AllocatePrefetchStyle=5 -version
3715 intx AllocatePrefetchStyle=5 is outside the allowed range [ 0 ... 3 ]
3716 Improperly specified VM option 'AllocatePrefetchStyle=5'
3717 Error: Could not create the Java Virtual Machine.
3718 Error: A fatal exception has occurred. Program will exit.
3719 The flag -XX:+PrintFlagsRanges prints the range of all the flags. This
3721 flag allows automatic testing of the flags by the values provided by
3722 the ranges. For the flags that have the ranges specified, the type,
3723 name, and the actual range is printed in the output.
3724 For example,
3726 intx ThreadStackSize [ 0 ... 9007199254740987 ] {pd product}
3728 For the flags that don't have the range specified, the values aren't
3730 displayed in the print out. For example:
3731 size_t NewSize [ ... ] {product}
3733 This helps to identify the flags that need to be implemented. The au‐
3735 tomatic testing framework can skip those flags that don't have values
3736 and aren't implemented.
3737
3739 You use large pages, also known as huge pages, as memory pages that are
3740 significantly larger than the standard memory page size (which varies
3741 depending on the processor and operating system). Large pages optimize
3742 processor Translation-Lookaside Buffers.
3743 A Translation-Lookaside Buffer (TLB) is a page translation cache that
3745 holds the most-recently used virtual-to-physical address translations.
3746 A TLB is a scarce system resource. A TLB miss can be costly because
3747 the processor must then read from the hierarchical page table, which
3748 may require multiple memory accesses. By using a larger memory page
3749 size, a single TLB entry can represent a larger memory range. This re‐
3750 sults in less pressure on a TLB, and memory-intensive applications may
3751 have better performance.
3752 However, using large pages can negatively affect system performance.
3754 For example, when a large amount of memory is pinned by an application,
3755 it may create a shortage of regular memory and cause excessive paging
3756 in other applications and slow down the entire system. Also, a system
3757 that has been up for a long time could produce excessive fragmentation,
3758 which could make it impossible to reserve enough large page memory.
3759 When this happens, either the OS or JVM reverts to using regular pages.
3760 Linux and Windows support large pages.
3762 Large Pages Support for Linux
3764 Linux supports large pages since version 2.6. To check if your envi‐
3765 ronment supports large pages, try the following:
3766 # cat /proc/meminfo | grep Huge
3768 HugePages_Total: 0
3769 HugePages_Free: 0
3770 ...
3771 Hugepagesize: 2048 kB
3772 If the output contains items prefixed with "Huge", then your system
3774 supports large pages. The values may vary depending on environment.
3775 The Hugepagesize field shows the default large page size in your envi‐
3776 ronment, and the other fields show details for large pages of this
3777 size. Newer kernels have support for multiple large page sizes. To
3778 list the supported page sizes, run this:
3779 # ls /sys/kernel/mm/hugepages/
3781 hugepages-1048576kB hugepages-2048kB
3782 The above environment supports 2 MB and 1 GB large pages, but they need
3784 to be configured so that the JVM can use them. When using large pages
3785 and not enabling transparent huge pages (option -XX:+UseTransparen‐
3786 tHugePages), the number of large pages must be pre-allocated. For ex‐
3787 ample, to enable 8 GB of memory to be backed by 2 MB large pages, login
3788 as root and run:
3789 # echo 4096 > /sys/ker‐
3791 nel/mm/hugepages/hugepages-2048kB/nr_hugepages
3792 It is always recommended to check the value of nr_hugepages after the
3794 request to make sure the kernel was able to allocate the requested num‐
3795 ber of large pages.
3796 When using the option -XX:+UseSHM to enable large pages you also need
3798 to make sure the SHMMAX parameter is configured to allow large enough
3799 shared memory segments to be allocated. To allow a maximum shared seg‐
3800 ment of 8 GB, login as root and run:
3801 # echo 8589934592 > /proc/sys/kernel/shmmax
3803 In some environments this is not needed since the default value is
3805 large enough, but it is important to make sure the value is large
3806 enough to fit the amount of memory intended to be backed by large
3807 pages.
3808 Note: The values contained in /proc and /sys reset after you re‐
3810 boot your system, so may want to set them in an initialization
3811 script (for example, rc.local or sysctl.conf).
3812 If you configure the OS kernel parameters to enable use of large pages,
3814 the Java processes may allocate large pages for the Java heap as well
3815 as other internal areas, for example:
3816 • Code cache
3818 • Marking bitmaps
3820 Consequently, if you configure the nr_hugepages parameter to the size
3822 of the Java heap, then the JVM can still fail to allocate the heap us‐
3823 ing large pages because other areas such as the code cache might al‐
3824 ready have used some of the configured large pages.
3825 Large Pages Support for Windows
3827 To use large pages support on Windows, the administrator must first as‐
3828 sign additional privileges to the user who is running the application:
3829 1. Select Control Panel, Administrative Tools, and then Local Security
3831 Policy.
3832 2. Select Local Policies and then User Rights Assignment.
3834 3. Double-click Lock pages in memory, then add users and/or groups.
3836 4. Reboot your system.
3838 Note that these steps are required even if it's the administrator who's
3840 running the application, because administrators by default don't have
3841 the privilege to lock pages in memory.
3842
3844 Application Class Data Sharing (AppCDS) stores classes used by your ap‐
3845 plications in an archive file. Since these classes are stored in a
3846 format that can be loaded very quickly (compared to classes stored in a
3847 JAR file), AppCDS can improve the start-up time of your applications.
3848 In addition, AppCDS can reduce the runtime memory footprint by sharing
3849 parts of these classes across multiple processes.
3850 Classes in the CDS archive are stored in an optimized format that's
3852 about 2 to 5 times larger than classes stored in JAR files or the JDK
3853 runtime image. Therefore, it's a good idea to archive only those
3854 classes that are actually used by your application. These usually are
3855 just a small portion of all available classes. For example, your ap‐
3856 plication may use only a few APIs provided by a large library.
3857 Using CDS Archives
3859 By default, in most JDK distributions, unless -Xshare:off is specified,
3860 the JVM starts up with a default CDS archive, which is usually located
3861 in JAVA_HOME/lib/server/classes.jsa (or JAVA_HOME\bin\server\class‐
3862 es.jsa on Windows). This archive contains about 1300 core library
3863 classes that are used by most applications.
3864 To use CDS for the exact set of classes used by your application, you
3866 can use the -XX:SharedArchiveFile option, which has the general form:
3867 -XX:SharedArchiveFile=<static_archive>:<dynamic_archive>
3869 • The <static_archive> overrides the default CDS archive.
3871 • The <dynamic_archive> provides additional classes that can be loaded
3873 on top of those in the <static_archive>.
3874 • On Windows, the above path delimiter : should be replaced with ;
3876 (The names "static" and "dynamic" are used for historical reasons. The
3878 only significance is that the "static" archive is loaded first and the
3879 "dynamic" archive is loaded second).
3880 The JVM can use up to two archives. To use only a single <static_ar‐
3882 chive>, you can omit the <dynamic_archive> portion:
3883 -XX:SharedArchiveFile=<static_archive>
3885 For convenience, the <dynamic_archive> records the location of the
3887 <static_archive>. Therefore, you can omit the <static_archive> by say‐
3888 ing only:
3889 -XX:SharedArchiveFile=<dynamic_archive>
3891 Manually Creating CDS Archives
3893 CDS archives can be created manually using several methods:
3894 • -Xshare:dump
3896 • -XX:ArchiveClassesAtExit
3898 • jcmd VM.cds
3900 One common operation in all these methods is a "trial run", where you
3902 run the application once to determine the classes that should be stored
3903 in the archive.
3904 Creating a Static CDS Archive File with -Xshare:dump
3906 The following steps create a static CDS archive file that contains all
3907 the classes used by the test.Hello application.
3908 1. Create a list of all classes used by the test.Hello application.
3910 The following command creates a file named hello.classlist that con‐
3911 tains a list of all classes used by this application:
3912 java -Xshare:off -XX:DumpLoadedClassList=hello.classlist -cp
3914 hello.jar test.Hello
3915 The classpath specified by the -cp parameter must contain only JAR
3917 files.
3918 2. Create a static archive, named hello.jsa, that contains all the
3920 classes in hello.classlist:
3921 java -Xshare:dump -XX:SharedArchiveFile=hello.jsa
3923 -XX:SharedClassListFile=hello.classlist -cp hello.jar
3924 3. Run the application test.Hello with the archive hello.jsa:
3926 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hel‐
3928 lo
3929 4. Optional Verify that the test.Hello application is using the class
3931 contained in the hello.jsa shared archive:
3932 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar
3934 -Xlog:class+load test.Hello
3935 The output of this command should contain the following text:
3937 [info][class,load] test.Hello source: shared objects file
3939 Creating a Dynamic CDS Archive File with -XX:ArchiveClassesAtExit
3941 Advantages of dynamic CDS archives are:
3942 • They usually use less disk space, since they don't need to store the
3944 classes that are already in the static archive.
3945 • They are created with one fewer step than the comparable static ar‐
3947 chive.
3948 The following steps create a dynamic CDS archive file that contains the
3950 classes that are used by the test.Hello application, excluding those
3951 that are already in the default CDS archive.
3952 1. Create a dynamic CDS archive, named hello.jsa, that contains all the
3954 classes in hello.jar loaded by the application test.Hello:
3955 java -XX:ArchiveClassesAtExit=hello.jsa -cp hello.jar Hello
3957 2. Run the application test.Hello with the shared archive hello.jsa:
3959 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hel‐
3961 lo
3962 3. Optional Repeat step 4 of the previous section to verify that the
3964 test.Hello application is using the class contained in the hello.jsa
3965 shared archive.
3966 It's also possible to create a dynamic CDS archive with a non-default
3968 static CDS archive. E.g.,
3969 java -XX:SharedArchiveFile=base.jsa -XX:ArchiveClassesAtEx‐
3971 it=hello.jsa -cp hello.jar Hello
3972 To run the application using this dynamic CDS archive:
3974 java -XX:SharedArchiveFile=base.jsa:hello.jsa -cp hello.jar Hel‐
3976 lo
3977 (On Windows, the above path delimiter : should be replaced with ;)
3979 As mention above, the name of the static archive can be skipped:
3981 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar Hello
3983 Creating CDS Archive Files with jcmd
3985 The previous two sections require you to modify the application's
3986 start-up script in order to create a CDS archive. Sometimes this could
3987 be difficult, for example, if the application's class path is set up by
3988 complex routines.
3989 The jcmd VM.cds command provides a less intrusive way for creating a
3991 CDS archive by connecting to a running JVM process. You can create ei‐
3992 ther a static:
3993 jcmd <pid> VM.cds static_dump my_static_archive.jsa
3995 or a dynamic archive:
3997 jcmd <pid> VM.cds dynamic_dump my_dynamic_archive.jsa
3999 To use the resulting archive file in a subsequent run of the applica‐
4001 tion without modifying the application's start-up script, you can use
4002 the following technique:
4003 env JAVA_TOOL_OPTIONS=-XX:SharedArchiveFile=my_static_ar‐
4005 chive.jsa bash app_start.sh
4006 Note: to use jcmd <pid> VM.cds dynamic_dump, the JVM process identified
4008 by <pid> must be started with -XX:+RecordDynamicDumpInfo, which can al‐
4009 so be passed to the application start-up script with the same tech‐
4010 nique:
4011 env JAVA_TOOL_OPTIONS=-XX:+RecordDynamicDumpInfo bash
4013 app_start.sh
4014 Creating Dynamic CDS Archive File with -XX:+AutoCreateSharedArchive
4016 -XX:+AutoCreateSharedArchive is a more convenient way of creating/using
4017 CDS archives. Unlike the methods of manual CDS archive creation de‐
4018 scribed in the previous section, with -XX:+AutoCreateSharedArchive,
4019 it's no longer necessary to have a separate trial run. Instead, you
4020 can always run the application with the same command-line and enjoy the
4021 benefits of CDS automatically.
4022 java -XX:+AutoCreateSharedArchive -XX:SharedArchiveFile=hel‐
4024 lo.jsa -cp hello.jar Hello
4025 If the specified archive file exists and was created by the same ver‐
4027 sion of the JDK, then it will be loaded as a dynamic archive; otherwise
4028 it is ignored at VM startup.
4029 At VM exit, if the specified archive file does not exist, it will be
4031 created. If it exists but was created with a different (but post JDK
4032 19) version of the JDK, then it will be replaced. In both cases the
4033 archive will be ready to be loaded the next time the JVM is launched
4034 with the same command line.
4035 If the specified archive file exists but was created by a JDK version
4037 prior to JDK 19, then it will be ignored: neither loaded at startup,
4038 nor replaced at exit.
4039 Developers should note that the contents of the CDS archive file are
4041 specific to each build of the JDK. Therefore, if you switch to a dif‐
4042 ferent JDK build, -XX:+AutoCreateSharedArchive will automatically
4043 recreate the archive to match the JDK. If you intend to use this fea‐
4044 ture with an existing archive, you should make sure that the archive is
4045 created by at least version 19 of the JDK.
4046 Restrictions on Class Path and Module Path
4048 • Neither the class path (-classpath and -Xbootclasspath/a) nor the
4049 module path (--module-path) can contain non-empty directories.
4050 • Only modular JAR files are supported in --module-path. Exploded mod‐
4052 ules are not supported.
4053 • The class path used at archive creation time must be the same as (or
4055 a prefix of) the class path used at run time. (There's no such re‐
4056 quirement for the module path.)
4057 • The CDS archive cannot be loaded if any JAR files in the class path
4059 or module path are modified after the archive is generated.
4060 • If any of the VM options --upgrade-module-path, --patch-module or
4062 --limit-modules are specified, CDS is disabled. This means that the
4063 JVM will execute without loading any CDS archives. In addition, if
4064 you try to create a CDS archive with any of these 3 options speci‐
4065 fied, the JVM will report an error.
4066
4068 You can use the Java advanced runtime options to optimize the perfor‐
4069 mance of your applications.
4070 Tuning for Higher Throughput
4072 Use the following commands and advanced options to achieve higher
4073 throughput performance for your application:
4074 java -server -XX:+UseParallelGC -XX:+UseLargePages -Xmn10g
4076 -Xms26g -Xmx26g
4077 Tuning for Lower Response Time
4079 Use the following commands and advanced options to achieve lower re‐
4080 sponse times for your application:
4081 java -XX:+UseG1GC -XX:MaxGCPauseMillis=100
4083 Keeping the Java Heap Small and Reducing the Dynamic Footprint of Embedded
4085 Applications
4086 Use the following advanced runtime options to keep the Java heap small
4087 and reduce the dynamic footprint of embedded applications:
4088 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
4090 Note: The defaults for these two options are 70% and 40% respec‐
4092 tively. Because performance sacrifices can occur when using
4093 these small settings, you should optimize for a small footprint
4094 by reducing these settings as much as possible without introduc‐
4095 ing unacceptable performance degradation.
4096
4098 The following exit values are typically returned by the launcher when
4099 the launcher is called with the wrong arguments, serious errors, or ex‐
4100 ceptions thrown by the JVM. However, a Java application may choose to
4101 return any value by using the API call System.exit(exitValue). The
4102 values are:
4103 • 0: Successful completion
4105 • >0: An error occurred
4107JDK 21 2023 JAVA(1)