IMR6/libraries/linux/graalvm/lib/svm/skills/building-native-image/references/native-image-options.md

GraalVM Native Image CLI Options

Classpath and modules

If native-image can't find your classes:

native-image -cp <path1>:<path2> <class>

If using modules:

native-image -p <module-path> --add-modules <module-name> <class>

Build failures

If a class fails because it initializes at build time but must not:

native-image --initialize-at-run-time=com.example.LazyClass <class>

If a class must be initialized at build time:

native-image --initialize-at-build-time=com.example.EagerClass <class>

If a type must be fully defined at build time:

native-image --link-at-build-time <class>

If the build runs out of memory:

native-image -J-Xmx8g <class>

If you need to set a system property at build time:

native-image -Dkey=value <class>

If you need to pass a flag to the JVM running the builder:

native-image -J<flag> <class>

Missing reachability metadata

If you want exact error reporting for missing reflection/JNI/proxy/resource/serialization registrations (GraalVM JDK 23+):

native-image --exact-reachability-metadata <class>

If you want to scope exact metadata handling to specific classpath entries:

native-image --exact-reachability-metadata-path=<path> <class>

Output and binary type

If you want to rename the output binary:

native-image -o myapp <class>

If you want to build a shared library:

native-image --shared <class>

If you want a fully statically linked binary:

native-image --static --libc=musl <class>

If you want static linking but keep libc dynamic:

native-image --static-nolibc <class>

Performance and optimization

If you want fastest build time (dev iteration):

native-image -Ob <class>

If you want best runtime performance:

native-image -O3 <class>

If you want to optimize for binary size:

native-image -Os <class>

If you want to change the garbage collector:

native-image --gc=epsilon <class>  # no GC (throughput)
native-image --gc=serial <class>   # default

If you want to target the current machine's CPU features:

native-image -march=native <class>

If you need maximum compatibility across machines:

native-image -march=compatibility <class>

If you want to limit build parallelism:

native-image --parallelism=4 <class>

Debugging and diagnostics

If you want debug symbols in the binary:

native-image -g <class>

If you want verbose build output:

native-image --verbose <class>

If you want to inspect class initialization and substitutions:

native-image --diagnostics-mode <class>

If you want a detailed HTML build report:

native-image --emit build-report <class>
# or: --emit build-report=report.html

If you want to trace instantiation of a specific class:

native-image --trace-object-instantiation=com.example.MyClass <class>

Network support

If the binary needs JDK URL protocol handlers such as HTTP or HTTPS:

{
  "reflection": [
    {
      "type": "sun.net.www.protocol.http.Handler",
      "methods": [{"name": "<init>", "parameterTypes": []}]
    },
    {
      "type": "sun.net.www.protocol.https.Handler",
      "methods": [{"name": "<init>", "parameterTypes": []}]
    }
  ]
}

The --enable-http, --enable-https, and --enable-url-protocols options are deprecated. Use reachability metadata instead.

Monitoring and observability

If you need runtime monitoring (heap dumps, JFR, thread dumps):

native-image --enable-monitoring=heapdump,jfr,threaddump <class>

Security and compliance

If you need all security services (e.g. TLS/SSL):

native-image --enable-all-security-services <class>

Cross-compilation and platform

If you need to cross-compile for a different OS/arch:

native-image --target=linux-aarch64 <class>

If you need a custom C compiler:

native-image --native-compiler-path=/usr/bin/gcc <class>

Info and discovery

If you want to list available CPU features:

native-image --list-cpu-features

If you want to list observable modules:

native-image --list-modules

If you want to see the native toolchain and build settings:

native-image --native-image-info