The class path can be set using either the-classpath
option when calling a JDK tool (the preferred method) or by setting theCLASSPATH
environment variable. The-classpath
option is preferred because you can set it individually for each application without affecting other applications and without other applications modifying its value.
%
jdkTool-classpath
path1:
path2...-or-
% CLASSPATH=
path1:
path2...
% export CLASSPATH
where:
- jdkTool
- A command-line tool, such as
java
,javac
, orjavadoc
. For a listing, see JDK Development Tools.
- path1
:
path2- Paths to the .jar, .zip or .class files. Each path should end with a filename or directory depending on what you are setting the class path to:
- For a .jar or .zip file that contains .class files, the path ends with the name of the .zip or .jar file.
- For .class files in an unnamed package, the path ends with the directory that contains the .class files.
- For .class files in a named package, the path ends with the directory that contains the "root" package (the first package in the full package name).
Multiple path entries are separated by colons.
The default class path is the current directory. Setting the
CLASSPATH
variable or using the-classpath
command-line option overrides that default, so if you want to include the current directory in the search path, you must include "." in the new settings.Classpath entries that are not either a directory or an archive (.zip or .jar file) are ignored.
The class path tells Java tools and applications where to find third-party and user-defined classes -- that is, classes that are not Java extensions or part of the Java platform. The class path needs to find any classes you've compiled with the javac compiler -- its default is the current directory to conveniently enable those classes to be found.
JDK 1.2, the JVM and other JDK tools find classes by searching the Java platform (bootstrap) classes, any extension classes, and the class path, in that order. (For details on the search strategy, see How Classes Are Found.) Class libraries for most applications will want to take advantage of the extensions mechanism. You only need to set the class path when you want to load a class that's (a) not in the current directory or in any of its subdirectories, and (b) not in a location specified by the extensions mechanism.
If you are upgrading from an older version of the JDK, your startup settings may include
CLASSPATH
settings that are no longer needed. You should remove any settings that are not application-specific, such asclasses.zip
. Some third-party applications that use the Java Virtual Machine may modify yourCLASSPATH
environment variable to include the libaries they use. Such settings can remain.You can change the class path by using the Java tools' -classpath option when you invoke the JVM or other JDK tools or by using the
CLASSPATH
environment variable. Using the-classpath
option is preferred over settingCLASSPATH
environment variable because you can set it individually for each application without affecting other applications and without other applications modifying its value.Classes can be stored either in directories (folders) or in archive files. The Java platform classes are stored in
rt.jar
. For more details on archives and information on how the class path works, see Understanding the class path and package names near the end of this document.
- Important Note: Older versions of the JDK included a
<
jdk-dir>/classes
entry in the default class path. That directory exists for use by the JDK, and should not be used for application classes. Application classes should be placed in a directory outside of the JDK. That way, installing a new JDK does not force you to reinstall application classes. For compatibility with older versions, applications that use the<
jdk-dir>/classes
directory as a class library will run in the current version, but there is no guarantee that they will run in future versions.
The Java tools java, jdb, javac, and javah have a
-classpath
option which replaces the path or paths specified by theCLASSPATH
environment variable while the tool runs. This is the recommended option for changing class path settings, because each application can have the class path it needs without interfering with any other application.The runtime tools java and jdb have a
-cp
option, as well. This option is an abbreviation for-classpath
.For very special cases, both java and javac have options that let you change the path they use to find their own class libraries. The vast majority of users will never to need to use those options, however.
In general, you will want to use the
-classpath
command-line option, as explained in the previous section. This section shows you how to set theCLASSPATH
environment variable if you want to do that, or clear settings left over from a previous installation.Setting CLASSPATH
In csh, the
CLASSPATH
environment variable is modified with thesetenv
command. The format is:
setenv CLASSPATH
path1:
path2In sh, the
CLASSPATH
environment variable can be modified with these commands:
CLASSPATH =
path1:
path2:
...
export CLASSPATH
Clearing CLASSPATH
If your
CLASSPATH
environment variable has been set to a value that is not correct, or if your startup file or script is setting an incorrect path, you can unsetCLASSPATH
in csh by using:unsetenv CLASSPATH
In sh, you would use:
unset CLASSPATH
These commands unset
CLASSPATH
for the current shell only. You should also delete or modify your startup settings to ensure that you have the rightCLASSPATH
settings in future sessions.Changing Startup Settings
If theCLASSPATH
variable is set at system startup, the place to look for it depends on the shell you are running:
Shell Startup Script csh, tcsh Examine your .cshrc
file for thesetenv
command.sh, ksh Examine your .profile
file for theexport
command.
Java classes are organized into packages which are mapped to directories in the file system. But, unlike the file system, whenever you specify a package name, you specify the whole package name -- never part of it. For example, the package name for
java.awt.Button
is always specified asjava.awt
.For example, suppose you want the Java runtime to find a class named
Cool.class
in the packageutility.myapp
. If the path to that directory is/java/MyClasses/utility/myapp
, you would set the class path so that it contains/java/MyClasses
.To run that app, you could use the following JVM command:
% java -classpath /java/MyClasses utility.myapp.Cool
When the app runs, the JVM uses the class path settings to find any other classes defined in the
utility.myapp
package that are used by theCool
class.Note that the entire package name is specified in the command. It is not possible, for example, to set the class path so it contains
/java/MyClasses/utility
and use the commandjava myapp.Cool
. The class would not be found.(You may be wondering what defines the package name for a class. The answer is that the package name is part of the class and cannot be modified, except by recompiling the class.)
Note: An interesting consequence of the package specification mechanism is that files which are part of the same package may actually exist in different directories. The package name will be the same for each class, but the path to each file may start from a different directory in the class path.
Folders and archive files
When classes are stored in a directory (folder), like
/java/MyClasses/utility/myapp
, then the class path entry points to the directory that contains the first element of the package name. (in this case,/java/MyClasses
, since the package name isutility.myapp
.)But when classes are stored in an archive file (a .zip or .jar file) the class path entry is the path to and including the .zip or .jar file. For example, to use a class library that is in a .jar file, the command would look something like this:
% java -classpath /java/MyClasses/myclasses.jar utility.myapp.Cool
Multiple specifications
To find class files in the directory
/java/MyClasses
as well as classes in/java/OtherClasses
, you would set the class path to:% java -classpath /java/MyClasses:/java/OtherClasses ...
Note that the two paths are separated by a colon.
Specification order
The order in which you specify multiple class path entries is important. The Java interpreter will look for classes in the directories in the order they appear in the class path variable. In the example above, the Java interpreter will first look for a needed class in the directory
/java/MyClasses
. Only if it doesn't find a class with the proper name in that directory will the interpreter look in the/java/OtherClasses
directory.