JMOD File Format in Java

1. Overview

In this tutorial, we’ll deep dive into what JMOD is and how it differs from JAR files. Then, we’ll create a sample modular project, package it as a JMOD file, and use jlink to generate a minimal Java runtime tailored specifically to the application.

2. What’s JMOD?

Before Java 9, Java applications were packaged primarily as JAR files with build tools such as Maven and Gradle. With the introduction of the Java Platform Module System in Java 9, Java gained a formal module system and introduced the JMOD file format.

A JMOD file is a packaging format for Java modules that are intended to be used during compile and link time, but not directly at runtime.

Unlike JAR files, we can’t place JMOD files on the classpath or module path when running an application.

Like JAR files, JMOD files can contain compiled class files and resources. However, JMOD files can also include additional artifacts such as native libraries, configuration files, and legal notices.

2.1. Its Relationship With JPMS

Moreover, JMOD is tightly related to JPMS. It serves as a packaging format for modules that may need more than just compiled bytecode files.

In the JPMS architecture, source code is compiled into bytecode. Then, the bytecode is packaged into modules (JAR or JMOD). Then, at link time, we can use jlink to assemble modules into a custom runtime image.

Link time is the phase between compilation and execution. During this phase, the Java linker analyzes module dependencies and bundles only the required modules into a runtime image. JMOD files are specifically designed to participate in the linking process.

2.2. The Purpose of JMOD and How It Differs From Modular JARs

While JPMS supports modular JAR files, JMOD was introduced to address the limitations of JAR packaging. A modular JAR contains compiled classes and resources and can be used directly at runtime.

On the other hand, a JMOD file may contain native code and additional metadata. It’s intended for link-time processing and can’t be executed directly. Unlike a JAR file, it isn’t meant to be published to repositories such as Maven Central.

Its primary purpose is to support the creation of custom runtime images using jlink. For instance, packaging an application together with a full JRE can significantly increase distribution size. Instead, JMOD enables the creation of a custom Java runtime that contains only the modules required by the application. This results in a smaller and more learner-friendly distribution size.

3. Practical Example: Creating a Custom JRE

To better understand how the JMOD file format works, let’s build a simple modular Java application and use it to create a custom runtime image.

3.1. Sample Application

Let’s bootstrap a simple Java project that logs “Hello Baeldung!” to the console:

public class Hello {

    private static final Logger LOG = Logger.getLogger(Main.class.getName());
    public static void main(String[] args) {
        LOG.info("Hello Baeldung!");
    }
}

In the code above, we define a class named Hello and use the java.util.logging API to log a message to the console.

Next, let’s make the project a Java module by adding a module-info.java file at the root of the module source directory:

module com.baeldung.jmod_sample {
    requires java.logging;
}

Here, com.baeldung.jmod_sample is the module name. While every module implicitly depends on java.base, additional modules such as java.logging must be implicitly declared.

Next, let’s compile our program:

$ javac -d output $(find -name \*.java)

The command above locates all .java files inside the src directory and compiles them. Then, it outputs the generated .class files into the output directory.

3.2. Packaging to JMOD

Next, let’s prepare our modular application for a custom runtime creation by packaging it into a JMOD file.

To create a JMOD file, we can use the jmod create command:

$ jmod create \
  --class-path output/ \
  --main-class com.baeldung.jmod_sample.Hello \
  --module-version 1.0.0 -p output hello.jmod

Here, –class-path output/ specifies the directory containing the compiled classes. Also, we define the entry point of the module and the name of the generated JMOD file.

After executing the command, a hello.jmod file is created in the current directory.

Next, let’s inspect the JMOD file to see what it contains by running the jmod describe command:

$ jmod describe hello.jmod

This outputs the content of the file to the console:

[email protected]
requires java.base mandated
requires java.logging
contains com.baeldung.jmod_sample
main-class com.baeldung.jmod_sample.Hello

This confirms that the JMOD file correctly encapsulates the compile module and its metadata, making it ready for use during link time with jlink.

3.3. Creating a Custom Runtime Using jlink

Now that we have generated our JMOD file, let’s use it create a custom Java runtime using jlink:

$ jlink \
  --module-path $JAVA_HOME/jmods:hello.jmod \
  --add-modules com.baeldung.jmod_sample \
  --launcher hello=com.baeldung.jmod_sample/com.baeldung.jmod_sample.Hello \
  --strip-debug \
  --compress=2 \
  --no-header-files \
  --no-man-pages \
  --output custom-runtime-min

Here, the  –module-path $JAVA_HOME/jmods:hello.jmod specifies where jlink should locate require modules. Next, the –add-modules option indicates the root module to include in the runtime image.

Then we use the launcher option to create a launcher script that runs the Hello class. After executing the command, jlink produces a new directory named “custom-runtme-min“.

We can check the size of the generated runtime image:

$ du -sh custom-runtime-min

Here’s the output:

35M     custom-runtime-min/

The resulting runtime is approximately 35 MB, significantly smaller than a full JDK installation, which typically exceeds 400 MB.

Let’s verify which modules were bundled into the runtime image:

$ ./custom-runtime-min/bin/java --list-modules

Here’s the output:

[email protected]
[email protected]
[email protected]

This confirms that only the required modules were included.

Finally, let’s run the generate launcher:

$ ./custom-runtime-min/bin/hello

The command above produces:

Mar 01, 2026 10:15:38 AM com.baeldung.jmod_sample.Hello main
INFO: Hello Baeldung!

The application runs successfully using the custom runtime image.

4. Conclusion

In this article, we learned what a JMOD file is, what it can contain, how it differs from a  JAR file, and when it should be used. Also, we built a simple modular Java application, packaged it into a JMOD file, and used it with jlink to generate a lean, custom Java runtime image tailored specifically to our application.

As usual, the complete source code for the example is available over on GitHub.