When you compile or run a Java program that depends on classes from other JAR files or locations, the Java runtime needs to know where to find those classes. The classpath is the list of paths that Java checks for classes and resources. In this guide we’ll explore how to set the classpath in a few different ways—via the java and javac commands, through the CLASSPATH environment variable and by using the -cp / -classpath switch.

What Is the Classpath?

The classpath is a logical list of directories, JAR archives, and other resources that the Java Virtual Machine (JVM) searches for class files. When the JVM loads a class, it looks through the entries in this list in order until it finds the class. If the class isn’t found, a ClassNotFoundException (compile time) or NoClassDefFoundError (runtime) is thrown.

Example of a classpath for a simple project might look like this:

/home/user/project/bin:/home/user/lib/commons-io-2.8.0.jar        

Method 1 – Using the -cp / -classpath Argument

This is the most common way to set the classpath for a single invocation. The syntax is similar for both javac and java commands.

Compiling

javac -cp ".:/home/user/lib/commons-io-2.8.0.jar" MyProgram.java        

Here . refers to the current directory (where your compiled classes will end up) and the colon : separates entries on Unix/macOS. On Windows, use a semicolon ; instead:

javac -cp ".;C:\libs\commons-io-2.8.0.jar" MyProgram.java       

Running

java -cp ".:/home/user/lib/commons-io-2.8.0.jar" MyProgram        

Method 2 – Setting the CLASSPATH Environment Variable

When you set CLASSPATH, Java uses that value for every subsequent invocation unless overridden by -cp. This can be convenient for small projects or when working in a restricted environment.

Unix/macOS

export CLASSPATH=".:/home/user/lib/commons-io-2.8.0.jar"  

Windows (Command Prompt)

set CLASSPATH=.;C:\libs\commons-io-2.8.0.jar

PowerShell

$env:CLASSPATH = ".;C:\libs\commons-io-2.8.0.jar"

After setting the variable, you can compile and run without providing -cp:

javac MyProgram.java
java MyProgram

Method 3 – Using the Java Launcher’s -Djava.class.path Switch

You can also supply the classpath directly to the java launcher via a system property, which is handy for scripts that need to override many defaults:

java -Djava.class.path=".:/home/user/lib/commons-io-2.8.0.jar" MyProgram

Tips & Common Pitfalls

• Always keep the current directory . (or ./ on Windows) at the start or end of your classpath so that your compiled classes are found.
• Use -classpath and -cp interchangeably. The former is the long form; the latter is easier to type.
• On Windows, remember that the separator is a semicolon ;, while on Unix/macOS it’s a colon :. Mixing these will lead to errors.
• If you need to include all JARs in a directory, you can use wildcard syntax: * for a single JAR or ** for recursive. Example: /home/user/lib/*.
• Always double‑check that your JAR paths are correct. A missing colon or semicolon can cause the JVM to treat multiple entries as a single string.

Practical Example

Suppose you have a project with the following layout:

/home/user/ankurm/java-demo/
├─ src/
│  └─ Main.java
├─ lib/
   ├─ log4j-2.14.1.jar
   └─ gson-2.8.6.jar

Compile Main.java:

javac -cp ".:/home/user/ankurm/java-demo/lib/log4j-2.14.1.jar:/home/user/ankurm/java-demo/lib/gson-2.8.6.jar" src/Main.java

Run the program:

java -cp ".:/home/user/ankurm/java-demo/lib/log4j-2.14.1.jar:/home/user/ankurm/java-demo/lib/gson-2.8.6.jar" Main

Alternatively, set the CLASSPATH once:

export CLASSPATH=".:/home/user/ankurm/java-demo/lib/log4j-2.14.1.jar:/home/user/ankurm/java-demo/lib/gson-2.8.6.jar"
javac src/Main.java
java Main

Wrapping Up

Understanding how to manipulate the classpath through the command line gives you full control over the environments your Java programs run in. Whether you’re working on a small script or a complex multi‑module application, the techniques above ensure that your compiler and runtime can locate all the classes they need.

Happy coding, and feel free to experiment with different classpath configurations to find what works best for your workflow!