Faster startup with the AOT cache

suggest change

Before a Java program runs its first line of main, the JVM does a lot of work: it finds classes in JAR files and in the JDK's module image, parses and verifies them, links them, runs static initializers and creates the lambda and string-concatenation classes the code needs. Then the code runs in the interpreter until the JIT compiler has seen enough of it to compile the hot parts. For a long-running server none of this matters much. For a command-line tool, a serverless function or a microservice that scales up and down, it is most of the run.

The AOT cache (ahead-of-time cache) saves that work. You do a training run: start the application once and let it do typical work. The JVM records what it loaded and linked and how the methods behaved, then writes it to a cache file. Later runs map the cache into memory and start with all of those classes already loaded and linked.

This is the first result of OpenJDK's Project Leyden. It arrived over three releases:

All of this is a standard product feature. There is nothing to enable and no preview flag. The output below is from JDK 25 on Windows, so Java 26 behaviour is described but not shown.

The application

The example is a small report generator packaged as a JAR. It parses XML, uses a record, regular expressions, streams with lambdas, java.time and String.format. That is ordinary code, but it pulls in a lot of JDK classes:

package app;

import java.io.StringReader;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.util.Comparator;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import javax.xml.parsers.DocumentBuilderFactory;
import org.w3c.dom.Element;
import org.xml.sax.InputSource;

public class Report {
    record Order(String customer, String date, double amount) {}

    static final String XML = """
        <orders>
          <order customer="alice" date="2026-10-01" amount="120.50"/>
          <order customer="bob"   date="2026-10-03" amount="80.00"/>
          <order customer="alice" date="2026-10-07" amount="42.25"/>
          <order customer="carol" date="2026-10-09" amount="310.00"/>
          <order customer="bob"   date="2026-10-12" amount="15.75"/>
        </orders>
        """;

    public static void main(String[] args) throws Exception {
        var doc = DocumentBuilderFactory.newInstance().newDocumentBuilder()
                .parse(new InputSource(new StringReader(XML)));
        var nodes = doc.getElementsByTagName("order");
        var orders = new java.util.ArrayList<Order>();
        for (int i = 0; i < nodes.getLength(); i++) {
            var e = (Element) nodes.item(i);
            orders.add(new Order(e.getAttribute("customer"), e.getAttribute("date"),
                    Double.parseDouble(e.getAttribute("amount"))));
        }

        Pattern name = Pattern.compile("^[a-z]+$");
        Map<String, Double> totals = orders.stream()
                .filter(o -> name.matcher(o.customer()).matches())
                .collect(Collectors.groupingBy(Order::customer, Collectors.summingDouble(Order::amount)));

        var fmt = DateTimeFormatter.ofPattern("EEEE, d MMMM yyyy", Locale.US);
        LocalDate last = orders.stream().map(o -> LocalDate.parse(o.date()))
                .max(Comparator.naturalOrder()).orElseThrow();

        List<String> lines = totals.entrySet().stream()
                .sorted(Map.Entry.<String, Double>comparingByValue().reversed())
                .map(en -> String.format(Locale.US, "%-6s %8.2f", en.getKey(), en.getValue()))
                .toList();
        lines.forEach(System.out::println);
        System.out.println("last order: " + fmt.format(last));
    }
}

Build it into an executable JAR (see Making an executable JAR from the command line) and run it:

> javac -d classes src/app/Report.java
> jar --create --file app.jar --main-class app.Report -C classes .
> java -jar app.jar
carol    310.00
alice    162.75
bob       95.75
last order: Monday, 12 October 2026

Creating the cache in one step (Java 25+)

Add -XX:AOTCacheOutput=<file> to the normal command line. That makes the run a training run:

> java -XX:AOTCacheOutput=app.aot -jar app.jar
carol    310.00
alice    162.75
bob       95.75
last order: Monday, 12 October 2026
Temporary AOTConfiguration recorded: app.aot.config
Launching child process C:\Program Files\Eclipse Adoptium\jdk-25.0.4.101-hotspot\bin\java to assemble AOT cache app.aot using configuration app.aot.config
Picked up JAVA_TOOL_OPTIONS: -Djava.class.path=app.jar -XX:AOTCacheOutput=app.aot -XX:AOTConfiguration=app.aot.config -XX:AOTMode=create
Reading AOTConfiguration app.aot.config and writing AOTCache app.aot
AOTCache creation is complete: app.aot 16056320 bytes
Removed temporary AOT configuration file app.aot.config

The application runs normally. When it exits, the JVM writes what it observed to a temporary AOT configuration file. It then starts a second JVM that reads the configuration and assembles the cache. The Picked up JAVA_TOOL_OPTIONS line comes from that child process, which gets its settings through the environment variable.

The cache is 16 MB. It contains the JDK classes the application used as well as its own, so it replaces the default CDS archive that ships with the JDK (more on CDS below). The whole training run took about 2.5 seconds here, against roughly 0.15 seconds for a normal run. You do it once, at build or deploy time, not on every start.

To use the cache, pass -XX:AOTCache with the same class path (here the same -jar app.jar):

> java -XX:AOTCache=app.aot -jar app.jar
carol    310.00
alice    162.75
bob       95.75
last order: Monday, 12 October 2026

The output is the same. Only the startup is faster.

Creating the cache in two steps (Java 24+)

-XX:AOTCacheOutput is a shortcut for two commands, which is all Java 24 has. The first records, the second creates:

> java -XX:AOTMode=record -XX:AOTConfiguration=app.aotconf -jar app.jar
carol    310.00
alice    162.75
bob       95.75
last order: Monday, 12 October 2026
 AOTConfiguration recorded: app.aotconf

> java -XX:AOTMode=create -XX:AOTConfiguration=app.aotconf -XX:AOTCache=app.aot -jar app.jar
Reading AOTConfiguration app.aotconf and writing AOTCache app.aot
AOTCache creation is complete: app.aot 16056320 bytes

The create step does not run the application. It only needs the same class path to find the classes again. The resulting cache is identical in size to the one from the one-step run.

The two-step form is still useful in Java 25. Recording can happen on one machine, for example in an integration test, and creating, which costs more CPU and memory, on another. You can also keep the configuration file and recreate the cache without training again.

Measured startup

How much does it help? I timed wall-clock runs of the whole process, from launch to exit, with a small Python script that runs each variant 20 times, interleaved, after one warm-up round:

import subprocess, sys, time, statistics
# usage: bench_aot.py N label="cmd args" ...
n = int(sys.argv[1])
cfgs = [a.split("=", 1) for a in sys.argv[2:]]
res = {l: [] for l, _ in cfgs}
for i in range(n + 1):
    for label, cmd in cfgs:
        t = time.perf_counter()
        subprocess.run(cmd.split(), stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=True)
        dt = (time.perf_counter() - t) * 1000
        if i > 0:  # first round is warm-up for the OS file cache
            res[label].append(dt)
for label, v in res.items():
    print(f"{label:<12} median {statistics.median(v):6.0f} ms   min {min(v):6.0f} ms   (n={len(v)})")

It compares four setups: class data sharing off (-Xshare:off), the JDK default, an AppCDS archive (explained below) and the AOT cache:

> python bench_aot.py 20 "share-off=java -Xshare:off -jar app.jar" "default=java -jar app.jar" "appcds=java -XX:SharedArchiveFile=app.jsa -jar app.jar" "aot=java -XX:AOTCache=app.aot -jar app.jar"
share-off    median    214 ms   min    177 ms   (n=20)
default      median    141 ms   min    111 ms   (n=20)
appcds       median    121 ms   min     92 ms   (n=20)
aot          median    104 ms   min     73 ms   (n=20)

The machine was busy with other work during these measurements (Windows reported 50-90% CPU load), so single numbers are noisy. Medians from three separate runs of the benchmark:

Setup Run 1 Run 2 Run 3
-Xshare:off 294 ms 297 ms 214 ms
default (JDK's CDS archive) 194 ms 182 ms 141 ms
AppCDS (-XX:SharedArchiveFile) 161 ms 170 ms 121 ms
AOT cache (-XX:AOTCache) 110 ms 133 ms 104 ms

The order was the same every time. The AOT cache cut startup by roughly a quarter to a half compared with the default, and it beat AppCDS. Treat the exact percentages as specific to this program and this machine. Measure your own application. The gain grows with the number of classes an application loads at startup, so frameworks with thousands of classes benefit more than this small example.

Source-file mode benefits too

Running source files without compiling compiles the program in memory with javac every time, and javac is itself a large Java program that has to start. Its classes come from the JDK, so they can be cached:

public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello from Java " + Runtime.version().feature());
    }
}
> java -XX:AOTCacheOutput=src.aot Hello.java
Hello from Java 25
...
AOTCache creation is complete: src.aot 24379392 bytes

> python bench_aot.py 10 "src=java Hello.java" "src-aot=java -XX:AOTCache=src.aot Hello.java"
src          median    498 ms   min    405 ms   (n=10)
src-aot      median    202 ms   min    181 ms   (n=10)

Two earlier runs of the same benchmark gave 702 vs 285 ms and, for a second file Other.java run with the cache trained on Hello.java, 998 vs 469 ms. Each time the cache more than halved the time. The classes of Hello itself are compiled in memory and can't be cached, but javac doesn't change, so one cache helps any small script.

What is in the cache

-Xlog:class+load prints where each class came from. Classes from a CDS archive or an AOT cache say source: shared objects file. Counting the lines for the report program:

> java -Xlog:class+load:file=cl.txt -jar app.jar
Setup Classes loaded From the archive
default 1377 1086
AppCDS 1364 1358
AOT cache 1432 1428

Without an application archive, 175 classes are read from the java.xml module, 71 more from java.base, and the application's own classes from app.jar. Lambda classes are spun up at run time:

[0.043s][info][class,load] app.Report source: file:/C:/.../aot/app.jar
[0.083s][info][class,load] app.Report$Order source: file:/C:/.../aot/app.jar
[0.085s][info][class,load] app.Report$$Lambda/0x000000001b040430 source: app.Report
[0.086s][info][class,load] app.Report$$Lambda/0x000000001b041800 source: app.Report
...

With the AOT cache everything comes from the cache, lambdas included, and all of it is there at the same instant, because the classes were linked ahead of time:

[0.045s][info][class,load] app.Report source: shared objects file
[0.045s][info][class,load] app.Report$$Lambda/0x800000034 source: shared objects file
[0.045s][info][class,load] app.Report$$Lambda/0x800000035 source: shared objects file
...
[0.045s][info][class,load] app.Report$Order source: shared objects file

In summary, the AOT cache stores:

Compiled machine code is not cached yet. Caching it is planned future work in Project Leyden.

Profiles help warm-up, not only startup

Method profiles matter for programs that run long enough for the JIT to kick in. This program counts words in generated text in a loop and reports how long the loop took:

package warm;

import java.util.HashMap;
import java.util.Map;

public class Warmup {
    // Some work the JIT has to optimize: word counting over generated text.
    static int work(int seed) {
        var sb = new StringBuilder();
        for (int i = 0; i < 20_000; i++) {
            sb.append("w").append((i * 31 + seed) % 500).append(' ');
        }
        Map<String, Integer> counts = new HashMap<>();
        for (String w : sb.toString().split(" ")) {
            counts.merge(w, 1, Integer::sum);
        }
        return counts.size();
    }

    public static void main(String[] args) {
        int rounds = Integer.parseInt(args[0]);
        long start = System.nanoTime();
        int sum = 0;
        for (int r = 0; r < rounds; r++) {
            sum += work(r);
        }
        long ms = (System.nanoTime() - start) / 1_000_000;
        System.out.println(rounds + " rounds in " + ms + " ms (" + sum + ")");
    }
}

The time is measured inside main, so class loading before main is not included. Train with 300 rounds, then compare 15 runs of each (median and minimum of the printed times, on the same busy machine):

> java -XX:AOTCacheOutput=warm.aot -jar warm.jar 300
300 rounds in 587 ms (150000)
...
default  30 rounds: median  125 ms  min   94 ms  (n=15)
aot      30 rounds: median   91 ms  min   68 ms  (n=15)
default  300 rounds: median  506 ms  min  322 ms  (n=15)
aot      300 rounds: median  422 ms  min  278 ms  (n=15)

The loop itself ran faster with the cache, because the JIT started from the recorded profile. The relative gain is largest early on and shrinks as the run gets longer, since after a while the JIT has collected a full profile either way.

Rules: when the cache can be used

The cache is a snapshot of one specific setup. The JVM checks at startup that the setup still matches:

Application arguments and system properties may differ between training and production.

What happens on a mismatch depends on -XX:AOTMode. The default is auto: the JVM ignores an unusable cache and starts normally, only slower. Sometimes it prints warnings and sometimes it prints nothing at all. Here the JAR is copied to another directory, which counts as a different class path, and no error appears:

> java -XX:AOTCache=app.aot -cp other/app.jar app.Report
carol    310.00
alice    162.75
bob       95.75
last order: Monday, 12 October 2026

-XX:AOTMode=on turns a silent fallback into an error, which is what you want in tests and in CI:

> java -XX:AOTCache=app.aot -XX:AOTMode=on -cp other/app.jar app.Report
[0.059s][warning][aot] The name of app classpath [1] does not match: expected 'app.jar', got 'other/app.jar'
[0.059s][error  ][aot] shared class paths mismatch (hint: enable -Xlog:class+path=info to diagnose the failure)
[0.059s][error  ][aot] An error has occurred while processing the AOT cache. Run with -Xlog:aot for details.
[0.059s][error  ][aot] unrecoverable error
Error occurred during initialization of VM
Unable to use AOT cache.

After touch app.jar:

> java -XX:AOTCache=app.aot -XX:AOTMode=on -jar app.jar
[0.032s][warning][aot] This file is not the one used while building the AOT cache: 'app.jar', timestamp has changed
[0.032s][error  ][aot] shared class paths mismatch (hint: enable -Xlog:class+path=info to diagnose the failure)
[0.032s][error  ][aot] An error has occurred while processing the AOT cache. Run with -Xlog:aot for details.
...

The cache was trained with the default G1 collector. Running with ZGC in JDK 25 fails, because ZGC doesn't use compressed object pointers:

> java -XX:+UseZGC -XX:AOTCache=app.aot -XX:AOTMode=on -jar app.jar
[0.033s][warning][aot] Unable to use AOT cache.
[                    ] The saved state of UseCompressedOops and UseCompressedClassPointers is different from runtime, CDS will be disabled.
[0.033s][error  ][aot] An error has occurred while processing the AOT cache. Run with -Xlog:aot for details.
[0.033s][error  ][aot] Loading static archive failed.
[0.033s][error  ][aot] Unable to map shared spaces
Error occurred during initialization of VM
Unable to use AOT cache.

The fix is to train with the same GC you run with. A cache created with -XX:+UseZGC -XX:AOTCacheOutput=zgc.aot loaded 1330 classes from the cache in a ZGC run.

If you train from a directory of classes, the JVM warns and leaves those classes out:

> java -XX:AOTCacheOutput=dir.aot -Xlog:aot=warning -cp classes app.Report
[0.515s][warning][aot] Skipping app/Report$Order: Unsupported location
[0.515s][warning][aot] Skipping app/Report: Unsupported location
...

-XX:AOTMode=off disables the cache even when -XX:AOTCache is given (in my test no class at all came from a shared archive then, not even from the JDK's default one). -Xlog:aot shows in detail what the JVM does with the cache.

The AOT options also can't be mixed with the older CDS options:

> java -XX:AOTCache=app.aot -Xshare:off -jar app.jar
Error occurred during initialization of VM
Option AOTCache cannot be used at the same time with -Xshare:on, -Xshare:auto, -Xshare:off, -Xshare:dump, DumpLoadedClassList, SharedClassListFile, or SharedArchiveFile

A good training run

The cache can only contain what the training run used. Classes the training run never loaded are loaded the usual way in production. Methods it never ran have no profile. So:

You don't have to change the launch script to use the cache. The JDK_JAVA_OPTIONS environment variable adds options to every java command:

> set JDK_JAVA_OPTIONS=-XX:AOTCache=app.aot -XX:AOTMode=on
> java -jar app.jar
NOTE: Picked up JDK_JAVA_OPTIONS: -XX:AOTCache=app.aot -XX:AOTMode=on
carol    310.00
...

On Linux and macOS use export JDK_JAVA_OPTIONS="...".

Background: CDS and AppCDS

The AOT cache grew out of Class Data Sharing (CDS), which has been in the JVM since Java 5:

The AppCDS archive in the benchmark was made like this:

> java -XX:ArchiveClassesAtExit=app.jsa -jar app.jar
> java -XX:SharedArchiveFile=app.jsa -jar app.jar

The .jsa file is 2.4 MB because it is layered on top of the JDK's default archive and holds only the classes that archive lacks. AppCDS stores parsed classes (lambda classes included) but doesn't link them ahead of time, doesn't cache heap objects and has no method profiles. The AOT cache does all of that, which explains the gap between the last two rows of the table.

The AOT cache uses the same file format and machinery as CDS, which is why it replaces the default archive, why it shows up as shared objects file in class-loading logs, and why it can't be combined with the -Xshare and SharedArchiveFile options. For new projects on Java 25 or later, use the AOT cache. Keep AppCDS for Java 17 and 21.

Summary

Task Command
Train and create (Java 25+) java -XX:AOTCacheOutput=app.aot -cp app.jar ...
Record (Java 24+) java -XX:AOTMode=record -XX:AOTConfiguration=app.aotconf -cp app.jar ...
Create (Java 24+) java -XX:AOTMode=create -XX:AOTConfiguration=app.aotconf -XX:AOTCache=app.aot -cp app.jar
Run with the cache java -XX:AOTCache=app.aot -cp app.jar ...
Fail if it can't be used add -XX:AOTMode=on
See what happens add -Xlog:aot or -Xlog:class+load

Related articles: JVM Flags for other -XX options, Choosing a garbage collector for the collector settings the cache depends on, Java Performance Tuning and Profiling for measuring where time goes before you decide that startup is the problem.

Feedback about page:

Feedback:
Optional: your email if you want me to get back to you:



Table Of Contents