This documentation is for an old GraalVM version. See the latest version.

Build Java Modules into a Native Executable

GraalVM Native Image supports the Java Platform Module System, introduced in Java 9, which means you can convert a modularized Java application into a native executable.

The native-image tool accepts the module-related arguments like --module (-m), --module-path (-p), --add-opens, --add-exports (same as for the java launcher). When such a module-related argument is used, the native-image tool itself is used as a module too.

In addition to supporting --add-reads and --add-modules, all module related options are considered prior to scanning the modulepath. This helps prevent class loading errors and allow for better module introspection at run time.

The command to build a native executable from a Java module is:

native-image [options] --module <module>[/<mainclass>] [options]

Run a Demo #

Follow the steps below to practice building a modular Java application into a native executable. For the demo, you will use a simple HelloWorld Java module gathered with Maven:

├── hello
│   └──
│       > package hello;
│       > 
│       > public class Main {
│       >     public static void main(String[] args) {
│       >         System.out.println("Hello from Java Module: "
│       >             + Main.class.getModule().getName());
│       >     }
│       > }
    > module HelloModule {
    >     exports hello;
    > }
  1. Download or clone the demos repository and navigate to the directory native-hello-module:

     git clone
     cd native-hello-module
  2. Compile and package the project with Maven:

     mvn package
  3. Test running it on GraalVM’s JDK:

     $JAVA_HOME/bin/java --module-path target/HelloModule-1.0-SNAPSHOT.jar --module HelloModule
  4. Now build this module into a native executable:

     $JAVA_HOME/bin/native-image --module-path target/HelloModule-1.0-SNAPSHOT.jar --module HelloModule

    It builds the modular Java application into a native executable called hellomodule in the project root directory that you can execute:


Connect with us