jpackage: native Java app installers

jpackage turns a Java application into a native application for one operating system: an application image with its own Java runtime and a native launcher, and from that image an installer in the platform’s own format, .dmg or .pkg on macOS, .msi or .exe on Windows, .deb or .rpm on Linux. It builds the runtime with jlink, or copies one you made with --runtime-image, so users install an ordinary app and never install Java. The tool arrived with JDK 16 (JEP 392). Its documentation sets the main limit plainly: each format must be built on the platform it runs on, and there is no cross-platform packaging. Signing and Apple’s notarisation are platform steps that the JDK does not perform.

This lesson packages the shop’s billing app from the jlink lesson on a Mac with Apple silicon, with Eclipse Temurin 25.0.4.1, and shows every command with its output.

An app image for macOS

--type app-image builds the application bundle without an installer, which is the quickest way to check a package:

from session import run

# The billing app's two modules, packed as modular JARs, then turned into a macOS application bundle with jpackage;
# its top folders, its launcher run twice, and the version it records.
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 .
jpackage --type app-image --name Kirana --app-version 1.0.0 --vendor "Example Kirana Stores" --copyright "Example Kirana Stores" --module-path mods --module kirana.app/com.example.kirana.app.Main --dest dist
find dist/Kirana.app -maxdepth 3 -not -name "._*" | sort
dist/Kirana.app/Contents/MacOS/Kirana
dist/Kirana.app/Contents/MacOS/Kirana --xml
plutil -extract CFBundleShortVersionString raw dist/Kirana.app/Contents/Info.plist
java Size.java dist/Kirana.app
"""
)

# 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 .
$ jpackage --type app-image --name Kirana --app-version 1.0.0 --vendor "Example Kirana Stores" --copyright "Example Kirana Stores" --module-path mods --module kirana.app/com.example.kirana.app.Main --dest dist
Warning: No JDK Modules found
$ find dist/Kirana.app -maxdepth 3 -not -name "._*" | sort
dist/Kirana.app
dist/Kirana.app/Contents
dist/Kirana.app/Contents/_CodeSignature
dist/Kirana.app/Contents/_CodeSignature/CodeResources
dist/Kirana.app/Contents/app
dist/Kirana.app/Contents/app/.jpackage.xml
dist/Kirana.app/Contents/app/Kirana.cfg
dist/Kirana.app/Contents/Info.plist
dist/Kirana.app/Contents/MacOS
dist/Kirana.app/Contents/MacOS/Kirana
dist/Kirana.app/Contents/PkgInfo
dist/Kirana.app/Contents/Resources
dist/Kirana.app/Contents/Resources/Kirana.icns
dist/Kirana.app/Contents/runtime
dist/Kirana.app/Contents/runtime/Contents
$ dist/Kirana.app/Contents/MacOS/Kirana
3 lines, Sharma Kirana Store: ₹71,400.00
$ dist/Kirana.app/Contents/MacOS/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>
$ plutil -extract CFBundleShortVersionString raw dist/Kirana.app/Contents/Info.plist
1.0.0
$ java Size.java dist/Kirana.app
Kirana.app                     55.5 MiB

• The warning is about this JDK, not the app. jpackage looked for JMOD files and found none, then linked the runtime from the JDK’s own run-time image, as jlink does on this build; the bundle works.
• A macOS bundle has a fixed layout. Contents/MacOS/Kirana is the native launcher, Contents/app holds the launcher’s configuration, Contents/runtime holds the linked Java runtime, and Contents/Resources/Kirana.icns is the default icon, used because no --icon was given.
• The options went where users see them. --name named the bundle and the launcher, and --app-version 1.0.0 became the version in Info.plist, which the Finder’s information window shows.
• It is self-contained. The whole bundle measured 55.5 MiB, runtime included, and it runs on a Mac without Java.

The app image is also the input of every installer: build it, start it and test it, then wrap the same image with --app-image, so that the installer holds exactly what was tested. Its shape depends on the platform. The jpackage guide shows a folder with the launcher in bin on Linux, and a folder with an .exe launcher at its top on Windows, where macOS has the .app bundle above. When the runtime needs jlink options that jpackage does not pass, such as --include-locales, link it yourself and hand it over with --runtime-image.

The options you set first

Platform limits

The table follows the jpackage guide’s list of prerequisites. Every format is built on its own platform, so a product for three platforms needs three build machines or three CI runners. --type app-image works everywhere and makes the platform’s application image without an installer.

Check yourself

Inside the app image: launchers, configuration and runtime, measured Pro: opens with a Pro, Premium or Ultimate pass

A .dmg and a .pkg built, inspected, and refused by Gatekeeper Pro: opens with a Pro, Premium or Ultimate pass

Windows and Linux packages, a release checklist, and an exercise Pro: opens with a Pro, Premium or Ultimate pass

Key takeaways

• jpackage bundles an application with a linked Java runtime into an app image, then into a native installer.
• --type app-image is the quickest check: on macOS it made a 55.5 MiB bundle that runs without Java installed.
• --name, --app-version, --icon and --module or --main-jar set what users see and what starts.
• Every installer format is built on its own platform; signing and notarisation are separate platform steps.