jlink: custom Java runtime images

jlink builds a runtime image: a folder with a java command and only the modules a program needs, instead of the whole JDK. You give it the program’s modules with --module-path, name the root modules with --add-modules, and it copies those modules and every module they require into the folder named by --output. jdeps --print-module-deps lists the JDK modules a program uses, which is the list jlink needs. The image runs on a computer without any JDK, so a program can ship with exactly the Java it was tested on, and a container or installer gets smaller. jlink arrived with Java 9 (JEP 282). The JDK used here, Eclipse Temurin 25.0.4.1 for macOS on Apple silicon, ships without JMOD files, so its jlink copies modules out of the JDK’s own run-time image, a capability that JEP 493 added and that each JDK build may enable or not.

Find the modules with jdeps

The program is the shop’s billing app from the module lesson, kirana.app and kirana.bill, with one new feature: --xml exports the bill as XML for the accountant, with the javax.xml.stream API of the java.xml module.

/** The shop's program: it prints a bill, or exports it as XML for the accountant. */
module kirana.app {
    requires kirana.bill;
    requires java.xml;
}

package com.example.kirana.app;

import com.example.kirana.bill.Bill;
import java.io.StringWriter;
import javax.xml.stream.XMLOutputFactory;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamWriter;

/** Prints the bill; --xml prints it as XML; --split N divides the total between N people. */
public class Main {
    public static void main(String[] args) throws XMLStreamException {
        Bill bill = new Bill("Sharma Kirana Store")
                .add("Basmati rice, 25 kg", 12, 2_450_00)
                .add("Toor dal, 30 kg", 4, 4_875_00)
                .add("Sugar, 50 kg", 10, 2_250_00);
        String option = args.length > 0 ? args[0] : "";
        switch (option) {
            case "--xml" -> System.out.println(xml(bill));
            case "--split" -> System.out.println("Each pays " + bill.totalPaise() / Integer.parseInt(args[1]) + " paise");
            default -> System.out.println(bill.lines().size() + " lines, " + bill.total());
        }
    }

    static String xml(Bill bill) throws XMLStreamException {
        StringWriter out = new StringWriter();
        XMLStreamWriter xml = XMLOutputFactory.newFactory().createXMLStreamWriter(out);
        xml.writeStartElement("bill");
        for (Bill.Line line : bill.lines()) {
            xml.writeStartElement("line");
            xml.writeAttribute("quantity", Integer.toString(line.quantity()));
            xml.writeAttribute("paise", Long.toString(line.paise()));
            xml.writeCharacters(line.item());
            xml.writeEndElement();
        }
        xml.writeEndElement();
        xml.close();
        return out.toString();
    }
}

from session import run

# The two modules are compiled and packed as modular JARs, then jdeps lists the modules the application needs, and
# jlink says how this JDK links.
run(
    """
javac -d out/kirana.bill $(find bill/src -name "*.java")
javac -d out/kirana.app --module-path out $(find app/src -name "*.java")
jar --create --file mods/kirana.bill.jar -C out/kirana.bill .
jar --create --file mods/kirana.app.jar --main-class com.example.kirana.app.Main -C out/kirana.app .
jdeps --module-path mods --print-module-deps --module kirana.app
jdeps -summary --module-path mods --module kirana.app
jlink --help | tail -n 2
"""
)

# openjdk version "25.0.4.1" LTS
$ javac -d out/kirana.bill $(find bill/src -name "*.java")
$ javac -d out/kirana.app --module-path out $(find app/src -name "*.java")
$ jar --create --file mods/kirana.bill.jar -C out/kirana.bill .
$ jar --create --file mods/kirana.app.jar --main-class com.example.kirana.app.Main -C out/kirana.app .
$ jdeps --module-path mods --print-module-deps --module kirana.app
java.base,java.xml,kirana.bill
$ jdeps -summary --module-path mods --module kirana.app
kirana.app -> java.base
kirana.app -> java.xml
kirana.app -> kirana.bill
$ jlink --help | tail -n 2
Capabilities:
      Linking from run-time image enabled

• jdeps reads the class files. It found java.xml because Main uses XMLStreamWriter, and kirana.bill because the declaration requires it; -summary shows the same edges one per line.
• The list is the input for jlink. For modular code, --add-modules kirana.app is enough, because jlink follows the requires directives itself; for a plain JAR, the list goes straight into --add-modules.
• This jlink links from the run-time image. Its help ends with the capability line that JEP 493 describes. A JDK that does have a jmods folder uses those files instead, and its help says “disabled” there.

jdeps has one blind spot to keep in mind from the start: it reports what the class files name, so a module that code only finds at run time, such as a provider of locale data, is missing from its list even when the program needs it.

Link an image and run it

from session import run

# A runtime image of the application and the JDK modules it needs, with a launcher; then what is in it, and how big
# it is next to the whole JDK.
run(
    """
javac -d out/kirana.bill $(find bill/src -name "*.java")
javac -d out/kirana.app --module-path out $(find app/src -name "*.java")
jar --create --file mods/kirana.bill.jar -C out/kirana.bill .
jar --create --file mods/kirana.app.jar --main-class com.example.kirana.app.Main -C out/kirana.app .
jlink --module-path mods --add-modules kirana.app --launcher kirana=kirana.app --output image
image/bin/java --list-modules
image/bin/kirana
image/bin/kirana --xml
ls image image/bin
cat image/release
java Size.java "$JAVA_HOME" image
"""
)

# openjdk version "25.0.4.1" LTS
$ javac -d out/kirana.bill $(find bill/src -name "*.java")
$ javac -d out/kirana.app --module-path out $(find app/src -name "*.java")
$ jar --create --file mods/kirana.bill.jar -C out/kirana.bill .
$ jar --create --file mods/kirana.app.jar --main-class com.example.kirana.app.Main -C out/kirana.app .
$ jlink --module-path mods --add-modules kirana.app --launcher kirana=kirana.app --output image
$ image/bin/java --list-modules
java.base@25.0.4.1
java.xml@25.0.4.1
kirana.app
kirana.bill
$ image/bin/kirana
3 lines, Sharma Kirana Store: ₹71,400.00
$ image/bin/kirana --xml
<bill><line quantity="12" paise="245000">Basmati rice, 25 kg</line><line quantity="4" paise="487500">Toor dal, 30 kg</line><line quantity="10" paise="225000">Sugar, 50 kg</line></bill>
$ ls image image/bin
image:
bin
conf
include
legal
lib
man
release

image/bin:
java
keytool
kirana
$ cat image/release
JAVA_VERSION="25.0.4.1"
MODULES="java.base java.xml kirana.bill kirana.app"
$ java Size.java "$JAVA_HOME" image
temurin-25.0.4+101.0.LTS      293.3 MiB
image                          61.2 MiB

• Four modules, no more. --list-modules and the release file both name java.base, java.xml and the two modules of the app: everything else of the JDK’s 69 modules stayed out.
• A launcher for the app. --launcher kirana=kirana.app wrote bin/kirana, which starts the main class that the modular JAR records, so users of the image never type a module path.
• About a fifth of the JDK. On this build, the image measured 61.2 MiB and the whole JDK 293.3 MiB, by the sizes of their files.

A program that is not modular uses an image the same way: link the JDK modules from jdeps’ list, then start the program with the image’s own java, as image/bin/java -jar app.jar. The image is not a JDK: it has no javac and no jlink, only what the four modules contain. The jlink documentation adds a reminder that matters in production: developers are responsible for updating their custom runtime images, so every security update of the JDK means linking the image again.

Options you will use

Check yourself

What each jlink option saves and costs, measured Pro: opens with a Pro, Premium or Ultimate pass

Modules jdeps cannot see: locale data and service providers, reproduced Pro: opens with a Pro, Premium or Ultimate pass

Linking without JMOD files: the limits, and the smallest-image exercise Pro: opens with a Pro, Premium or Ultimate pass

Key takeaways

• jlink copies a set of modules, and everything they require, into a runtime image that runs without a JDK.
• jdeps --print-module-deps lists the JDK modules a program refers to; jlink takes that list.
• The lesson’s image measured 61.2 MiB against 293.3 MiB for the whole JDK.
• An image is not a JDK, and it needs linking again for every JDK security update.