Java Module Path: Learn Module Path, Classpath, Resolution, and Modular JARs

The module path is the mechanism Java uses to locate named modules during compilation and execution. If module-info.java describes what a module needs and exposes, the module path helps Java find those modules.

This distinction is important. A module descriptor defines the rules, while the module path provides the location from which Java can discover the modules involved in those rules.

Why Does the Module Path Exist?

Traditional Java applications commonly use the classpath to locate classes and JAR files. With the Java Platform Module System introduced in Java 9, Java needed a mechanism specifically designed to locate modules and respect their boundaries.

That mechanism is the module path.

Concept	Classpath	Module Path
Main unit	Classes and JAR files	Modules
Introduced	Traditional Java mechanism	Java 9
Dependency model	Less explicit	Explicit module dependencies
Encapsulation	Mainly based on access modifiers	Also enforced through module boundaries
Typical option	-cp or --class-path	-p or --module-path

Basic Module Path Syntax

The Java compiler and launcher provide the --module-path option, commonly abbreviated as -p.

--module-path path

For example:

java --module-path mods -m com.example.app/com.example.app.Main

Here, mods identifies the location where Java should search for modules.

Module Path and module-info.java

The module path becomes particularly useful when one module depends on another.

Suppose we have a library module:

module com.example.library {
    exports com.example.library.api;
}

And an application module:

module com.example.app {
    requires com.example.library;
}

Java knows that the application requires com.example.library, but it still needs to locate that module. The module path provides the location.

Remember: requires describes a dependency; --module-path tells Java where to find modules.

Example Project Structure

Imagine a project compiled into a directory called mods.

mods/
├── com.example.library/
│   └── ...
└── com.example.app/
    └── ...

The mods directory can be supplied as the module path.

java --module-path mods -m com.example.app/com.example.app.Main

Java searches the specified module path for the required modules and constructs the module graph needed to launch the application.

Compiling with the Module Path

The module path is also used during compilation when a module depends on another compiled module.

javac --module-path mods -d mods/com.example.app src/com.example.app/module-info.java src/com/example/app/Main.java

The important part is the --module-path option. It tells the compiler where it can locate required modules.

Running a Module

When launching a modular application, Java commonly uses the -m option to identify the module and its main class.

java --module-path mods -m com.example.app/com.example.app.Main

The format is:

module-name/main-class

So in this example:

com.example.app/com.example.app.Main

means that Java should launch Main from the com.example.app module.

Module Path vs Classpath

One of the most common sources of confusion is the difference between the classpath and module path.

The classpath is primarily a collection of locations from which Java loads classes and resources. The module path is designed to locate modules and allows Java to use the module descriptors that define their relationships and boundaries.

Classpath:
java --class-path lib/* com.example.Main

Module Path:
java --module-path mods -m com.example.app/com.example.app.Main

The commands may look similar, but they represent different application models.

Module Path Can Contain JAR Files

The module path is not limited to exploded directories. Modular applications can also use modular JAR files.

mods/
├── com.example.library.jar
└── com.example.app.jar

Java can discover the modules represented by these JAR files when the directory is supplied as the module path.

java --module-path mods -m com.example.app/com.example.app.Main

Exploded Modules

During development, a module may exist as an ordinary directory containing compiled classes and its module descriptor rather than as a packaged JAR.

mods/
└── com.example.app/
    ├── module-info.class
    └── com/
        └── example/
            └── app/
                └── Main.class

This is commonly called an exploded module. It can be placed directly on the module path.

Multiple Module Path Locations

The module path can contain multiple locations. On common operating systems, locations are separated using the platform-specific path separator.

java --module-path mods:libs -m com.example.app/com.example.app.Main

The exact separator differs by operating system, so build tools are often preferred in larger projects because they handle these details automatically.

Module Resolution

When Java starts a modular application, it does more than simply search for a class. It resolves the module graph based on the application's root module and its declared dependencies.

For example:

com.example.app
        |
        v
com.example.library
        |
        v
java.sql

The application requires the library, and the library may require another module. Java uses these declarations to determine the required module graph.

Important: The module path is not simply a replacement name for the classpath. Its purpose is to support the module system's explicit dependencies, module descriptors, and stronger encapsulation.

Common Beginner Mistakes

• Confusing --module-path with --class-path.
• Declaring requires but forgetting to make the required module available on the module path.
• Using the wrong module name when launching with -m.
• Confusing a package name with a module name.
• Assuming that every JAR automatically behaves as a named module.
• Ignoring the difference between an exploded module and a packaged modular JAR.

Best Practices

• Keep module dependencies explicit in module-info.java.
• Use the module path consistently when working with named modules.
• Prefer build tools for larger projects instead of manually maintaining long compiler and runtime commands.
• Keep module boundaries clear and avoid unnecessary dependencies.
• Understand whether a dependency is being loaded through the module path or classpath.

Interview Insight

A common interview question is, "What is the module path in Java?" A strong answer is: The module path is a collection of locations used by the Java compiler and runtime to locate modules. It works with the Java module system and can contain exploded modules or modular JAR files.

Interview Tip: Do not say that the module path simply replaces the classpath. Explain that both mechanisms exist, but the module path is specifically designed to locate and resolve modules and their declared dependencies.

Quick Revision

Concept	Key Point
Module path	Locations from which Java discovers modules.
Option	--module-path or -p.
Module launch	Uses -m module/main-class.
Module dependency	Declared using requires.
Module formats	Can include exploded modules and modular JAR files.
Classpath	Traditional mechanism for locating classes and resources.
Module resolution	Uses declared dependencies to construct the required module graph.

The module path provides the physical locations from which Java can discover the logical modules described by module-info.java. Once you understand the relationship between the module descriptor, module path, and module graph, modular Java applications become much easier to reason about. The final topic in this chapter is Modules vs Packages, where these two concepts can be compared directly.