How we integrated Project Leyden into Quarkus

In the Java world, Ahead-of-Time (AOT) compilation rose to prominence with the introduction of GraalVM native image, which compiles Java applications into native executables.

It made a huge impact on the Java ecosystem and was a game changer for Java application startup performance:

But this comes with some drawbacks:

All in all, native image is an excellent option when startup time and footprint are the primary goals.

However, not all applications optimize for those dimensions. Some prioritize peak throughput, development velocity, debuggability, and compatibility with existing tooling. This is where Leyden becomes interesting, aiming to improve startup and footprint while staying closer to the traditional JVM model.

Project Leyden addresses the same fundamental problem as GraalVM native image, but takes a different approach:

The AOT cache is exactly that: a cache. If a class is not present in the cache, it is loaded and linked as usual.

Project Leyden reduces startup time by optimizing class loading and linking. It reduces warmup time by providing the JVM with profiling information, and will reduce it even further once compiled code itself is stored in the cache.

That said, Project Leyden is not magic either. In its current form:

Our take is that Project Leyden offers a compelling balance between performance and compatibility, at a very reasonable cost, and could become part of the default deployment workflow for many Java applications running on the JVM.

In OpenJDK 25, the following Project Leyden-related JEPs are available:

Together, these JEPs make Project Leyden fully usable starting with OpenJDK 25.

Additional JEPs are planned for OpenJDK 26 and beyond.

You may be used to seeing your Quarkus application packaged in a target/quarkus-app/ directory, but that wasn’t always the case. In the early days of Quarkus, we built a traditional runner JAR in target/, with dependencies placed in a lib/ directory, much like most other Java frameworks.

The current default packaging in Quarkus is called fast-jar. One of its primary goals is to optimize class loading.

We achieved this by introducing our own class loader, which, for example, keeps a package name → jar file mapping in memory. It also includes additional optimizations, such as maintaining a full directory index for specific locations like META-INF/services. These are just a few examples of what this packaging does, but they should give you some context.

This packaging performs very well in the traditional JVM world, but it doesn’t play nicely with Project Leyden.

Project Leyden takes a conservative approach: it only caches classes loaded by the standard JDK class loaders. In other words, no custom class loaders are allowed if you want to fully benefit from AOT caching.

To be precise: you cannot use custom class loaders to load classes if you want to fully benefit from AOT caching. However, you can still use a custom class loader for loading resources only.

This is why we developed a dedicated packaging for Project Leyden: aot-jar. It is automatically selected when AOT is enabled, making the transition completely transparent. It uses the same file layout as the fast-jar packaging.

In addition to delegating all class loading to the JDK class loader, this packaging has a few specific characteristics:

As this packaging format is new, we hope to gather feedback from real-world usage.

The AOT cache is only as good as the training data used to generate it. During the training phase, the JVM records which classes are loaded and linked, and collects method profiling data. The more representative the training workload, the more effective the resulting cache.

We wanted training to be as seamless as possible for Quarkus users. The natural fit was to leverage the existing integration test infrastructure: if you already have @QuarkusIntegrationTest tests, they can serve as the training workload.

When AOT training is enabled, the flow is as follows:

This is both practical and effective: you already write integration tests to validate your application, and they also happen to produce somewhat realistic training data for the AOT cache.

We wanted enabling Leyden in Quarkus to be a one-flag operation.

Setting quarkus.package.jar.aot.enabled=true is all it takes. Quarkus automatically switches to the aot-jar packaging and sets up the entire AOT pipeline.

With Maven, the full flow is a single command:

This builds the application, runs integration tests with AOT training, and generates the app.aot cache file in target/quarkus-app/.

Running the application with the AOT cache is just as straightforward:

We also integrated AOT with the container image extensions (Jib, Docker, and Podman). When building a container image with AOT enabled, Quarkus:

This end-to-end integration means going from source code to an AOT-optimized container image in a single command.

Startup time is greatly improved by Leyden, both for small and very large applications. While it doesn’t quite match the startup speed of a native executable, the results are still impressive.

Let’s pause for a moment. We were able to start a Quarkus REST application in the JVM in just 80 ms.

Granted, it’s a simple REST application with a single endpoint, but it still relies on a full-featured REST implementation. And it runs in the JVM.

For very large applications, the results are just as impressive: we were able to reduce startup time by 71%.

It won’t come as a surprise: you also need to include the AOT cache file in your container image, so Leyden increases the image size.

For a Quarkus REST application, the minimum is around 40 MB. The cache size grows as your application becomes larger.

On the other hand, going native significantly reduces the container image size, since you no longer need to include the full JVM.

In terms of RSS, Project Leyden does not significantly change the picture, while native executables offer a substantially lower memory footprint.

Reducing memory usage has not been a primary goal of Project Leyden so far, though this may evolve in the future.

At this point, you might be thinking: "Why not just go native for everything?". For all the reasons we’ve outlined, use native when it makes sense for you.

There’s also the question of throughput. We haven’t collected throughput numbers ourselves, as we didn’t have the proper setup, but some of our colleagues are running tests in an isolated environment, and recently published new benchmark results. Native executables usually result in lower throughput, at least with what is available as Open Source today in Mandrel and GraalVM CE.

This is where Project Leyden really shines: you get significantly faster startup times compared to a regular JVM, while still retaining all the benefits of running on the JVM.