Step-by-Step IzPack Tutorial: From Setup to Custom Packs

IzPack: The Complete Guide to Java Installer Creation

What is IzPack?

IzPack is an open-source, Java-based tool for building lightweight, cross-platform installers for Java applications. It packages application files, resources, and installation logic into a single distributable installer JAR that runs on any system with a compatible Java Runtime Environment (JRE). IzPack focuses on simplicity, extensibility, and producing native-feeling installers without platform-specific binaries.

When to use IzPack

• You ship Java applications that must run across Windows, macOS, and Linux.
• You want a single installer artifact (JAR) that users can run with java -jar.
• You need customizable installer screens, conditionals, and support for multiple installation packs.
• You prefer a text/XML-based configuration that integrates with build tools (Maven, Gradle, Ant).

Key concepts

• Installer XML: The central configuration file that declares packs, files, panels (screens), variables, and other installer behavior.
• Packs: Logical groups of files (e.g., core, docs, examples) that users can choose to install.
• Panels: UI screens shown during installation (welcome, license, target selection, progress, finish).
• Listeners and custom actions: Hooks to run code during installation steps (pre-install, post-install).
• Compression and compression levels: Options to reduce installer size (e.g., ZIP, gzip).
• Uninstaller: Optionally include an uninstaller to remove installed files.

Installation and setup

1. Install Java JDK (11+ recommended) and ensure java and javac are on PATH.
2. Add IzPack to your build system:
   • Maven: use the izpack-maven-plugin.
   • Gradle: use community Gradle plugins or invoke IzPack via an exec task.
   • Ant: use the IzPack Ant tasks.
3. Obtain IzPack distribution (binary or Maven Central dependency) for the chosen version.

Basic installer XML structure

• Define with metadata (app name, version, author).
• Define each with id, name, and entries.
• Define to set the installer UI flow.
• Configure compression, javaversion, and other runtime options.

Example (conceptual):

Code
Copy CodeCopied


 
<appname>MyApp</appname> <version>1.0</version> 

  
<pack name="Core"    <file src="build/libs/myapp.jar" targetdir="$INSTALL_PATH/lib"/> </pack> 

  
<panel classname="HelloPanel"/> <panel classname="LicencePanel"/> <panel classname="TargetPanel"/> <panel classname="InstallPanel"/> 





Building an installer with Maven

Add izpack-maven-plugin to your pom.xml.
Configure plugin with path to installer XML and output file name.
Run mvn package izpack:bundle (plugin goals may vary by version) to generate installer JAR.

Common customizations

Custom panels: Implement Java classes extending IzPack panel classes and include them in XML.
Variable substitution: Use variables (e.g., $APP_HOME) in paths and dialogues, set defaults, and allow user overrides.
Conditions: Show or hide packs/panels based on OS, available disk space, or user choices.
Native shortcuts: Create desktop/start menu shortcuts using installer actions or bundled helper scripts.
Localization: Provide resource bundles for different languages and reference them in panels.

Adding an uninstaller
Enable the uninstaller in the installation XML. IzPack will create an executable uninstaller alongside installed files, tracking installed files and undoing changes when run.
Testing installers

Run the produced JAR on target platforms: java -jar myapp-installer.jar.
Test different install options, pack selections, and failure scenarios.
Verify uninstaller behavior and edge cases (permission issues, missing JRE).

Troubleshooting tips

If panels fail to show, check XML panel classnames and plugin versions.
Large installers: enable stronger compression and remove unnecessary files.
Missing resources: ensure relative paths in  entries are correct at build time.
Java compatibility: match the JRE version used to run installers with the IzPack-required Java version.

Alternatives and when not to use IzPack

If you need native MSI/DMG installers with deep OS integration, consider platform-specific tools (WiX for MSI, pkgbuild/hdiutil for macOS).
For very small installers or containerized apps, consider zip/tar distributions or platform package managers.

Resources and next steps

Start by creating a minimal installer XML with one pack and the default panels.
Integrate IzPack into your CI build so installers are produced automatically.
Incrementally add custom panels, localization, and listeners as needed.

This guide covers the essentials to get started building cross-platform Java installers with IzPack. Follow IzPack documentation and plugin docs for version-specific configuration and advanced features.