rgoussu.dev
rgoussu@goussu: ~/library/java/jdk-and-tools
❯ ~/library/java/jdk-and-tools cat jpackage.md

jpackage — native installers and app images

# Packages a Java application with a bundled runtime into platform-native installers (deb, rpm, msi, exe, dmg, pkg) per JEP 392.

Conceptsaved 2026-08-09 #java#tooling#packaging#distribution

Overview

jpackage (standard since Java 16, JEP 392) turns a Java application plus a runtime into something end users can actually install: a native app image (a self-contained directory with a platform launcher) or a platform installer — deb/rpm on Linux, msi/exe on Windows, dmg/pkg on macOS. Users never install Java separately; the runtime travels inside the package. It replaced the old JavaFX javapackager.

Key points

  • Two-stage model: it first builds an app image (launcher + app/ with your jars + runtime/), then wraps it in an installer; --type app-image stops after stage one.
  • Runtime bundling: by default jpackage runs jlink itself (use --add-modules / --jlink-options to trim); or pass a pre-built image with --runtime-image for full control.
  • Platform-bound: it produces packages only for the OS it runs on and needs local packaging tools (WiX on Windows, dpkg/rpmbuild on Linux, Xcode command-line tools on macOS) — CI needs one build job per target platform.
  • Inputs: modular (--module) or classpath (--input dir + --main-jar/--main-class) applications both work.
  • Launcher polish: --icon (.ico/.icns/.png per platform), --java-options for fixed JVM flags, --arguments for defaults, --add-launcher for extra entry points, file associations via --file-associations.
  • Signing is on you: macOS Gatekeeper requires codesigning and notarisation (--mac-sign and related options help); Windows SmartScreen expects Authenticode signing of the msi/exe, which jpackage does not do — sign afterwards with signtool.
  • Not cross-platform, not an updater: no built-in update channel; pair with platform stores or an updater library if you need one.

Examples

jpackage --name MyApp --app-version 2.1.0 \
         --input build/libs --main-jar myapp.jar \
         --icon assets/myapp.icns \
         --java-options '-Xmx512m' \
         --type dmg

Related

  • JDK & tools — parent catalogue of the JDK toolchain.
  • jlink — builds the trimmed runtime jpackage embeds.
  • jmod — link-time format behind the bundled runtime's JDK modules.
  • jar tool — the application artefacts that go into --input.
  • Build ecosystem — how packaging fits the Maven/Gradle release pipeline.