Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท Native Images and Dev Mode

Native Images with GraalVM and Mandrel

Compile a Quarkus app to a native executable with GraalVM or Mandrel: build commands, container builds, reflection and resource registration, limits and when to use it.

A normal Quarkus application is a jar that runs on the JVM. A native image is a different artifact: an operating-system executable, with no JVM inside it, produced by compiling your whole application ahead of time. It starts in a few dozen milliseconds and uses a fraction of the memory, which suits serverless functions, scale-to-zero platforms and dense container deployments.

Quarkus was designed for this from the start, because build-time processing already removed most of the reflection and dynamic loading that make native compilation hard. This lesson shows the commands, the compile model, the one big practical problem (reflection), and an honest list of trade-offs. A native compiler is not available on this site, so commands are read-only, and the TryIts illustrate the reachability idea and the reflection rule in plain Java.

Building a native executable

You need GraalVM or its Red Hat distribution Mandrel (which focuses on exactly the Quarkus use case). Instead of installing it, let Quarkus build inside a container that already has the right toolchain:

Terminal
./mvnw package -Dnative -Dquarkus.native.container-build=true
# or with the CLI
quarkus build --native

./target/shop-1.0.0-runner      # a Linux executable, no JVM needed

If the machine has GraalVM and GRAALVM_HOME set you can omit container-build. A container build is also the way to produce a Linux executable on Windows or macOS, which is what a Linux container image needs.

Native compilation is slow compared with a jar build: expect anywhere from about a minute for a small service to several minutes for a larger one, and several gigabytes of RAM while it runs. That is why teams develop on the JVM (dev mode) and build native only in CI.

A native Docker image is then tiny:

DOCKERFILE
FROM quay.io/quarkus/quarkus-micro-image:2.0
WORKDIR /work/
COPY target/*-runner /work/application
RUN chmod 775 /work
EXPOSE 8080
CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]

Quarkus project templates already contain src/main/docker/Dockerfile.native and Dockerfile.native-micro, so you rarely write this by hand. More on packaging in containers and Kubernetes.

How native compilation works

The compiler starts from your main method and from the entry points Quarkus registers, then performs points-to analysis: it follows every call, every field access and every class that is instantiated, and keeps only what is reachable. All reachable code is compiled to machine code. Everything else, including large parts of the JDK, is left out. Heap state created during image build (static initializers marked for build-time init) is written into the image, so the application starts with it already in memory.

JVM jar versus native executable

JVM jar JIT warms up, fast peak speed.
Native Starts in milliseconds, small RSS.
Size No JVM to ship.

Pick per workload, not by fashion.

1 / 2
Java Stand-in: reachability analysis on a call graph

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The reflection problem

Reflection looks things up by name at runtime: Class.forName("org.acme.Book"), a library that calls getters to turn objects into JSON, a framework that creates objects from a string. The analysis cannot see these names, so it may throw the target class away. The program works on the JVM and then fails in the native executable with ClassNotFoundException, a missing method, or an empty JSON object.

Quarkus extensions register what they need automatically. For your own classes that a library will use reflectively, tell the compiler yourself:

Java
import io.quarkus.runtime.annotations.RegisterForReflection;

@RegisterForReflection
public record BookDto(String title, int pages) { }
Java
@RegisterForReflection(targets = { ExternalVendorType.class })   // a class you cannot edit
public class ReflectionConfig { }

Return types of REST endpoints are detected for Jackson automatically with Quarkus REST, so DTOs often work without annotation, but a class used only inside a generic collection, or deserialized by your own ObjectMapper call, needs @RegisterForReflection.

Resources need the same care. A file loaded with getResourceAsStream must be declared:

PROPERTIES
quarkus.native.resources.includes=templates/*.txt,data/*.json
Java Stand-in: a closed world that only knows what you registered

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Other limits to know

  • No runtime class generation or loading. Bytecode generation with ASM or ByteBuddy at runtime, dynamic proxies for classes unknown at build time and URLClassLoader plugins do not work.
  • Static initializers run at build time by default for Quarkus code, which is fast but means a value computed in a static {} block (such as a timestamp or random seed) can be baked into the image. Compute such values at runtime.
  • Peak throughput. A JVM's JIT compiler optimizes hot paths using live profiles. A native image has no JIT, so a long-running, CPU-heavy service can be faster on the JVM, while short-lived and bursty services are better native. Profile-guided optimization (PGO) is available in Oracle GraalVM.
  • Debugging and tooling. You debug on the JVM, and use native only for the final artifact. Some agents, profilers and libraries do not support native.
  • Build cost. Minutes and gigabytes per build.

Testing the native executable

Unit tests run on the JVM, which does not prove the native image works. Quarkus therefore has @QuarkusIntegrationTest: it builds the packaged application (jar or native), starts it as a separate process, and runs your tests against the real HTTP port.

Java
@QuarkusIntegrationTest
class BookResourceIT extends BookResourceTest { }
Terminal
./mvnw verify -Dnative -Dquarkus.native.container-build=true

Extending the normal test class reuses all assertions, a common pattern covered in testing.

When should you choose native?

Choose native for Stay on the JVM for
Serverless functions and scale-to-zero Long-running, CPU-heavy services
Very dense deployments (many small pods) Heavy dynamic features and plugins
CLI tools and short jobs Teams without CI capacity for long builds
Fast autoscaling reaction Code with many reflection-based libraries

Many teams ship JVM jars by default and keep native as an option for specific services. Quarkus makes that a build flag, not a rewrite.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a Quarkus native executable?

    GraalVM or Mandrel compiles the application and the reachable JDK parts into machine code.
  2. 2. Why can reflection fail in a native image?

    The compiler keeps only reachable code, so reflective targets must be registered, for example with @RegisterForReflection.
  3. 3. Which option lets you build a Linux native executable without installing GraalVM?

    A container build runs the native compiler inside a container that already has the toolchain.
  4. 4. Which annotation runs tests against the packaged jar or native executable?

    It starts the built application as a separate process and tests it over HTTP.

Summary

  • A native image is an ahead-of-time compiled executable: tiny startup time and memory, no JIT.
  • Build with -Dnative and preferably a container build; expect slow builds.
  • Reachability analysis removes unused code, so reflection and resources must be registered (@RegisterForReflection, quarkus.native.resources.includes).
  • Verify native behavior with @QuarkusIntegrationTest.
  • Choose native for serverless and dense deployments; the JVM remains great for long-running heavy workloads.

Next: Testing with @QuarkusTest