Java Module Path: How --module-path Finds Your Modules
The Java module path is the list of locations where javac and java look for modules. You set it with --module-path (short form -p), and every module your program requires must be found there or in the JDK itself.
In Java Modules and module-info in Java you wrote module descriptors. This lesson explains how the JVM actually finds those modules: what can go on the module path, how to inspect module resolution, how to fix FindException, and how plain JAR files become automatic modules.
Java Module Path Syntax
The module path works for both the compiler and the launcher. Each entry is a directory or a JAR file, separated by the platform path separator.
# long form
java --module-path <path1>:<path2> --module <module>/<main.Class>
# short form
java -p <path1>:<path2> -m <module>/<main.Class>
# compiling
javac -d out --module-path <path> --module-source-path src $(find src -name "*.java")
| Option | Short form | Used by | Meaning |
|---|---|---|---|
--module-path | -p | javac, java, jlink, jdeps | Where to find compiled modules |
--module | -m | java, javac | Module to run (java) or compile (javac) |
--module-source-path | none | javac | Where module source folders live |
--add-modules | none | javac, java | Extra root modules to resolve |
--list-modules | none | java | Print every observable module and exit |
--describe-module | -d | java | Print one module's descriptor and exit |
Note: The separator is
:on Linux and macOS and;on Windows, exactly like the classpath. On Windows write-p out;mods\text-utils.jar.
Running a Module From the Module Path
Start with two small modules: com.gocourse.greeter exports a utility class, and com.gocourse.app uses it.
src/
├── com.gocourse.greeter/
│ ├── module-info.java
│ └── com/gocourse/greeter/Greeter.java
└── com.gocourse.app/
├── module-info.java
└── com/gocourse/app/Main.java
com.gocourse.greeter:
module com.gocourse.greeter {
exports com.gocourse.greeter;
}
package com.gocourse.greeter;
public final class Greeter {
private Greeter() { }
public static String greet(String name) {
return "Hello, " + name + "!";
}
}
com.gocourse.app:
module com.gocourse.app {
requires com.gocourse.greeter;
}
package com.gocourse.app;
import com.gocourse.greeter.Greeter;
public class Main {
public static void main(String[] args) {
System.out.println(Greeter.greet("GOCOURSE"));
System.out.println("Running in module: " + Main.class.getModule().getName());
}
}
Compile both modules, then run the app with the out folder on the module path:
javac -d out --module-source-path src $(find src -name "*.java")
java --module-path out --module com.gocourse.app/com.gocourse.app.Main
Output:
Hello, GOCOURSE!
Running in module: com.gocourse.app
How it works:
javacwrites one folder per module:out/com.gocourse.greeter/andout/com.gocourse.app/. Each folder holds amodule-info.class.--module-path outtells the JVM to treat every subfolder ofoutas an exploded module.--module com.gocourse.app/com.gocourse.app.Mainnames the root module and its main class. The JVM reads itsrequiresline, findscom.gocourse.greeteron the module path, and links the two.java -p out -m com.gocourse.app/com.gocourse.app.Mainis the same command with short options.
What You Can Put on the Module Path
A module path entry can be a folder of modules, a single module folder, or a JAR file.
| Entry type | Example | How the JVM reads it |
|---|---|---|
| Directory of exploded modules | out | Each subfolder with module-info.class is one module |
| Directory of JARs | mods | Each .jar inside is one module |
| Single modular JAR | mods/greeter.jar | One module, named by its module-info.class |
| Single plain JAR | libs/text-utils-1.4.2.jar | One automatic module (covered below) |
Package both modules as JARs and run from a folder of JARs:
mkdir -p mods
jar --create --file mods/greeter.jar -C out/com.gocourse.greeter .
jar --create --file mods/app.jar --main-class com.gocourse.app.Main -C out/com.gocourse.app .
java -p mods -m com.gocourse.app
Output:
Hello, GOCOURSE!
Running in module: com.gocourse.app
How it works:
-p modsscans the folder and finds two modular JARs.--main-classstored the main class inapp.jar, so-m com.gocourse.appis enough. You no longer write/com.gocourse.app.Main.- The file names
greeter.jarandapp.jardo not matter here. A modular JAR's name comes from itsmodule-info.class.
You can also mix entries in one path:
java -p "out:mods2/text-utils-1.4.2.jar" --list-modules | grep gocourse
Output (paths shortened):
com.gocourse.app file:///.../out/com.gocourse.app/
com.gocourse.greeter file:///.../out/com.gocourse.greeter/
com.gocourse.textutils@1.4.2 file:///.../mods2/text-utils-1.4.2.jar automatic
Note: For packaging details such as
--main-classand manifests, see JAR File in Java.
Inspecting Module Resolution
When the program starts, the JVM performs module resolution: it begins at the root module and follows every requires until the module graph is complete. Three launcher options let you see this process.
List Observable Modules
--list-modules prints every module the JVM can see: your modules plus all JDK modules.
java -p mods --list-modules | grep gocourse
Output:
com.gocourse.app file:///.../mods/app.jar
com.gocourse.greeter file:///.../mods/greeter.jar
Without the grep, the list also contains every JDK module, such as java.base@21 and java.sql@21, because the JDK's own modules are always observable.
Describe One Module
java -p mods --describe-module com.gocourse.greeter
Output:
com.gocourse.greeter file:///.../mods/greeter.jar
exports com.gocourse.greeter
requires java.base mandated
Show Module Resolution
java -p mods --show-module-resolution -m com.gocourse.app
Output (first lines):
root com.gocourse.app file:///.../mods/app.jar
com.gocourse.app requires com.gocourse.greeter file:///.../mods/greeter.jar
java.base binds jdk.jlink jrt:/jdk.jlink
java.base binds jdk.javadoc jrt:/jdk.javadoc
How it works:
rootmarks the module named with-m. Resolution always starts here.- Each
requiresline shows which module was needed and the exact file that satisfied it, which is the quickest way to answer "which JAR did it load?". bindslines come from services (uses/provides): JDK modules that provide services used byjava.baseare added to the graph.
Fixing FindException: Module Not Found
If a required module is missing from the module path, the program fails before main runs. Copy only app.jar into a new folder and run it:
mkdir -p broken
cp mods/app.jar broken/
java -p broken -m com.gocourse.app
Output:
Error occurred during initialization of boot layer
java.lang.module.FindException: Module com.gocourse.greeter not found, required by com.gocourse.app
The compiler reports the same problem at compile time:
javac -d tmpout src/com.gocourse.app/module-info.java src/com.gocourse.app/com/gocourse/app/Main.java
src/com.gocourse.app/module-info.java:2: error: module not found: com.gocourse.greeter
requires com.gocourse.greeter;
^
1 error
Adding the dependency to the module path fixes both:
javac -d tmpout -p mods/greeter.jar src/com.gocourse.app/module-info.java src/com.gocourse.app/com/gocourse/app/Main.java
How it works:
- Missing modules are detected during resolution, at startup, not later when a class is first used. This is a big difference from the classpath, where a missing class appears only when code touches it.
- The message names both the missing module and the module that required it, so you know exactly which JAR to add.
Two Versions of the Same Module
The module path also rejects duplicates in the same folder:
mkdir -p dup
cp mods/greeter.jar dup/a.jar
cp mods/greeter.jar dup/b.jar
java -p dup --list-modules
Output:
Error occurred during initialization of boot layer
java.lang.module.FindException: Two versions of module com.gocourse.greeter found in dup (a.jar and b.jar)
Note: When the same module appears in different module path entries, the first entry wins and later copies are ignored. Only duplicates inside one directory cause this error.
Automatic Modules: Plain JARs on the Module Path
Many libraries still ship as plain JARs without module-info.class. When you place one on the module path, the JVM turns it into an automatic module so that your modules can requires it.
Build a plain library JAR named text-utils-1.4.2.jar:
package com.gocourse.textutils;
public final class TextUtils {
private TextUtils() { }
public static String padRight(String text, int width) {
return String.format("%-" + width + "s", text);
}
public static String line(int width) {
return "-".repeat(width);
}
}
javac -d libout libsrc/com/gocourse/textutils/TextUtils.java
mkdir -p mods2
jar --create --file mods2/text-utils-1.4.2.jar -C libout .
java -p mods2 --describe-module text.utils
Output:
text.utils@1.4.2 file:///.../mods2/text-utils-1.4.2.jar automatic
requires java.base mandated
contains com.gocourse.textutils
How an Automatic Module Gets Its Name
| Source | Example | Module name |
|---|---|---|
Automatic-Module-Name in the manifest | Automatic-Module-Name: com.gocourse.textutils | com.gocourse.textutils |
| Otherwise, the JAR file name | text-utils-1.4.2.jar | text.utils (version 1.4.2) |
From the file name, the JVM drops .jar, splits off the version (-1.4.2), and replaces every non-alphanumeric character with a dot. Names derived from files are fragile: renaming the JAR changes the module name. Library authors add a stable name to the manifest instead:
echo "Automatic-Module-Name: com.gocourse.textutils" > manifest.txt
jar --create --file mods2/text-utils-1.4.2.jar --manifest manifest.txt -C libout .
java -p mods2 --describe-module com.gocourse.textutils
Output:
com.gocourse.textutils@1.4.2 file:///.../mods2/text-utils-1.4.2.jar automatic
requires java.base mandated
contains com.gocourse.textutils
Rules for Automatic Modules
| Rule | Effect |
|---|---|
| Exports | Every package in the JAR is exported and opened |
| Reads | It reads every other module, including classes on the classpath |
requires transitive | Requiring one automatic module gives access to all other automatic modules |
| Services | META-INF/services files are turned into provides directives |
Note: Automatic modules are a bridge for migrating to modules. They let your module depend on a library before that library adds its own
module-info.java.
Module Path vs Classpath
The same JAR behaves differently depending on which path you put it on. The next lesson, Java Classpath, covers the classpath in depth.
| Feature | Module path (-p) | Classpath (-cp) |
|---|---|---|
| Unit | Module (named or automatic) | Individual classes and JARs |
| Missing dependency | Detected at startup (FindException) | Detected when first used (NoClassDefFoundError) |
| Duplicate packages | Error | Silently uses the first one found |
| Encapsulation | Only exported packages are accessible | All public classes are accessible |
| Plain JAR becomes | An automatic module | Part of the unnamed module |
Can a named module requires it? | Yes | No |
That last row matters. A named module cannot read the unnamed module, so a library on the classpath is invisible to requires:
java -cp mods2/text-utils-1.4.2.jar -p mods2/invoice.jar -m com.gocourse.invoice
Error occurred during initialization of boot layer
java.lang.module.FindException: Module com.gocourse.textutils not found, required by com.gocourse.invoice
Real-World Example: Invoice App Using a Plain Library JAR
This example puts everything together. A modular invoice application depends on the plain text-utils JAR from above, loaded as an automatic module. The full layout:
mods2/
├── text-utils-1.4.2.jar plain JAR, manifest has Automatic-Module-Name
└── invoice.jar modular JAR with main class
isrc/com.gocourse.invoice/
├── module-info.java
└── com/gocourse/invoice/InvoiceApp.java
module-info.java:
module com.gocourse.invoice {
requires com.gocourse.textutils; // automatic module from a plain JAR
}
InvoiceApp.java:
package com.gocourse.invoice;
import com.gocourse.textutils.TextUtils;
import java.util.LinkedHashMap;
import java.util.Map;
public class InvoiceApp {
public static void main(String[] args) {
Map<String, Double> items = new LinkedHashMap<>();
items.put("Java Course", 1499.00);
items.put("Spring Boot Course", 2499.00);
items.put("Mock Interview", 799.50);
System.out.println("INVOICE INV-2026-031");
System.out.println(TextUtils.line(36));
double total = 0;
for (Map.Entry<String, Double> item : items.entrySet()) {
System.out.printf("%s Rs. %9.2f%n", TextUtils.padRight(item.getKey(), 20), item.getValue());
total += item.getValue();
}
System.out.println(TextUtils.line(36));
System.out.printf("%s Rs. %9.2f%n", TextUtils.padRight("Total", 20), total);
Module utilsModule = TextUtils.class.getModule();
System.out.println();
System.out.println("TextUtils loaded from module: " + utilsModule.getName());
System.out.println("Automatic module? " + utilsModule.getDescriptor().isAutomatic());
}
}
Compile against the library on the module path, package the app, and run:
javac -d iout --module-path mods2 --module-source-path isrc $(find isrc -name "*.java")
jar --create --file mods2/invoice.jar --main-class com.gocourse.invoice.InvoiceApp -C iout/com.gocourse.invoice .
java -p mods2 -m com.gocourse.invoice
Output:
INVOICE INV-2026-031
------------------------------------
Java Course Rs. 1499.00
Spring Boot Course Rs. 2499.00
Mock Interview Rs. 799.50
------------------------------------
Total Rs. 4797.50
TextUtils loaded from module: com.gocourse.textutils
Automatic module? true
How it works:
- Compile time.
--module-path mods2letsjavacfindcom.gocourse.textutils, so therequiresline and theimportboth compile. - Startup.
-p mods2makes both JARs observable. Resolution starts atcom.gocourse.invoice, followsrequires com.gocourse.textutils, and finds it intext-utils-1.4.2.jarthrough itsAutomatic-Module-Name. - Access. Automatic modules export all packages, so
TextUtilsis accessible without anyexportsline in the library. - Proof at runtime.
TextUtils.class.getModule()returns the automatic module, andgetDescriptor().isAutomatic()returnstrue. - The numbers.
1499.00 + 2499.00 + 799.50 = 4797.50.padRight(..., 20)and%9.2fkeep the columns aligned.
If the library author later adds a real module-info.java with the same module name, the invoice app keeps working with no changes, which is exactly why a stable Automatic-Module-Name is important.