Build Native Image Maven

Maven Native Image Build

Prerequisites

• Set JAVA_HOME to a GraalVM JDK installation so the plugin can find native-image.
• Do not require GRAALVM_HOME in the normal case. Only mention it if the user already relies on it or their environment needs an explicit override.
• Use Maven 3.6+.

Plugin Setup

Add the following to your pom.xml inside a native profile:

<profiles>
  <profile>
    <id>native</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.graalvm.buildtools</groupId>
          <artifactId>native-maven-plugin</artifactId>
          <version>0.11.1</version>
          <extensions>true</extensions>
          <executions>
            <execution>
              <id>build-native</id>
              <goals>
                <goal>compile-no-fork</goal>
              </goals>
              <phase>package</phase>
            </execution>
            <execution>
              <id>test-native</id>
              <goals>
                <goal>test</goal>
              </goals>
              <phase>test</phase>
            </execution>
          </executions>
          <configuration>
            <mainClass>org.example.Main</mainClass>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Build and Run

./mvnw -Pnative package                    # Build native image → target/<imageName>
./target/myapp                             # Run the native executable
./mvnw -Pnative test                       # Build and run JUnit tests as a native image
./mvnw -Pnative -DskipTests package        # Skip all tests
./mvnw -Pnative -DskipNativeTests package  # Run JVM tests only, skip native

Plugin Not Resolving or Activating

• "Could not resolve artifact" — Ensure mavenCentral() is in repositories and the version is correct.
• "Could not find goal 'compile-no-fork'" — Verify <extensions>true</extensions> is set on the plugin.
• Build runs without native compilation — Check you are activating the profile: ./mvnw -Pnative package.

Build or Runtime Failures

For class initialization errors, linking issues, memory problems, or unexpected runtime behavior, see references/maven-plugin-options.md.

Missing Reachability Metadata

When native-image reports missing reflection, resources, serialization, or JNI entries, see references/reachability-metadata.md.

Native Testing

For nativeTest failures or setting up native JUnit tests, see references/testing.md.

Reference Files