How to Use JPackage to Create Native Installers for Java Applications

By XaHertz  |  April 16, 2024  |  Last Updated : April 16, 2024

If you are a Java developer, you might have wondered how to distribute your applications to end users in a convenient and user-friendly way. You might have also faced the challenge of bundling your application with a Java runtime, or making sure that the users have the right version of Java installed on their machines.

Fortunately, Java 14 introduced a new tool called JPackage, which can help you create native installers and packages for your Java applications. In this post, we will explore what JPackage is, why it is useful, and how to use it.

What is JPackage?

JPackage is a command-line tool that takes a Java application and a Java runtime image as an input, and produces a Java application image that includes all the necessary dependencies as an output. It can also produce a native package in a platform-specific format, such as an exe on Windows or a dmg on macOS. Each format must be built on the platform it runs on, there is no cross-platform support.

Why JPackage?

It is standard practice while distributing software to deliver an installable package to the end user. This package is compatible with the user's native platform and hides the internal dependencies and setup configurations. For example, we use DMG files on macOS and MSI/EXE files on Windows. This allows the distribution, installation, and uninstallation of the applications in a manner that is familiar to our end users.

JPackage allows developers to create such an installable package for their JAR files. The user does not have to explicitly copy the JAR file or even install Java to run the application. The installable package takes care of all of this.

How to use JPackage?

The key prerequisites for using the JPackage command are:

  • The system used for packaging must contain the application to be packaged, a JDK, and software needed by the packaging tool.
  • It needs to have the underlying packaging tools used by JPackage:
    • RPM, DEB on Linux: On Red Hat Linux, we need the rpm-build package; on Ubuntu, we need the fakeroot package
    • PKG, DMG on macOS: Xcode command line tools are required when the –mac-sign option is used to request that the package be signed, and when the –icon option is used to customize the DMG image
    • EXE, MSI on Windows: On Windows, we need the third party tool WiX 3.0 or later
  • The application packages must be built on the target platform. This means to package the application for multiple platforms, we must run the packaging tool on each platform.

Let's create an EXE Installer package for an application JAR. As mentioned in the above section, the application JAR should be pre-built, and it will be used as an input to the JPackage tool. The following Batch Script will create an EXE Installer package for Windows when execured from the root folder of a Java Project that uses Maven:

Let's go through some of the options used:

  • --input: Location of folder where the input jar files are located
  • --dest: Location of folder where the generated output file is placed
  • --name: Name of the application
  • --vendor: Publisher of the application
  • --main-jar: JAR file to launch at the start of the application
  • --app-version: Version of the application
  • --type: Type of package to create. Valid values are: app-image, exe, msi, rpm, deb, pkg, dmg. If this option is not specified a platform dependent default type will be created.

There are many other options available for customizing your package, just change the options at the jpackage command in the script. You can refer to the official documentation for more details. I hope this post was helpful and saved you some hassle. If you have any questions or feedback, feel free to leave a comment below.

Last updated on April 16, 2024