How to Build a Native Executable With Quarkus and Mandrel
Build a Quarkus native executable with Mandrel or GraalVM: the native profile, build commands, what you gain and lose, build time and memory, and testing it.

A Quarkus native executable is a single binary that starts in tens of milliseconds and uses a fraction of the memory of the same application on a JVM. It is built ahead of time by GraalVM's native-image tool, or by Mandrel, Red Hat's distribution of the same technology built for Quarkus. The gains are real and so are the costs: long builds, a closed-world model that limits reflection, and peak throughput that can be lower than a warmed-up JVM. This post covers the build, what you gain and give up, how to test the binary, and how to decide whether native is right for a service. It uses Quarkus 3 and Mandrel built on JDK 25.
Build
With Mandrel or GraalVM installed locally and GRAALVM_HOME set:
./mvnw package -Dnative
./target/shop-1.0.0-SNAPSHOT-runnerThe native profile compiles the application and its dependencies, performs a reachability analysis from the entry points, and produces an executable for the build machine's operating system and architecture. A Linux binary built on a Mac does not run on Linux; build where you will run, or build in a container so that the result is a Linux binary on any host:
./mvnw package -Dnative -Dquarkus.native.container-build=trueThat option runs native-image inside a builder container, so you need no local GraalVM. The details, and the variants for different container engines, are in container builds without a local GraalVM. Plan for the cost: a native build takes one to several minutes for a small service, more for large ones, and needs several gigabytes of memory; a CI agent with 2 GB will be killed by the out-of-memory killer with a message that points nowhere useful. Give the builder at least 4 to 6 GB, and cap parallelism with -Dquarkus.native.native-image-xmx=6g if the machine is shared.
Mandrel is a downstream distribution of GraalVM's native-image tool built from the OpenJDK, tested for Quarkus. It does not include the Graal compiler as a JIT, the Truffle language runtime or the polyglot features, because Quarkus does not need them. Pick Mandrel for Quarkus builds and GraalVM when you need other GraalVM features. The project is at github.com/graalvm/mandrel.
What you gain
Startup time and resident memory. A native Quarkus REST service typically starts in a few tens of milliseconds and has a resident set measured in tens of megabytes, where the JVM version takes seconds and hundreds of megabytes. Those are order-of-magnitude figures, not a guarantee; measure your own application on your own hardware before promising a number to anyone. The reason is that the work moved to build time: class loading, annotation processing, dependency injection wiring and configuration parsing all happen during the build, which Quarkus does by design, as explained in build-time processing. The binary has no JIT compiler and no class metadata to load.
That matters most where the runtime is short-lived or the density high: serverless functions where cold start is the cost, CLI tools, scale-to-zero deployments, and clusters packing many small instances per node. It matters little for a long-running service on a large instance, where the JVM's startup is paid once. For the JVM's own startup improvements and their limits, see why Quarkus starts fast.
What you give up
Peak throughput. A JVM profiles a running application and recompiles hot code with optimisations based on what it observed; a native image is compiled once, with only static information. For CPU-heavy steady-state workloads the JVM with its C2 compiler is often faster after warm-up, and profile-guided optimisation for native images (a GraalVM Enterprise feature) narrows but does not close that gap in all cases. Garbage collection is simpler in native images, with a serial collector by default, which affects latency under heavy allocation.
Build time and feedback. Every change you want to test as a native binary costs minutes, so day-to-day development stays in JVM mode (quarkus:dev) and native builds run in CI.
Dynamic features. The closed-world assumption means the compiler must know at build time which classes are reachable. Reflection, resource loading, dynamic proxies and serialisation need to be declared. Quarkus extensions register what they know, and anything else becomes an error you meet at run time, covered in reflection and resource configuration and the build failure cases in native build failures. Libraries that rely on runtime classpath scanning or bytecode generation may not work at all. Debugging is harder as well: there is no JVM tooling such as JFR in the same form, no jcmd, and stack traces are fine while heap dumps and profilers differ.
Test the binary
Every one of those limits shows up only in the native binary. Tests that run on the JVM prove nothing about it. Quarkus provides @QuarkusIntegrationTest, which launches the built artifact (the native executable when you build with -Dnative) and runs the tests against it over HTTP:
@QuarkusIntegrationTest
class OrderResourceIT extends OrderResourceTest {
}Extending the @QuarkusTest class reuses its tests against the native binary. The pattern is a good one: write the tests once, run them in JVM mode on every commit and against the native executable in a CI stage. Run ./mvnw verify -Dnative to build and test in one go. Cover each serialisation path, each resource file read and each reflective feature at least once, because a missing registration is a run-time failure in exactly the code path nobody exercised.
Build the container image from the native binary with the minimal base image Quarkus suggests (quay.io/quarkus/quarkus-micro). The result is often under 100 MB and starts in milliseconds, and it has no JVM to patch, though you must rebuild it for each library security update, since the dependencies are compiled in.
Choosing
Choose native when startup or memory is what you are paying for: functions, scale-to-zero, many small instances, tools that run and exit. Stay on the JVM when the service is long-running and throughput-bound, when it relies on libraries that fight native image, or when your team's feedback loop matters more than the cold start. A middle path exists: JDK features such as class data sharing and ahead-of-time caching in recent releases reduce JVM startup, and for many services that is enough. Measure the specific numbers that matter to you, which are usually time to first request and memory per instance at your load.
Where this does not apply
For a Quarkus application that uses extensions without native support, or Hibernate features that need runtime bytecode generation, check the extension's native status first in its guide. The build guide is at quarkus.io/guides/building-native-image.


