Java Module Path: How --module-path Finds Your Modules

Su Suriya Ravichandran Updated 18 Nov 2026
9 min read ·Lesson 231 of 306

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")
OptionShort formUsed byMeaning
--module-path-pjavac, java, jlink, jdepsWhere to find compiled modules
--module-mjava, javacModule to run (java) or compile (javac)
--module-source-pathnonejavacWhere module source folders live
--add-modulesnonejavac, javaExtra root modules to resolve
--list-modulesnonejavaPrint every observable module and exit
--describe-module-djavaPrint 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:

  • javac writes one folder per module: out/com.gocourse.greeter/ and out/com.gocourse.app/. Each folder holds a module-info.class.
  • --module-path out tells the JVM to treat every subfolder of out as an exploded module.
  • --module com.gocourse.app/com.gocourse.app.Main names the root module and its main class. The JVM reads its requires line, finds com.gocourse.greeter on the module path, and links the two.
  • java -p out -m com.gocourse.app/com.gocourse.app.Main is 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 typeExampleHow the JVM reads it
Directory of exploded modulesoutEach subfolder with module-info.class is one module
Directory of JARsmodsEach .jar inside is one module
Single modular JARmods/greeter.jarOne module, named by its module-info.class
Single plain JARlibs/text-utils-1.4.2.jarOne 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 mods scans the folder and finds two modular JARs.
  • --main-class stored the main class in app.jar, so -m com.gocourse.app is enough. You no longer write /com.gocourse.app.Main.
  • The file names greeter.jar and app.jar do not matter here. A modular JAR's name comes from its module-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-class and 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:

  • root marks the module named with -m. Resolution always starts here.
  • Each requires line shows which module was needed and the exact file that satisfied it, which is the quickest way to answer "which JAR did it load?".
  • binds lines come from services (uses / provides): JDK modules that provide services used by java.base are 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

SourceExampleModule name
Automatic-Module-Name in the manifestAutomatic-Module-Name: com.gocourse.textutilscom.gocourse.textutils
Otherwise, the JAR file nametext-utils-1.4.2.jartext.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

RuleEffect
ExportsEvery package in the JAR is exported and opened
ReadsIt reads every other module, including classes on the classpath
requires transitiveRequiring one automatic module gives access to all other automatic modules
ServicesMETA-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.

FeatureModule path (-p)Classpath (-cp)
UnitModule (named or automatic)Individual classes and JARs
Missing dependencyDetected at startup (FindException)Detected when first used (NoClassDefFoundError)
Duplicate packagesErrorSilently uses the first one found
EncapsulationOnly exported packages are accessibleAll public classes are accessible
Plain JAR becomesAn automatic modulePart of the unnamed module
Can a named module requires it?YesNo

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:

  1. Compile time. --module-path mods2 lets javac find com.gocourse.textutils, so the requires line and the import both compile.
  2. Startup. -p mods2 makes both JARs observable. Resolution starts at com.gocourse.invoice, follows requires com.gocourse.textutils, and finds it in text-utils-1.4.2.jar through its Automatic-Module-Name.
  3. Access. Automatic modules export all packages, so TextUtils is accessible without any exports line in the library.
  4. Proof at runtime. TextUtils.class.getModule() returns the automatic module, and getDescriptor().isAutomatic() returns true.
  5. The numbers. 1499.00 + 2499.00 + 799.50 = 4797.50. padRight(..., 20) and %9.2f keep 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.

0 Comments

Reviewed before they appear

No comments yet.

Java
Java Introduction Java Features Java Syntax Java Comments Java Statements Java Output Java Variables Java Data Types Java Type Casting Java Operators Java Strings Java Numbers Java Math Java Booleans Java User Input Java Conditions Java If Else Java Switch Java While Loop Java For Loop Java Break Java Continue Java Arrays Java Methods Java Parameters Java Return Values Java Scope Java Recursion Install Java Install JDK Java IDEs Java JDK Java JRE Java JVM Java Compiler Java File Compile Java Run Java JShell Basics Java Packages Java OOP Java Classes Java Objects Class Methods Constructors Constructor Overload this Keyword static Keyword final Keyword Encapsulation Inheritance Polymorphism Abstraction Access Modifiers super Keyword Method Overload Method Override Instanceof Operator Nested Classes Inner Classes Anonymous Classes Enums Records Array Basics Array Length Loop Arrays Multidimensional Arrays Array Copy Array Sorting Array Search ArrayList LinkedList HashSet TreeSet HashMap TreeMap Queue Interface Deque Interface Stack Class Iterator List Interface Set Interface Map Interface Collections Class Comparable Comparator Generics Basics Generic Classes Generic Methods Wildcards String Basics String Length String Methods String Concatenation String Compare String Search String Replace String Split String Format StringBuilder StringBuffer Text Blocks Regular Expressions Number Types Integer Class Float Class Double Class BigInteger BigDecimal Math Class Random Numbers Number Format Date Basics LocalDate LocalTime LocalDateTime ZonedDateTime Date Formatting Date Parsing Period Class Duration Class Java Instant Class Java Exception Basics Java try...catch Java Multiple Catch Blocks Java finally Block Java throw Keyword Java throws Keyword Java Checked Exceptions Java Unchecked Exceptions Java Custom Exceptions Java try-with-resources Java Exception Chaining Java File Basics Java Create Files Java Read Files Java Write Files Java Delete Files Java File Paths Java File Class Java BufferedReader Java BufferedWriter Java FileInputStream Java FileOutputStream Java Object Streams Java Directory Handling Java NIO Basics Java Files API Java Input Java Scanner Class Java Console Input Java PrintStream Java InputStream Java OutputStream Java Reader Class Java Writer Class Java Buffered Streams Java Data Streams Java Generics Introduction Java Generic Types Java Generic Methods Java Bounded Types Java Wildcards Java Type Erasure Java Generic Interfaces Java Generic Collections Java Lambda Basics Java Lambda Syntax Java Functional Interfaces Java Method References Java Stream API Java Stream Creation Java Stream Filter Java Stream Map Java Stream Reduce Java Stream Sort Java Stream Collect Java Collectors Class Java Optional Class Java Parallel Streams Java Threads: Thread Basics Create a Thread in Java Java Thread Class Java Runnable Interface Java Thread States Java Thread Sleep Java Thread Join Java Thread Priority Java Synchronization Java Thread Safety Java Race Conditions Java Deadlocks Java Executor Service Java Thread Pools Java Callable Interface Java Future Interface Java CompletableFuture Java Concurrent Collections Java Atomic Classes Java Virtual Threads Java Networking Basics Java URL Class Java URI Class Java HttpClient Java HTTP Requests Java HTTP Responses Java Socket Basics Java ServerSocket Java DatagramSocket Java WebSocket Basics Java JDBC Basics Java JDBC Setup Java Database Connection Java JDBC Connection Interface Java JDBC Statement Java PreparedStatement Java ResultSet Java JDBC CRUD Operations Java JDBC Transactions Java JDBC Batch Update Java Connection Pooling with HikariCP Java JPA Basics: Entities, EntityManager and JPQL Java Hibernate Basics: SessionFactory, Session and HQL Package in Java: Basics Explained with Examples Create Package in Java: Step-by-Step Guide with Examples Import Package in Java: The import Statement Explained Access Control in Java: Packages, Classes and Members JAR File in Java: Create, Run and Inspect JAR Files Java Modules: Introduction to the Java Module System module-info in Java: Every Module Directive Explained Java Module Path: How --module-path Finds Your Modules Java Classpath: How -cp and CLASSPATH Find Your Classes Java Annotations: Basics of @ Metadata in Java Java Built-in Annotations: @Override, @Deprecated and More Java Custom Annotations: Create Your Own @interface Java Annotation Targets: @Target and ElementType Explained Java Reflection API: Inspect and Use Classes at Runtime Java Class Metadata: Names, Modifiers, Hierarchy and Generic Java Dynamic Objects: Create Objects Dynamically With Reflec Java Dynamic Proxy: Intercept Method Calls With Proxy and In Java Security Java Secure Coding Java Password Hashing Java Input Validation Java Cryptography Basics Java KeyStore Basics Java TLS Basics Java SecureRandom Java JUnit Basics Java JUnit Test Methods JUnit Assertions JUnit Test Fixtures JUnit Parameterized Tests Mockito in Java Java Mock Objects Java Integration Testing Java Code Coverage Maven in Java Create a Maven Project in Java Maven Dependencies Maven Plugins Gradle in Java Gradle Build Gradle Dependencies Build Executable JAR in Java Build WAR File in Java HTTP Basics in Java Java Servlet Basics Servlet Lifecycle in Java HttpServletRequest in Java HttpServletResponse in Java JSP in Java JSTL in JSP REST API in Java JSON in Java Java Web Application Spring Framework Basics Spring Boot Tutorial Spring MVC Spring Data JPA Spring Security Spring Boot REST API Jakarta EE Basics Java Deployment JAR Deployment Java WAR Deployment Run Java as a Service Docker Java: Dockerize a Java Application Java Environment Variables and Configuration Java Logging Basics Java Production Setup Java JVM Options Java JVM Monitoring Java Hello World App Java Calculator App Java Number Guess Game Java Student Manager Java Library System Java Bank App Java Todo App Java File Manager Java Quiz App Java REST API Project Java Chat Server Java Employee Manager Java E-commerce API
Ask about this post
AI Ask about this post

Ask questions about Java Module Path: How --module-path Finds Your Modules and get answers drawn from it.

Signed-in readers only.