JPACKAGE(1)

🌈 jpackage(1) 🌈

okay bestie, welcome to jpackage(1) — she lives in the JDK Commands section of the manual and she is, like, the main character of getting your Java app out into the world. buckle up 🎀

---

✨ NAME ✨

jpackage — tool for packaging self-contained Java applications. that's her whole thing. no cap.

---

🦋 SYNOPSIS 🦋

jpackage [options]

• options — command-line options, separated by spaces. (the full list is in jpackage Options below, keep scrolling, it's a lot 😭)

---

💖 DESCRIPTION 💖

so here's the vibe: the jpackage tool takes a Java application and a Java run-time image as input, and produces a Java application image that includes all the necessary dependencies. everything's in there. self-contained. iconic. 💅

it can also produce a native package in a platform-specific format — think an exe on Windows, or a dmg on macOS. slay.

⚠️ but listen: each format must be built on the platform it runs on. there is no cross-platform support. you can't make a Windows exe from your Mac, that's not a thing, don't try it 🙈

and the tool has options that let packaged applications be customized in various ways. a lot of options, actually. brace yourself 🫶

---

👑 JPACKAGE OPTIONS 👑

💅 Generic Options 💅

• @filename — read options from a file. yes, a whole file of options. this option can be used multiple times. 📄
• --type or -t type — the type of package to create.

Valid values are: {"app-image", "exe", "msi", "rpm", "deb", "pkg", "dmg"}

if you don't specify this option, a platform dependent default type will be created. she'll pick for you ✨

• --app-version version — version of the application and/or package.
• --copyright copyright — copyright for the application.
• --description description — description of the application.
• --help or -h — print the usage text, with a list and description of each valid option for the current platform, to the output stream, and exit. very "lemme show you around first" of her 🫶
• --icon path — path of the icon of the application package.

(absolute path or relative to the current directory)

• --name or -n name — name of the application and/or package.
• --dest or -d destination — path where the generated output file is placed.

(absolute path or relative to the current directory)

defaults to the current working directory. 📁

• --resource-dir path — path to override jpackage resources.

(absolute path or relative to the current directory)

icons, template files, and other resources of jpackage can be over-ridden by adding replacement resources to this directory. swappable assets, we love to see it 💅

• --temp directory — path of a new or empty directory used to create temporary files.

(absolute path or relative to the current directory)

⚠️ if specified, the temp dir will not be removed upon the task completion and must be removed manually. you've been warned, bestie — that's on you now 😭

if not specified, a temporary directory will be created and removed upon the task completion. clean girl behaviour ✨

• --vendor vendor — vendor of the application.
• --verbose <[-]key(,[-]key)*> — configures verbose output. enables and/or disables log message categories using zero or more of the keys described below, separated by commas. the key all enables or disables all categories (respectively); other keys enable the corresponding category, or disable it if preceded by a hyphen (-).

supported values for key are:

• all: enables console output and routing of all message categories to the logging framework through the System.Logger API. equivalent to console,log.
• console: enables console output of all message categories. equivalent to all,-log.
• errors: enables output of fatal errors. if the key is specified without the trace key, error messages will be written to the console without the corresponding exception stacktraces. if the key is specified with the trace key, error messages will be written to the console with the corresponding exception stacktraces.
• progress: enables output of progress messages.
• resources: enables output of messages about the use of the configurable resources.
• summary: enables output of the bundle properties and the versions of the tools being used.
• tools: enables output of commands being executed. if the key is specified without the trace key, the jpackage will print the command lines without the output produced by executing these command lines. only command lines that are relevant to package customization will be written to the console. if the key is specified with the trace key, the jpackage will print all command lines and their output.
• trace: enables output of stack traces of suppressed exceptions and details of the jpackage execution. when combined with other keys, it enables additional information in messages from the corresponding message categories, as described above.
• warning: enables output of warnings.
• log: enables routing of all message categories to the logging framework through the System.Logger API. the logger name will be "jdk.jpackage".

if the option is specified without the value, it is equivalent to:

--verbose console,-trace

if the option is not specified, it is equivalent to:

--verbose errors,warnings

sample usage:

suppress all console output, enable logging via the System.Logger API:

--verbose log

enable all message categories in the console:

--verbose console

enable all message categories, but "trace" and "tools" in the console:

--verbose console,-trace,-tools

enable "trace" and "tools" message categories in the console:

--verbose trace,tools

enable "trace" and "tools" message categories in the console and enable logging via the System.Logger API:

--verbose log,trace,tools

🔥 like, the control you have here? unmatched.

• --version — print the product version to the output stream and exit. quick little flex, then she's out 💨

---

🧚 Options for creating the runtime image 🧚

• --add-modules module-name [,module-name...] — a comma (",") separated list of modules to add.

this module list, along with the main module (if specified), will be passed to jlink as the --add-module argument. if not specified, either just the main module (if --module is specified), or the default set of modules (if --main-jar is specified) are used.

this option can be used multiple times. 🎀

• --module-path or -p module-path [,module-path...] — a File.pathSeparator separated list of paths.

each path is either a directory of modules or the path to a modular jar, and is absolute or relative to the current directory.

this option can be used multiple times.

• --jlink-options options — a space separated list of options to pass to jlink.

if not specified, defaults to "--strip-native-commands --strip-debug --no-man-pages --no-header-files" — those are the defaults, don't come for me, that's just what it says 🫶

this option can be used multiple times.

• --runtime-image directory — path of the predefined runtime image that will be copied into the application image.

(absolute path or relative to the current directory)

if --runtime-image is not specified, jpackage will run jlink to create the runtime image using options specified by --jlink-options. so either you bring the runtime or she builds one, no third option ✨

---

🌸 Options for creating the application image 🌸

• --input or -i directory — path of the input directory that contains the files to be packaged.

(absolute path or relative to the current directory)

all files in the input directory will be packaged into the application image. all of them. everything. no skipping 💅

• --app-content additional-content [,additional-content...] — a comma separated list of paths to files and/or directories to add to the application payload.

this option can be used more than once.

🍓 macOS note: the value should be a directory with the "Resources" subdirectory (or any other directory that is valid in the "Contents" directory of the application bundle). otherwise, jpackage may produce an invalid application bundle which may fail code signing and/or notarization. seriously, don't skip this part 😭

---

🎀 Options for creating the application launcher(s) 🎀

• --add-launcher name=path — name of launcher, and a path to a Properties file that contains a list of key, value pairs.

(absolute path or relative to the current directory)

the keys "module", "main-jar", "main-class", "description", "arguments", "java-options", "icon", "launcher-as-service", "win-console", "win-shortcut", "win-menu", and "linux-shortcut" can be used.

these options are added to, or used to overwrite, the original command line options to build an additional alternative launcher. the main application launcher will be built from the command line options. additional alternative launchers can be built using this option, and this option can be used multiple times to build multiple additional launchers. launcher girlies rise 🙌

• --arguments arguments — command line arguments to pass to the main class if no command line arguments are given to the launcher.

this option can be used multiple times.

value can contain substrings that will be expanded at runtime. two types of such substrings are supported: environment variables and "APPDIR", "BINDIR", and "ROOTDIR" tokens.

an expandable substring should be enclosed between the dollar sign character ($) and the first following non-alphanumeric character. alternatively, it can be enclosed between "${" and "}" substrings.

expandable substrings are case-sensitive on Unix and case-insensitive on Windows. no string expansion occurs if the referenced environment variable is undefined.

environment variables with names "APPDIR", "BINDIR", and "ROOTDIR" will be ignored, and these expandable substrings will be replaced by values calculated by the app launcher. so don't try to sneak those in, she handles them 💅

prefix the dollar sign character with the backslash character (\) to prevent substring expansion.

• --java-options options — options to pass to the Java runtime.

this option can be used multiple times.

value can contain substrings that will be substituted at runtime, such as for the --arguments option. same energy, different flag ✨

• --main-class class-name — qualified name of the application main class to execute.

⚠️ this option can only be used if --main-jar is specified. no --main-jar, no --main-class, that's the rule 🫶

• --main-jar main-jar — the main JAR of the application; containing the main class (specified as a path relative to the input path).

…and yeah, --module and --main-jar are like the two friends who can't both come to the party — either one or the other, never both 💅

• --module, -m module-name[/main-class] — the main module (and optionally the main class too) of your app 🫶 this module has to live on the module path, no exceptions. When you use this option, the main module gets linked right into the Java runtime image. And remember the rule from above: --module or --main-jar, pick one, not both ✨

---

🎀 Platform dependent options for creating the application launcher:

🪟 Windows platform options (only a thing when you're running on Windows):

• --win-console — makes a console launcher for your app. Lowkey you want this if your application actually needs console interactions, i.e. it talks back in a terminal 💻

🍎 macOS platform options (only a thing when you're running on macOS):

• --mac-package-identifier identifier — an identifier that uniquely identifies your application for macOS. Defaults to the main class name. You may only use alphanumeric characters (A-Z, a-z, 0-9), hyphen (-), and period (.) — anything else is a no 🙈
• --mac-package-name name — the name of the application as it shows up in the Menu Bar. This can totally be different from the application name itself. It must be less than 16 characters long and has to be suitable for displaying in the menu bar and the application Info window. Defaults to the application name 🎀
• --mac-package-signing-prefix prefix — when signing the application package, this value gets prefixed to all components that need to be signed that don't have an existing package identifier ✍️
• --mac-sign — request that the package or the predefined application image be signed ✨
• --mac-signing-keychain keychain-name — name of the keychain to search for the signing identity 🔑 if you don't specify it, the standard keychains get used.
• --mac-signing-key-user-name name — the team or user name portion in Apple signing identities 👑
• --mac-app-store — indicates that the jpackage output is intended for the Mac App Store 🛍️
• --mac-entitlements path — path to the file containing entitlements to use when signing executables and libraries in the bundle 📜
• --mac-app-category category — string used to construct LSApplicationCategoryType in the application plist. The default value is "utilities" 🧰

---

📦 Options for creating the application package:

• --about-url url — URL of the application's home page 🏠
• --app-image directory — location of the predefined application image that's used to build an installable package (on all platforms) or to be signed (on macOS). It's an absolute path or relative to the current directory 📁
• --file-associations path — path to a Properties file that contains a list of key, value pairs (absolute path or relative to the current directory). The keys "extension", "mime-type", "icon", and "description" can be used to describe the association. You can use this option multiple times, bestie 🔗
• --install-dir path — absolute path of the installation directory of the application (on macOS or linux), or a relative sub-path of the installation directory such as "Program Files" or "AppData" (on Windows) 📂
• --license-file path — path to the license file (absolute path or relative to the current directory) 📄
• --runtime-image path — path of the predefined runtime image to install (absolute path or relative to the current directory). This option is required when you're creating a runtime installer ⚠️
• --launcher-as-service — request to create an installer that will register the main application launcher as a background service-type application 🌙

---

🧩 Platform dependent options for creating the application package:

🪟 Windows platform options (only a thing when you're running on Windows):

• --win-dir-chooser — adds a dialog so the user can choose a directory to install the product in 🗂️
• --win-help-url url — URL where the user can get further information or technical support 🆘
• --win-menu — adds a Start menu shortcut for this application, or requests to do so if --win-shortcut-prompt is specified 🪟
• --win-menu-group menu-group-name — the Start Menu group this application gets placed in 📌
• --win-per-user-install — installs the application on a per-user basis. Without this option it installs per-machine 👤 vs 🖥️
• --win-shortcut — adds a desktop shortcut for this application, or requests to do so if --win-shortcut-prompt is specified ✨
• --win-shortcut-prompt — adds a dialog if at least one of --win-menu or --win-shortcut are specified, so the user can choose whether these shortcuts get created by the installer 💬
• --win-update-url url — URL of available application update information 🔄
• --win-upgrade-uuid id — UUID associated with upgrades for this package 🆔
• --win-with-ui — forces the installer to have UI 🖼️

🐧 Linux platform options (only a thing when you're running on Linux):

• --linux-package-name name — name for the Linux package. Defaults to the application name 🐧
• --linux-deb-maintainer email-address — maintainer for the .deb bundle 📧
• --linux-menu-group menu-group-name — the menu group this application gets placed in 📋
• --linux-package-deps package-dep-string — required packages or capabilities for the application 🔧
• --linux-rpm-license-type type — type of the license ("License: value" of the RPM .spec) 📜
• --linux-app-release release — release value of the RPM <name>.spec file or Debian revision value of the DEB control file 🔢
• --linux-app-category category-value — group value of the RPM <name>.spec file or Section value of the DEB control file 🏷️
• --linux-shortcut — creates a shortcut for the application 🎯

🍎 macOS platform options (only a thing when you're running on macOS):

• --mac-dmg-content additional-content [,additional-content...] — include all the referenced content in the dmg. You can use this option more than once 💽

---

🌈 JPACKAGE EXAMPLES

Ok bestie, here's where it gets fun — actual copy-pasteable vibes ✨

Generate an application package suitable for the host system:

For a modular application:

jpackage -n name -p modulePath -m moduleName/className

For a non-modular application:

jpackage -i inputDir -n name \
    --main-class className --main-jar myJar.jar

From a pre-built application image:

jpackage -n name --app-image appImageDir

---

Generate an application image:

For a modular application:

jpackage --type app-image -n name -p modulePath \
    -m moduleName/className

For a non-modular application:

jpackage --type app-image -i inputDir -n name \
    --main-class className --main-jar myJar.jar

To provide your own options to jlink, run jlink separately:

jlink --output appRuntimeImage -p modulePath \
    --add-modules moduleName \
    --no-header-files [<additional jlink options>...]
jpackage --type app-image -n name \
    -m moduleName/className --runtime-image appRuntimeImage

---

Generate a Java runtime package:

jpackage -n name --runtime-image <runtime-image>

---

Sign the predefined application image (on macOS):

jpackage --type app-image --app-image <app-image> \
    --mac-sign [<additional signing options>...]

Note: the only additional options that are permitted in this mode are: the set of additional mac signing options and --verbose 👀 don't try to sneak anything else in there, it's not gonna slay.

---

🦋 JPACKAGE AND JLINK

So here's the tea ☕ — jpackage will use jlink to create the Java Runtime unless you use the --runtime-image option. And the created Java Runtime image on Windows will include MS runtime libraries bundled with the JDK 🪟

But if MS runtime libraries of a different version are needed for the application, the user will need to add/replace those themselves 😭 no cap, that part's on you.

🎀 JPACKAGE RESOURCE DIRECTORY 🎀

Okay so bestie, you can override jpackage's icons, template files, and other resources by adding replacement resources to this directory. jpackage looks up files by specific names in the resource directory — literally the names matter, no cap. ✨

🐧 Resource directory files considered only when running on Linux:

• <launcher-name>.png — the application launcher icon. 🖼️
  • Default resource is JavaApp.png.
• <launcher-name>.desktop — a desktop file to be used with the xdg-desktop-menu command.
  • Considered with application launchers registered for file associations and/or have an icon.
  • Default resource is template.desktop.

📦 Resource directory files considered only when building Linux DEB/RPM installer:

• <package-name>-<launcher-name>.service — a systemd unit file for an application launcher registered as a background service-type application.
  • Default resource is unit-template.service.

🐧 Resource directory files considered only when building Linux RPM installer:

• <package-name>.spec — an RPM spec file.
  • Default resource is template.spec.

🐧 Resource directory files considered only when building Linux DEB installer:

• control — the control file.
  • Default resource is template.control.
• copyright — the copyright file.
  • Default resource is template.copyright.
• preinstall — a pre-install shell script.
  • Default resource is template.preinstall.
• prerm — a pre-remove shell script.
  • Default resource is template.prerm.
• postinstall — a post-install shell script.
  • Default resource is template.postinstall.
• postrm — a post-remove shell script.
  • Default resource is template.postrm.

🪟 Resource directory files considered only when running on Windows:

• <launcher-name>.ico — the application launcher icon. 🪟
  • Default resource is JavaApp.ico.
• <launcher-name>.properties — a properties file for the application launcher executable.
  • Default resource is WinLauncher.template.

🪟 Resource directory files considered only when building Windows MSI/EXE installer:

• <application-name>-post-image.wsf — a Windows Script File (WSF) to run after building the application image.
• main.wxs — the main WiX project file.
  • Default resource is main.wxs.
• overrides.wxi — the overrides WiX project file.
  • Default resource is overrides.wxi.
• service-installer.exe — the service installer executable.
  • Considered if some application launchers are registered as background service-type applications.
• <launcher-name>-service-install.wxi — a service installer WiX project file.
  • Considered if some application launchers are registered as background service-type applications.
  • Default resource is service-install.wxi.
• <launcher-name>-service-config.wxi — a service installer WiX project file.
  • Considered if some application launchers are registered as background service-type applications.
  • Default resource is service-config.wxi.
• InstallDirNotEmptyDlg.wxs — a WiX project file for the installer UI dialog that checks the installation directory doesn't exist or is empty.
  • Default resource is InstallDirNotEmptyDlg.wxs.
• ShortcutPromptDlg.wxs — a WiX project file for the installer UI dialog that configures shortcuts.
  • Default resource is ShortcutPromptDlg.wxs.
• bundle.wxf — a WiX project file with the hierarchy of components of the application image.
• ui.wxf — a WiX project file for the installer UI.
• os-condition.wxf — a WiX project file with the condition to block installation on older versions of Windows.
  • Default resource is os-condition.wxf.
• wix-conv.xsl — a WiX source code converter. It's used for converting WiX sources from WiX v3 to v4 schema when WiX v4 or newer is used.
  • Default resource is wix3-to-wix4-conv.xsl.

🪟 Resource directory files considered only when building Windows EXE installer:

• WinInstaller.properties — a properties file for the installer executable.
  • Default resource is WinInstaller.template.
• <package-name>-post-msi.wsf — a Windows Script File (WSF) to run after building the embedded MSI installer for the EXE installer.
• installer.exe — an executable wrapper for the MSI installer.
  • Default resource is msiwrapper.exe.

🍎 Resource directory files considered only when running on macOS:

• <launcher-name>.icns — the application launcher icon. 🍎
  • Default resource is JavaApp.icns.
• Info.plist — the application property list file.
  • Default resource is Info-lite.plist.template.
• Runtime-Info.plist — the Java Runtime property list file.
  • Default resource is Runtime-Info.plist.template.
• <application-name>.entitlements — the signing entitlements property list file.
  • Default resource is sandbox.plist.

🍎 Resource directory files considered only when building macOS PKG/DMG installer:

• <package-name>-post-image.sh — a shell script to run after building the application image.

🍎 Resource directory files considered only when building macOS PKG installer:

• uninstaller — the uninstaller shell script.
  • Considered if some application launchers are registered as background service-type applications.
  • Default resource is uninstall.command.template.
• preinstall — a pre-install shell script.
  • Default resource is preinstall.template.
• postinstall — a post-install shell script.
  • Default resource is postinstall.template.
• services-preinstall — a pre-install shell script for the services package.
  • Considered if some application launchers are registered as background service-type applications.
  • Default resource is services-preinstall.template.
• services-postinstall — a post-install shell script for the services package.
  • Considered if some application launchers are registered as background service-type applications.
  • Default resource is services-postinstall.template.
• <package-name>-background.png — the background image.
  • Default resource is background_pkg.png.
• <package-name>-background-darkAqua.png — the dark background image.
  • Default resource is background_pkg.png.
• product-def.plist — the package property list file.
  • Default resource is product-def.plist.
• <package-name>-<launcher-name>.plist — a launchd property list file for an application launcher registered as a background service-type application.
  • Default resource is launchd.plist.template.

🍎 Resource directory files considered only when building macOS DMG installer:

• <package-name>-dmg-setup.scpt — the setup AppleScript script.
  • Default resource is DMGsetup.scpt.
• <package-name>-license.plist — the license property list file.
  • Default resource is lic_template.plist.
• <package-name>-background.tiff — the background image.
  • Default resource is background_dmg.tiff.
• <package-name>-volume.icns — the volume icon.
  • Default resource is JavaApp.icns.

That's a wrap on the resource directory era, bestie. 💖 This page is from JDK 27-ea, dated 2026 — and the footer says JPACKAGE(1). Mwah. 💅