Including All JARs in the Java Classpath

By the end of this page, you will understand how the Java classpath works, when wildcard JAR loading is supported, why lib/*.jar may not behave as expected, and how to correctly include all JAR files from a directory when running Java programs.

The classpath tells the Java runtime where to look for compiled classes and packaged libraries such as JAR files.

When you run a Java program, the JVM does not automatically search every folder on your machine. It only looks in the locations you explicitly provide through the classpath.

A classpath entry can be:

• A directory containing .class files
• A specific .jar file
• In modern Java launchers, a wildcard like lib/* to include all JARs in one directory

A common source of confusion is that Java wildcard classpath support is not the same as shell file expansion.

For Java, the supported wildcard form is typically:

lib/*

not:

lib/*.jar

Why this matters:

• lib/* tells the Java launcher to include all JAR files in that directory
• lib/*.jar may be expanded by the shell before Java sees it, which can produce unexpected results
• Wildcards apply to JAR files in a directory, not recursively to subdirectories

So in most cases, the correct approach is:

java -cp "lib/*:." my.package.Program

On Windows, the separator is ; instead of ::

java -cp "lib/*;." my.package.Program

This concept matters because nearly every non-trivial Java application depends on external libraries. If the classpath is wrong, the program will fail with errors such as ClassNotFoundException or NoClassDefFoundError.

Think of the classpath as a list of places Java is allowed to search.

If your program needs a book, Java will only look in the libraries listed on that search list.

• . means: "also look in the current directory"
• lib/some.jar means: "look in this one exact library"
• lib/* means: "look in every JAR sitting directly inside the lib folder"

If a library is not on that list, Java acts as if it does not exist, even if the file is right there on disk.

The most common syntax is:

java -cp "lib/*:." my.package.Program

What this means

• -cp is short for -classpath
• lib/* includes all JAR files in the lib directory
• . includes the current directory
• my.package.Program is the main class to run

Linux/macOS example

java -cp "lib/*:." com.example.Main

Windows example

java -cp "lib/*;." com.example.Main

Including one specific JAR manually

java -cp "lib/a.jar:lib/b.jar:." com.example.Main

Important note about *.jar

This often looks reasonable:

java -classpath lib/*.jar:. my.package.Program

But it may fail because the shell may expand lib/*.jar before Java processes the classpath. Java's own wildcard support expects lib/*.

Example project structure

project/
├── lib/
│   ├── gson.jar
│   └── commons-lang3.jar
└── com/example/Main.class

Run it with:

java -cp "lib/*:." com.example.Main

This tells Java to search both:

• all JARs in lib/
• compiled classes reachable from the current directory

Consider this command:

java -cp "lib/*:." com.example.Main

Now walk through what happens:

1. The java launcher starts.
2. It reads the classpath from -cp.
3. It sees two classpath entries:
   • lib/*
   • .
4. lib/* is interpreted by Java as: include all JAR files directly inside lib.
5. . tells Java to also search the current directory for compiled classes.
6. Java tries to load com.example.Main.
7. If com/example/Main.class exists under the current directory, Java loads it.
8. When Main references classes from external libraries, Java searches the JARs included from lib/*.
9. If the needed class is found in one of those JARs, execution continues.
10. If not, Java throws an error such as:

java.lang.ClassNotFoundException

Small trace example

Suppose:

.
├── lib/
│   ├── gson.jar
│   └── util.jar
└── com/example/Main.class

And Main.class uses com.google.gson.Gson.

Execution flow:

• Java finds com.example.Main in .
• Main starts running
• Main needs com.google.gson.Gson
• Java searches lib/gson.jar
• Class is found
• Program continues normally

Classpath configuration is used in many practical situations:

Running a small Java app manually

You have compiled .class files and a lib/ folder of dependencies.

java -cp "lib/*:." com.example.Main

Launching internal tools or scripts

Teams often keep utility programs with a local lib/ directory for database drivers, JSON libraries, or logging frameworks.

Using JDBC drivers

Database drivers are usually shipped as JAR files. Including all JARs in lib/ makes it easy to run tools that connect to MySQL, PostgreSQL, or Oracle.

Legacy applications without Maven or Gradle

Older Java projects often depend on manually managed JAR files. Wildcard classpaths reduce command length and setup errors.

Batch jobs and scheduled tasks

A cron job or task scheduler may run a Java command-line application that loads libraries from a deployment folder.

In real projects, developers rarely type long classpaths by hand for large applications. Instead, they use a few common patterns.

1. A lib/ directory plus wildcard classpath

Useful in simple deployments:

java -cp "app.jar:lib/*" com.example.Main

2. Build tools manage dependencies

Tools like Maven and Gradle usually generate the runtime classpath automatically. This avoids manual mistakes.

3. Startup scripts

Teams often create shell scripts or batch files so users do not need to remember separators or quoting rules.

#!/bin/sh
java -cp "lib/*:." com.example.Main

4. Guarding against missing dependencies

When a classpath is wrong, applications may fail at startup. Developers often test startup early so missing libraries are caught quickly.

5. Packaging into one executable JAR

Instead of many JAR files, some teams package dependencies into a single distributable artifact. This simplifies deployment, though the underlying classpath concept still matters.

6. Environment-specific launch configuration

Different environments may load different driver or plugin JARs by pointing the classpath to different folders.

Using lib/*.jar instead of lib/*

This is the most common issue.

Broken example:

java -cp lib/*.jar:. com.example.Main

Better:

java -cp "lib/*:." com.example.Main

Forgetting the current directory

If your own compiled classes are not inside a JAR, you often still need ..

Broken example:

java -cp "lib/*" com.example.Main

If Main.class is in the current directory structure, use:

java -cp "lib/*:." com.example.Main

Using the wrong path separator

• Linux/macOS use :
• Windows uses ;

Broken on Windows:

java -cp "lib/*:." com.example.Main

Correct on Windows:

java -cp "lib/*;." com.example.Main

Expecting recursive folder scanning

lib/* includes JARs directly inside lib, not inside nested folders like lib/plugins/extra/.

If you need nested directories, you must add them explicitly or use build tooling.

Misunderstanding shell expansion

In some shells, *.jar is expanded before Java sees it. That changes how arguments are passed and can break the command.

Quoting issues

Quoting helps ensure the classpath is passed as one argument.

Safer example:

java -cp "lib/*:." com.example.Main

-cp vs -jar

Classpath basics

• -cp and -classpath mean the same thing
• . means current directory
• Linux/macOS separator: :
• Windows separator: ;

Include all JARs in a folder

Linux/macOS:

java -cp "lib/*:." com.example.Main

Windows:

java -cp "lib/*;." com.example.Main

Rules

• Use lib/*, not usually lib/*.jar
• Wildcard includes JARs directly in that folder
• Wildcard does not search subdirectories recursively
• Add . if your compiled classes are in the current directory
• Quote the classpath to keep it as one argument

Common errors

• ClassNotFoundException → class not found on classpath
• NoClassDefFoundError → class was present at compile time or expected, but missing at runtime

Manual alternative

java -cp "lib/a.jar:lib/b.jar:." com.example.Main

Can I include all JAR files from a directory in Java?

Yes. Use a wildcard directory entry such as lib/* in the classpath.

Why does lib/*.jar not work reliably?

Because the shell may expand it before Java handles the classpath. Java's wildcard classpath support is designed around lib/*.

Does lib/* include subdirectories too?

No. It includes JAR files directly inside lib, not nested folders.

Do I still need to include . in the classpath?

Yes, if your own compiled .class files are being loaded from the current directory structure.

What is the difference between ClassNotFoundException and NoClassDefFoundError?

ClassNotFoundException usually means Java could not locate a class when asked to load it. NoClassDefFoundError often means the class was expected at runtime but is missing from the actual runtime classpath.

Is the classpath separator the same on every operating system?

No. Use : on Linux/macOS and ; on Windows.

Should I list every JAR manually in modern projects?

Usually no. For larger projects, build tools such as Maven or Gradle manage dependencies more safely and conveniently.

• Java classpath — The core mechanism for telling Java where to find classes and libraries.
• JAR files — Java libraries are commonly packaged as JAR archives.
• ClassNotFoundException — A common error caused by incorrect classpath configuration.
• NoClassDefFoundError — Another runtime error often related to missing dependencies.
• Java packages — Package names map to directory structure when Java loads classes.
• Maven dependencies — Maven automates library management and classpath generation.
• Gradle dependencies — Gradle also manages dependencies and runtime classpaths.
• Executable JARs — An alternative deployment approach that reduces manual classpath setup.