.svg){kind=icon}
- GraalVM 25 (Latest)
- GraalVM for JDK 21
- GraalVM for JDK 17
- Archives
- Dev Build
- Getting Started with Native Image
- Guides
- Native Image Basics
- Build Overview
- Build Output
- Build Report
- Build Configuration
- Native Image Bundles
- Command-line Options
- Reachability Metadata
- Optimizations and Performance
- Debugging and Diagnostics
- Dynamic Features
- Interoperability with Native Code
- Web Image
- Workshops and Labs
Command-line Options
Options to configure Native Image are provided in the following categories:
- Build options: run
native-image --helpfor help on build options. - Extra build options: run
native-image --help-extrafor help on extra build options. - Expert build options: run
native-image --expert-optionsfor help on expert options. - Table of available options: run
native-image --print-options(table),native-image --print-options=md(Markdown), ornative-image --print-options=json(machine-readable JSON).
Depending on the GraalVM version, the options to the native-image builder may differ.
Native Image options can also be categorized as hosted or runtime options:
- Hosted options: to configure the build process and set default values for run-time behavior. These options use the prefix
-H:. For example,-H:MaxHeapSize=2gsets the default maximum heap size for the native executable. - Runtime options: to provide explicit values when building the native binary, using the prefix
-R:. At run time, the default prefix is-XX:(this is application-specific and not mandated by Native Image).
You can use -H: options at build time to configure both build-time behavior and run-time defaults. For most use cases, -H: options are sufficient and you typically do not need to distinguish between build-time and run-time configuration.
For more information describing how to define and use these options, read the com.oracle.svm.core.option package documentation.
Build Options
Run native-image --print-options to generate a table of the available options like this one below:
| Command | Type | Description | Default | Usage |
|———|——|————-|———|——-|
| --add-exports | String | value
List of Useful Options
There are some expert level options that a user may find useful or needed. For example, the option to dump graphs of the native-image builder, or to print various statistics during the build process.
Build Output and Build Report
Native Image provides an informative build output including various statistics during the build process.
The build output in a JSON-based, machine-readable format can be requested using the -H:BuildOutputJSONFile option, and later processed by a monitoring tool.
The JSON files validate against the JSON schema defined in build-output-schema-v0.9.4.json.
A comprehensive report with additional information can be requested using the --emit build-report option.
Note: The
--emit build-reportoption is not available in GraalVM Community Edition.
Graph Dumping
Native Image re-used the options for graph dumping, logging, counters, and everything else from the GraalVM debug environment.
These GraalVM options can be used both as hosted options (if you want to dump graphs of the native-image builder), and as runtime options (if you want to dump graphs during dynamic compilation at runtime).
The Graal compiler options that work as expected include Dump, DumpOnError, Log, MethodFilter, and the options to specify file names and ports for the dump handlers.
For example:
-H:Dump= -H:MethodFilter=ClassName.MethodName: dump the compiler graphs of thenative-imagebuilder.-XX:Dump= -XX:MethodFilter=ClassName.MethodName: dump the compile graphs at runtime.
Preserving Packages, Modules, or Classes
GraalVM 25 introduces the -H:Preserve option. This lets you instruct the native-image tool to keep entire packages, modules, or all classes on the classpath in the native executable, even when static analysis cannot discover them.
You can use -H:Preserve in the following ways:
-H:Preserve=all: preserves all elements from the entire JDK and classpath. This creates larger images but ensures all code is included, which can help resolve missing metadata issues.-H:Preserve=module=<module>: preserves all elements from a given module.-H:Preserve=module=ALL-UNNAMED: preserves all elements from the classpath (provided with-cp).-H:Preserve=package=<package>: preserves all elements from a given package. You can use*to include all subpackages, for example:-H:Preserve=package=com.my.pkg.*,package=com.another.pkg.*. Note that only the*wildcard is supported; other regex patterns are not allowed.-H:Preserve=path=<cp-entry>: preserves all elements from a given class-path entry- You can combine any of the previous uses by separating them with a comma (
,). For example:-H:Preserve=path=<cp-entry>,module=<module>,module=<module2>,package=<package>
You must explicitly configure multi-interface proxy classes, arrays of dimension 3 and higher, and .class files as resources in the native image. Tooling-related Java modules are not included by default with -H:Preserve=all and must be added with -H:Preserve=module=<module> if needed.
If you get errors related to --initialize-at-build-time, follow the suggestions in the error messages.
Note: Using
-H:Preserve=allrequires significant memory and will result in much larger native images. Use the-Osflag to reduce image size. For more information, see Optimizations and Performance.
For a practical demonstration, see the preserve-package demo.
Memory Requirements
Native Image compilation is memory-intensive, particularly when building large projects or when using -H:Preserve=all or --pgo-instrument.
If you encounter OutOfMemoryError: Java heap space you can:
- use the
-Osflag to reduce image size. For more information, see Optimizations and Performance - use more specific preservation options like
-H:Preserve=package=<package>instead of-H:Preserve=all - use more RAM by increasing the heap size with
-J-Xmx<n>gwhere<n>varies based on your machine’s available memory and build requirements
System Properties
You can define system properties at image build time using the -D<system.property>=<value> option syntax.
It sets a system property for the native-image tool, but the property will not be included in the generated executable.
However, JDK system properties are included in generated executables and are visible at runtime.
For example:
-D<system.property>=<value>will only be visible at build time. If this system property is accessed in the native executable, it will returnnull.-Djava.version=25will be visible at both build time and in the native executable because the value is copied into the binary by default.
The following system properties are automatically copied into the generated executable:
| Name | Description |
|---|---|
| file.separator | File separator |
| file.encoding | Character encoding for the default locale |
| java.version | Java Runtime Environment version |
| java.version.date | General-availability (GA) date of the release |
| java.class.version | Java class format version number |
| java.runtime.version | Java Runtime Environment version |
| java.specification.name | Java Runtime Environment specification name |
| java.specification.vendor | Java Runtime Environment specification vendor |
| java.specification.version | Java Virtual Machine specification version |
| java.vm.specification.name | Java Virtual Machine specification name |
| java.vm.specification.vendor | Java Virtual Machine implementation vendor |
| java.vm.specification.version | Java Virtual Machine specification version |
| line.separator | Line separator |
| native.encoding | Specifies the host environment’s character encoding |
| org.graalvm.nativeimage.kind | Specifies if the image is built as a shared library or executable |
| path.separator | Path separator |
| stdin.encoding | Specifies the encoding for System.in |
| stdout.encoding | Specifies the encoding for System.out and System.err |
| sun.jnu.encoding | Specifies encoding when parsing values passed via the commandline |