classpath : Java Glossary
home C words local find no local find frame, full screen Google search web for topic jump to footer translate with Babelfish 2007-10-12 by Roedy Green ©1996-2008 Canadian Mind Products
Go to : punctuation 0-9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z (all)
classpath
The CLASSPATH is an environment variable that tells the Java compiler javac.exe where to look for class files to import or java.exe where to find class files to interpret.

In contrast, the PATH is an environment variable that tells the command processor the where to look for executable files, e.g. *.exe, *.com and *.bat files. The Classpath is one of the most confusing things in Java. Unfortunately, you must master it to even compile HelloWorld.

File Naming Recipes Hashtable Explanation
Adding Jars to the Classpath Examples
Gotchas ext directories
Raspberries Command Line Too long?
Hiding Places Global Classpath Anachronism
Rules Servlet Wombs
Spaces and Quotes Where That Class Came From
Tips Learning More
Complexities Links
Under the Hood

CLASSPATH And File Naming Recipes

Here are my simplified rules for using CLASSPATH and naming the files on the javac.exe and java.exe command line:
  1. Put every class in a package. Don’t use the default package.
  2. Use the latest JDK. It will be the one everyone you ask help from is familiar with. Two dangling prepositions in one sentence. Churchill would be proud.
  3. Configure your SET CLASSPATH= in the environment to clear it out.
  4. You don’t need to explicitly include rt.jar:
    rt.jar system class files :
    unless you are using Jikes, where you need to add it to the JIKESPATH, but not the CLASSPATH.
  5. In all that follows, everything is strictly case sensitive.
  6. To compile a HelloWorld.java app in the default package in C:\MyDir, use 
    cd \MyDir
javac.exe -classpath . HelloWorld.java
  7. To run a HelloWorld.class app, in the default package in C:\MyDir, use 
    cd \MyDir
java.exe -classpath . HelloWorld
  8. To compile a HelloWorld.java app in C:\com\mindprod\mypackage, in package com.mindprod.mypackage, use 
    c:
cd \
javac.exe -classpath . com\mindprod\mypackage\HelloWorld.java

rem alternatively
e:
cd E:\com\mindprod\mypackage
javac.exe -classpath .;C:\ HelloWorld.java
  9. To run a HelloWorld.class app in C:\com\mindprod\mypackage, in package com.mindprod.mypackage, use 
    c:
cd \
rem not you do not do cd \com\mindprod\mypackage!!
java.exe -classpath . com.mindprod.mypackage.HelloWorld
  10. To compile a HelloWorld.class app in C:\com\mindprod\mypackage, in into a jar called helloworld.jar in package com.mindprod.mypackage, use
  11. To run a HelloWorld.class app in C:\com\mindprod\mypackage, in a jar called helloworld.jar in package com.mindprod.mypackage, use 
    CD \dirwherejaris
java.exe -classpath helloworld.jar com.mindprod.mypackage.HelloWorld

rem or if your Main-Class manifest points to HelloWorld.class.
java.exe -jar helloworld.jar

rem or if your *.jar extension is set to invoke java.exe
helloworld.jar
  12. If for any reason the examples shown do not work with your version of java.exe, try replacing the \ in com\mindprod\mypackage\HelloWorld with / mypackage/HelloWorld.
If you stare long enough at those examples, you may understand the logic behind them, and then you can create variants. If you can’t, just slavishly copy the closest matching example.

Adding Jars to the Classpath

There are 5 ways to put jars on the classpath:
  1. Include the jar name in the set classpath.
  2. Include the jar name in the -classpath command line option.
  3. Include the jar name in the Class-Path option in the manifest.
  4. In Java 1.6+, use a wildcard to include all jars in a directory into the set classpath or the command line -classpath. 
    rem use of wildcard in classpath to add all jars in C:\jardir and E:\morejars
java.exe -classpath C:\jardir\*;E:\morejars\*
  5. Put the jar in the ext directory.

Classpath Gotchas

  1. The elements of the classpath are platform specific OS directory names (with \ or / separators) or jar file names. The package/classnames on the command line are not; they are fully-qualified dotted names. Don’t try to concoct a chimera class name such as C:/com.mindprod.mypackage.MyClass
  2. If you want a jar on the classpath, you must put the jar file name on the classpath, not just the name of the directory where the jar lives. This means you need whacking long classpaths, with every jar in a common directory each added to the classpath individually. Perhaps one day Sun will implement a JARPATH. In would not be hard to build a wrapper around javac.exe and Java.exe that faked in a JARPATH. In the meantime you can use
    To add to the usual extdir. In Java 1.6 you can use a wildcard to include all jars in a directory. 
    rem use of wildcard in classpath to add all jars in C:\jardir and E:\morejars
java.exe -classpath C:\jardir\*;E:\morejars\*
  3. If you use the -jar option, java.exe ignores the classpath. It will only look in that jar. Try using the manifest Class-Path instead.
  4. Beware of inserting extra semicolons (in general, File. pathSeparatorChar chars) in your CLASSPATH. Everything to the right will be ignored!, leading you to pull out your remaining hair in frustration wondering why java.exe can’t find the classes. You must have exactly one semicolon between elements, no lead/trail/extras.
  5. Beware. Putting D: on the classpath is not the same thing as putting D:\. The first put the current directory of D: on the classpath. The second puts the root directory. They are often the same, but not always.

Classpath Raspberries

Where the Classpath Hides

Stalking your classpath, you must look in different places depending on the platform:

Rules About Classpaths

  1. Simply copying or moving your jar files to the ext directory pointed to by the system property java.ext.dirs =C:\Program Files\java\jre1.6.0_06\lib\ext automatically puts them on the classpath without having to mention them explicitly. This is a great way to prune back an overblown classpath. It is safest to put your jars in all the ext directories:
    where to look for ext directories :
    You never know for sure where your javac.exe or java.exe is going to look. Grrr. You can change the location of the ext directory on the command line. 
    java.exe -Djava.ext.dirs=C:\mylibs mypackage.MyClass
    See the ext dirs entry for details.
  2. Class names are always fully qualified with the complete package name. There is no way to ever abbreviate the higher levels.
  3. Each element of the CLASSPATH provides a starting point to look for a fully qualified package and class name, identical to the way it appeared in the package or import statement.
  4. If the element of the CLASSPATH is the name of a directory, Java will look in that tree for directory names matching the package name structure. It looks at one place only. It does not search. The class file sought must be filed under the one and only precise fully qualified pathname, or it won’t be found. It wants to find a *.class file (or *.java file), at the precisely correct spot in the directory tree. You must get an exact match on the fully qualified name. The name of the directory specified in the CLASSPATH itself is totally immaterial in determining the package name.
  5. If the element of the CLASSPATH is a jar, Java will look in the internal directory structure of the jar for an exact match on the fully qualified name. It looks; it does not search. The class file sought must be filed under the one and only precise fully qualified pathname, or it won’t be found. The location of the jar is totally immaterial in determining the name of the package. If you peek inside the jar with WinZip you should see pathnames on each class file matching the package structure. Download and examine any of my jars and the corresponding source to see how it works.
  6. An alternative, ultimately more confusing way of looking at it, is that you specify part of the operating system’s name for a class file in the CLASSPATH and part in the package name. Java source imports and package statements, javac.exe and java.exe command lines specify only the fully qualified package name, not the higher order part handled by the CLASSPATH. The higher levels that are handled by the CLASSPATH (which could appear on the command line via -classpath option), are effectively invisible to your Java programs. However, you are not at liberty to shuffle levels of qualification between your import and classpath unless you adjust all your package statements and recompile as well.

Spaces and Quotes in Classpaths

Spaces in filenames are a royal PITA, however, Microsoft forces them down your throat because most packages install in C:\Program Files. There are several plausible ways you might deal with spaces in classpaths: javac.exe and java.exe are fairly forgiving. Note that just to keep you on your toes: Here is what works and what does not:rem missing quotes around classpath value on the command line.
javac -classpath .;C:\;J:\Program Files\javamail1.4\mail.jar;J:\Program Files\jaf1.1\activation.jar *.java

rem quotes around whole classpath on the command line.
javac -classpath ".;C:\;J:\Program Files\javamail1.4\mail.jar;J:\Program Files\jaf1.1\activation.jar" *.java

rem quotes around each space-containing element of the classpath on the command line.
javac -classpath .;C:\;"J:\Program Files\javamail1.4\mail.jar";"J:\Program Files\jaf1.1\activation.jar" *.java

rem no quotes on the classpath environment variable.
set classpath=.;C:\;J:\Program Files\javamail1.4\mail.jar;J:\Program Files\jaf1.1\activation.jar
javac *.java

rem quotes around whole classpath environment variable.
set classpath=".;C:\;J:\Program Files\javamail1.4\mail.jar;J:\Program Files\jaf1.1\activation.jar"
javac *.java

rem illegal quotes around each element of the classpath environment variable.
set classpath=".;C:\;"J:\Program Files\javamail1.4\mail.jar";"J:\Program Files\jaf1.1\activation.jar"
javac *.java
There is some logic to it. The command line needs quotes around the entire classpath to tell it apart from any other command line options. SET CLASSPATH= needs no quotes because the end of line terminates the classpath. The simplest rule is always put to always put quotes around the entire classpath, even though they are not necessary for SET CLASSPATH=.

CLASSPATH Tips

  1. See below for tip on how to squeeze long classpath onto the command line.
  2. Unlike C++, Java compilers use the CLASSPATH to find and examine compiled code rather than source header files to learn how about how to invoke the various methods. The compiler also uses the CLASSPATH to find and compile the corresponding source if no class file is available. The runtime also uses the CLASSPATH to find the class files to execute.
  3. Note that CLASSPATH uses forward (or optionally backslashes under Windows W95/W98/Me/NT/W2K/XP/W2K3/Vista to separate levels, and semicolons to separate directories, (in general File. pathSeparatorChar directory separators). In contrast, inside Java programs in import statements, you use dots to separate levels. Inside <lt;APPLET CODE statements it is best if you use dots to represents levels inside jar files and slashes to represent files. java.exe uses only dots, no slashes or backslashes allowed.
  4. Presuming you had a CLASSPATH like this: 
    SET CLASSPATH=.;E:\com\mindprod\project;
    You might think that you could have an import like this: 
    import com.mindprod.project.mybeans.Jumping;
    However, you cannot respecify any level already mentioned in the CLASSPATH. You just give the low levels of qualification like this:
  5. If you have a jar file in C:\MyStuff\ajar.jar, on the classpath, then com.mindprod.somepackage is the internal directory name stored inside the jar file. You might be tempted to might try to get at the class in the jar with the following import: 
    import MyStuff.com.mindprod.somepackage.SomeClass;
    That will not work. You may only specify the low order qualification that is actually part of the package name like this: 
    // import com.mindprod.somepackage.SomeClass which lives
// in file C:\MyStuff\ajar.jar
// in internal zip directory com/mindprod/somepackage
// in file SomeClass.class.
import com.mindprod.somepackage.SomeClass;
  6. Basically the rule is, your package name cannot provide redundant information that the CLASSPATH has already provided. You always have to specify the fully qualified package name. You can’t abbreviate with a smart Alec CLASSPATH like this: 
    SET CLASSPATH=.;E:\com\mindprod\mypackage;
    Then expect to get away with specifying only MyClass instead of com.mindprod.mypackage.MyClass. You always have to use fully qualified class names.
  7. You can check the CLASSPATH setting by typing: 
    echo %CLASSPATH%
    under W95/W98/Me/NT/W2K/XP/W2K3/Vista or 
    echo $CLASSPATH
    under Unix/Linux.
    If you want to be really sure, use the Wassup utility which will also find and report on Webgain’s SC.INI CLASSPATH when it applies.
  8. If you don’t want to be bothered with manually composing a CLASSPATH, try SmartJ, though it is now badly out of date in JDK support.
  9. For applications, you can also specify the CLASSPATH on the command line with the -classpath or -cp (for short) option switch. e.g. 
    java.exe -cp C:\MyStuff;C:\MyStuff\mygoodies.jar  HelloWorld
    This is the safest place especially when every app needs a slightly different CLASSPATH and/or a different JVM. The catch is the CLASSPATH can be very long which makes the command line hard to type and read. Infuriatingly, the -cp shortcut does not work with javac.exe as well.
  10. Keep in mind that Java is extremely case sensitive, even if your operating system is not. Be very careful to get case precisely right any time you specify a filename, <APPLET CODE, or CLASSPATH. Unfortunately Windows and Windows NT will often lie to you about the actual case of a name. Tracking down case mismatches can drive you nuts. JP Soft’s 4NT DIR /F is useful at getting at the true case of a filename. Packages should contain lower case only. Classes should start with an upper case letter. Variables should start with a lower case letter. See coding conventions.
  11. Just to keep you on your toes, in JDK 1.0 putting the classes.zip on the CLASSPATH is mandatory. in JDK 1.1, putting classes.zip on the CLASSPATH is optional. In 1.2 and 1.3 putting rt.jar on the classpath is an error. Starting with version 1.2 the class files live in: and they automatically go on the classpath.
  12. See java.exe for a more discussion of how the java.exe runtime uses package names, class names and the CLASSPATH to find the classes, and javac.exe for how the javac.exe compiler finds the dependent *.java files that also need compilation.
  13. You have little control over the CLASSPATH used by a browser for an Applet. You can find out what it is using for a CLASSPATH by running this Applet. You have to grant it security permission to look at your classpath. If that does not work, try Wassup.
  14. I lost pounds of hair fighting with classpath. I have found some magic patterns that work, and now just stomp out boiler plate to create the skeleton java, HTML and bat files for new projects. You might study my jar files and Applet HTML and emulate my patterns. See the downloads page. You can use my ANT scripts as a starting point. I long ago gave up on using BAT files.
  15. To discover what your program is using as the classpath use:
    You can view the default value of these properties by running wassup as an application. The CLASSPATH separator character is platform dependent. You can discover it with the system properties as well. It will usually be ; or :. You must put ., the current directory, explicitly on the CLASSPATH.
  16. If you use the -jar option, java.exe ignores the classpath. It will only look in that jar.
  17. Classpath will make a lot more sense if you start with some jars and bat files that work, and study them, looking inside the zips and jars with Winzip.
  18. The Webgain (née Symantec) compilers ignored the usual SET CLASSPATH= and take one from the \VCP\BIN\SC.INI file instead. Class files may be standalone, combined in zip files or combined in jar files. Java looks for class files in any directories mentioned in the CLASSPATH, but only searches jar and zip files if they are explicitly mentioned. A typical CLASSPATH statement might look like this:
    all on one gigantic line without any spaces. Ouch!
  19. My personal classpath looks like this: SET CLASSPATH=.;C:\;C:\exper;e:\. This will look for classes in the current path, or in a directory matching the package on C:\, C:\exper or e:\. I keep most of my class files in C:\com\mindprod\xxxx where the package is com.mindprod.xxxx, or in C:\exper when there is no package.

CLASSPATH Complexities

I lied to you. Life is actually a little more complicated. If you feel ready for the whole truth, and want to understand the logic behind those examples, here is how CLASSPATH really works. Suddenly all of classpath’s craziness made sense once I figured out how it worked inside. You may be similarly lucky.

The Key To Understanding: Look Under the Hood

This all sounds hideously complicated. My explanations sound like drooling nonsense. It did not come clear to me until I began to think about how java.exe and javac.exe make use of the classpath. Then it all made sense.
  1. When java.exe (or <APPLET CODE) wants to find a class, it has the fully qualified classname composed of package.classname e.g. com.mindprod.business.HelloWorld.
  2. It then looks at each element (a chunk between semicolons/pathSeparators) of the CLASSPATH, working left to right seeking a match.
  3. If that CLASSPATH element is a jar, it looks for an entry inside the jar for a folder called precisely com/mindprod/business and a member called precisely HelloWorld.class. It is irrelevant to the naming scheme where in the directory structure the jar file itself is. All that matters is perfect-fully-qualified-pathnames-to-package mapping inside the jar.
  4. If the CLASSPATH element is a directory, it expects to find in that directory a directory subtree called precisely com\mindprod\business and in the business directory it expects to find a file called precisely HelloWorld.class. It does not matter where the CLASSPATH element itself is in the directory tree. That has no effect on the package name.
  5. The lookup is quite quick for each element of the classpath. It involves no scanning, just a lookup, does this class file exist by precisely this name in precisely this place? It does though have to repeat this for each element of the classpath before it gives up.
  6. When javac.exe wants to find a class, it may want either the *.java source or the compiled *.class or both. It uses the same mechanism to find them.

The Hashtable Explanation

If you understand Hashtables, this explanation may let you suddenly grok the classpath.

A ClassLoader with plenty of RAM could work this way. It creates a giant Hashtable of all possible classes out there on disk in all the directories and jars on the classpath and all the ext directory jars, using fully qualified package and class names as the keys. It would include classes it might never even possibly load. A real implementation would use some tricks to conserve RAM such as making a Hashtable of Hashtables, one for each layer of the package name, or keys broken into interned segments, or might only build a Hashtable for jarred classes, but for the purpose of understanding, imagine just a simple single Hashtable with the keys to all the fully qualified package and classnames on the classpath.

How does the ClassLoader build this Hashtable? It looks at the first segment of the classpath and starts adding classnames using the fully qualified class name as the key and where the class files are on disk as the value. Then it moves onto the next segment of the classpath. It adds all those classnames. If it discovers a duplicate, it ignores the new key, and keeps the key it already has. This ensures the first occurrence of a class on the classpath will be the one used.

Now when you first use a class, the ClassLoader looks up the name in the Hashtable, and it if it is present, it knows where on disk and in what jar to find it. There is no scanning required, just a straight forward keyed Hashtable lookup. If the class is not present in the Hashtable, the ClassLoader knows the class is nowhere to be found and it raises the dreaded NoClassDefFoundError exception.

Classpath Examples

If, for example, you had a class called com.mindprod.bulk.Resend e.g. class Resend in package com.mindprod.bulk,

If you did cd \ and had classpath . then java would expect to find the class file in: C:\com\mindprod\bulk\Resend.class.

If you did cd \com\mindprod\bulk and had classpath . then java would expect to find the class file in: C:\com\mindprod\bulk\com\mindprod\bulk\Resend.class.

If you did cd \ and had classpath C:\ then it would expect to find the class file in: C:\com\mindprod\bulk\Resend.class.

If you did cd \com\mindprod\bulk and had classpath C:\ then it would expect to find the class file in: C:\com\mindprod\bulk\Resend.class.

To get the hang of this, experiment with simple classpaths with only one element to them, then gradually build up more complex classpaths that search in many places.

ext Directories

The ext dir is a much easier way to add whole jars to the class path. See the ext dirs entry for details. I almost never use the old classpath any more.

Command Line Too long?

In Windows in particular, you will often find all the junk you need to put on a command line is too long. Here are a few tricks to shorten it.
  1. Use the SET CLASSPATH in a kickoff bat file for each application. That way it does not need to be on the java.exe command line with everything else.
  2. Build the classpath up in pieces like this: 
    set classpath = C:\somedir\jar
set classpath = %CLASSPATH%;C:\anotherdir
set classpath = %CLASSPATH%;C:\yetanotherdir
    You can still get in trouble if the final result is too long.
  3. Move jars into the ext directory. Then they don’t need to be on the classpath.
  4. Instead of passing all parameter with the -D option, put them in a properties file.
  5. Use 4DOS or 4NT for your command processor. They have more relaxed limits.

Global Classpath Is An Anachronism

The global classpath is an anachronism. It is impossible to have one classpath that satisfies all possible compilations and all possible applications. Installers will meddle with it. Programs will work, then mysteriously stop working when you make some innocent change the classpath.

Instead, put it in your IDE projects, on your javac.exe -classpath and java.exe -classpath commands and in your jar manifests where the rest of the world cannot meddle with it.

Avoid using version numbers in your classpaths. They tend to go stale.

If you leave out your SET classpath, it defaults to simply . the current directory.

Servlet Wombs

When you write servlets, JSP, Struts and or code for other application servers, the womb may simulate a common classpath and possibly a classpath for each application. You will have to read the womb documentation to find out where you put your class files and resources.

The womb sometimes extends the set classpath with the WEB-APP\classes directory for additional class files for a particular application, and WEB-APP\lib for jars for a particular application. Instead of adding jars and directories to the general classpath, you make multiple copies off the classes and jars and put them in the various WEB-APPs as needed. This helps minimize unexpected interactions between applications, e.g. one app needs version 1.1 of a jar and another version 2.0.

Where Did that Class Come From?

Sometimes you want to know where a class or resource came from. Which jar, which directory. This may help track down problems with duplicates or obsolete versions.

Sometimes you can’t even find the jar, much less put it on the classpath. I have written some .help for that problem.

You also might like to implement the which and what utilities.

Learning More

Sun’s tutorial on classpath
classpath tool student project
environment
ext directory
GNU Classpath: a Java core library nothing at all to do with classpaths. What an idiotic name!
HelloWorld
java.exe
javac.exe
NoClassDefFoundError
PATH
SET
SmartJ
Sudsy’s explanation of classpath
where
where to find classes
where to find jars
which and what student project
CMP_homejump to top
CMP logo		 feedback Please email your feedback for publication, errors, omissions, broken/redirected link reports
and suggestions to improve this page to Roedy Green : feedback email
made with CSS
HTML Checked!
ICRA ratings logo
mindprod.com IP:[65.110.21.43]
Your face IP:[38.103.63.17] Spread the Net
You are visitor number 370,613.
You can get a fresh copy of this page from: or possibly from your local J: drive (Java virtual drive/Mindprod website mirror)
http://mindprod.com/jgloss/classpath.html J:\mindprod\jgloss\classpath.html