Let’s talk about making Java applications faster and lighter. I want to explain a technology that changes how we run Java programs. Usually, Java code runs on the Java Virtual Machine, or JVM. This is powerful and flexible, but it can be slow to start and use more memory than we’d like. What if you could turn your Java application into a single, compact file that runs instantly, like a program written in C or Go? That’s what GraalVM Native Image does.

It transforms your Java application, compiled ahead of time into a native executable specific to your operating system. This file doesn’t need a JVM. It starts in milliseconds and uses less memory. This is a game-changer for cloud environments, tiny microservices, and serverless functions where resources are limited and billed by the second.

I remember the first time I used it. I had a small CLI tool. On the JVM, it took a second or two to become responsive. After building it as a native image, it ran almost before my finger left the enter key. The difference was startling. Let’s walk through how you can achieve this, from the basics to more advanced tuning.

The simplest way to begin is with the native-image command. You point it at your application’s JAR file. It analyzes your code, figures out every class and method your program actually uses, and then compiles all that down to machine code.

native-image -jar myapp.jar

After this runs, you’ll have a file simply named myapp (or myapp.exe on Windows). You can run it directly: ./myapp. That’s it. No java -jar command. This executable contains your application, essential parts of a runtime system (like a garbage collector), and the code needed to manage memory and threads. It’s a complete package.

However, this simple command can stumble. Java is dynamic. It often uses features where the program’s structure isn’t fully known until it’s actually running. The two most common troublemakers are reflection and resource loading. Reflection is when code inspects or modifies itself at runtime, like creating an instance of a class just by knowing its name as a string. Resource loading is accessing files bundled inside your JAR.

The native image builder, doing its analysis ahead of time, cannot always see these dynamic uses. If you try to use reflection on a class it didn’t see referenced directly in the code, that part will be missing from the final binary, and it will fail at runtime. You have to tell the builder about them explicitly. The best way to do this is to let the tool help you.

Run your application on the regular JVM with a special GraalVM agent. This agent watches what your code does and writes a configuration file for you.

java -agentlib:native-image-agent=config-output-dir=./config -jar myapp.jar

Then, exercise your application. Click through all the features, call all the APIs. The agent records every class used via reflection, every resource loaded, every JNI call. Afterwards, you’ll find JSON files in the ./config directory. You include these in your next native image build.

native-image -jar myapp.jar -H:ConfigurationFileDirectories=./config

The configuration looks like this JSON snippet. It explicitly lists classes for reflection and patterns for resources.

{
  "resources": {
    "includes": [
      {"pattern": ".*\\.properties$"},
      {"pattern": "META-INF/services/.*"}
    ]
  },
  "reflect": [
    {"name": "com.example.service.UserService"},
    {"name": "com.example.model.DataPoint", "methods": [{"name": "getId"}, {"name": "getValue"}]}
  ]
}

Doing this manually for every build is cumbersome. This is where build tools like Maven or Gradle shine. You can integrate the process seamlessly. For Maven, use the Native Build Tools plugin. It manages the agent run, the configuration, and the final compilation.

Add this plugin to your pom.xml. It creates a dedicated Maven profile for native compilation.

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>0.9.19</version>
    <executions>
        <execution>
            <goals>
                <goal>compile-no-fork</goal>
            </goals>
            <phase>package</phase>
        </execution>
    </executions>
    <configuration>
        <imageName>${project.name}</imageName>
        <mainClass>${project.mainClass}</mainClass>
        <buildArgs>
            <buildArg>--verbose</buildArg>
        </buildArgs>
    </configuration>
</plugin>

You run mvn -Pnative package. The plugin handles everything, producing your native executable in the target directory. It feels like magic, but it’s just good automation. I set this up once, and now my CI pipeline builds both a traditional JAR and a native binary with a single command.

Speaking of pipelines, let’s talk about containers. The combination of Native Image and Docker is incredibly powerful. You can create microscopic, secure, and fast container images. The strategy is a multi-stage Docker build. The first stage has the full GraalVM installation to compile the native binary. The second stage uses a minimal base image like alpine or even scratch, and only copies in that tiny binary.

Here’s a Dockerfile template I use often. It produces a final image that’s often under 50MB, sometimes even under 10MB.

# Build stage
FROM ghcr.io/graalvm/native-image:ol8-java17-22 AS builder
WORKDIR /build
COPY target/myapp-*.jar app.jar
RUN native-image --no-fallback -jar app.jar

# Run stage
FROM alpine:latest
RUN apk add --no-cache libstdc++
WORKDIR /app
COPY --from=builder /build/myapp .
USER nobody
ENTRYPOINT ["/app/myapp"]

The size difference is dramatic. A standard JVM-based Docker image can easily be 300-400MB. This native version is a fraction of that. It starts faster and has a much smaller attack surface, which is a major security benefit.

Now, you have a working native binary. But is it optimized? The basic compilation is good, but you can make it better with Profile-Guided Optimization, or PGO. The idea is simple: train your binary. First, you build a special instrumented version of your native executable.

native-image --pgo-instrument -jar myapp.jar

Run this instrumented binary under a realistic workload. Simulate typical user traffic or run your standard integration test suite. As it runs, it writes a file, default.iprof, capturing which parts of your code are executed most frequently—the “hot paths.”

./myapp run-my-tests
# or, for a server: ./myapp & then send it traffic with curl or a load tester.

Once you have this profile data, you use it to build the final, optimized binary. The compiler uses the profile to make smarter decisions, like inlining small, hot methods aggressively.

native-image --pgo=default.iprof -jar myapp.jar

The result is an executable that’s not just fast-starting, but also has better peak performance. It’s like giving the compiler a map of your application’s most traveled roads.

Memory management is another critical area. In a traditional JVM, you can adjust heap size and garbage collector settings with command-line arguments at launch. In a native executable, many of these choices are made at build time. You select your garbage collector during compilation.

native-image --gc=G1 -jar myapp.jar

Your main choices are the serial GC (default, good for smaller heaps), the G1 GC (better for larger heaps with more throughput), or the Epsilon GC. Epsilon is a special one—it only allocates memory and never collects garbage. It’s useful for ultra-short-lived applications where you know they will exit before running out of memory, or for performance testing. You can also set maximum heap size at build time.

native-image -R:MaxHeapSize=1G -jar myapp.jar

Remember, these are fixed in the binary. You can’t change them when you run ./myapp. This requires you to know your application’s needs upfront, which is part of the shift in thinking when moving to native images.

Let’s address more complex dynamic features. Suppose your code uses Java’s dynamic proxies or the Java Native Interface. These are inherently runtime-oriented and challenging for static analysis.

For dynamic proxies, you must declare the full list of interfaces that a proxy might implement. The build-time agent I mentioned earlier will usually catch these and add them to the reflection config. If you’re writing the config manually, it looks like this:

{
  "proxy": [
    {"interfaces": ["java.util.List", "java.util.RandomAccess"]}
  ]
}

For JNI, if you have native methods that call into C libraries, you must ensure those libraries are available in the target environment, just like with a regular JVM. The native image builder will link them. More importantly, any Java classes those native methods interact with must be registered for reflection. The agent is, again, your best friend for discovering these requirements.

Debugging a native executable is different from debugging Java bytecode. You can’t use your favorite Java debugger. Instead, you use system debuggers like GDB or LLDB. First, you need to include debug symbols in your binary.

native-image -g -jar app.jar

The -g flag tells the compiler to include information that maps machine code back to your original Java source lines. To debug, you start your native application and then attach GDB to its process ID.

./app &
APP_PID=$!
gdb --pid=$APP_PID

Inside GDB, you can set breakpoints, step through code, and inspect variables. The experience is more like debugging a C program than a Java one. It’s less interactive but absolutely essential for diagnosing crashes or strange behavior in production binaries. Getting comfortable with GDB’s basic commands is a worthwhile investment.

Binary size is a common concern. A “Hello World” Java native image might be around 20-30MB. That’s because it includes a whole runtime system. You can control this. Using the --no-fallback flag is crucial. If the build encounters something it can’t handle, it will fail instead of creating a binary that secretly includes a mini-JVM, which would be much larger.

For the smallest possible size on Linux, you can create a fully static binary. This means it doesn’t even depend on the standard system C library. It’s completely self-contained.

native-image --static --libc=musl -jar app.jar

This requires you to have the musl C library and static development tools installed on your build machine. The resulting binary can run on almost any Linux system, regardless of its installed libraries, and can be incredibly small.

Finally, how do you know your native binary works correctly? You test it. But you need to test the native binary itself, not just the Java code. Your regular unit tests run on the JVM. You need integration tests that start the actual native executable, send requests to it, and verify its responses.

The GraalVM community provides tools to help. For JUnit 5, you can use the @NativeImageTest annotation in a separate test source set. These tests will launch your native binary, run against it, and then shut it down.

import org.junit.jupiter.api.Test;
import org.graalvm.buildtools.test.junit.NativeImageTest;
import static io.restassured.RestAssured.given;

@NativeImageTest
public class NativeAppIT {
    @Test
    void testRootEndpoint() {
        given()
          .baseUri("http://localhost:8080")
        .when()
          .get("/")
        .then()
          .statusCode(200);
    }
}

This type of testing is slower than unit tests but gives you immense confidence. It catches issues specific to the native environment: missing reflection configs, resource problems, or differences in behavior between the JVM’s just-in-time compiler and the native image’s ahead-of-time compiler.

Adopting GraalVM Native Image requires a shift. You trade the dynamic flexibility of the JVM for predictable performance and minimal footprint. The build process is longer and requires more configuration. You must understand your application’s runtime behavior deeply.

But the rewards are substantial. Instant startup, reduced memory cost, and simpler deployment are compelling advantages, especially in modern cloud architectures. Start with a simple application, use the agent to generate configuration, integrate it into your build, and progress from there. The path from a dynamic Java application to a sleek, self-contained native binary is well-trodden and full of practical benefits.