Documentation Contents
Java Platform, Standard Edition Tools Reference
Contents Previous Next

# 2 Setting the Class Path

The class path is the path that the Java Runtime Environment (JRE) searches for classes and other resource files.

This chapter covers the following topics:

- Synopsis

- Description

- JDK Commands Class Path Options

- CLASSPATH Environment Variable

- Class Path Wild Cards

- Class Path and Package Names

## Synopsis

The class search path (class path) can be set using either the `-classpath` option when calling a JDK tool (the preferred method) or by setting the `CLASSPATH` 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.

sdkTool -classpath classpath1:classpath2...

setenv CLASSPATH classpath1:classpath2...

sdkTool

  A command-line tool, such as `java`, `javac`, `javadoc`, or `apt`. For a listing, see JDK Tools and Utilities at
  `http://docs.oracle.com/javase/8/docs/technotes/tools/index.html`

classpath1:classpath2

  Class paths to the JAR, zip or class files. Each class path should end with a file name or directory depending on what you are setting the class path to, as follows:

  - For a JAR or zip file that contains class files, the class path ends with the name of the zip or JAR file.

  - For class files in an unnamed package, the class path ends with the directory that contains the class files.

  - For class files in a named package, the class path ends with the directory that contains the root package, which is the first package in the full package name.

  Multiple path entries are separated by semicolons with no spaces around the equals sign (=) in Windows and colons in Oracle Solaris.

  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, then you must include a dot (`.`) in the new settings.

  Class path entries that are neither directories nor archives (.zip or JAR files) nor the asterisk (`*`) wildcard character are ignored.

## Description

The class path tells the JDK tools and applications where to find third-party and user-defined classes that are not extensions or part of the Java platform. See The Extension Mechanism at
`http://docs.oracle.com/javase/8/docs/technotes/guides/extensions/index.html`

The class path needs to find any classes you have compiled with the `javac` compiler. The default is the current directory to conveniently enable those classes to be found.

The JDK, 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 about the search strategy, see How Classes Are Found at
`http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html`

Class libraries for most applications use the extensions mechanism. You only need to set the class path when you want to load a class that is (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 upgrade from an earlier release of the JDK, then your startup settings might include `CLASSPATH` settings that are no longer needed. You should remove any settings that are not application-specific, such as `classes.zip`. Some third-party applications that use the Java Virtual Machine (JVM) can modify your `CLASSPATH` environment variable to include the libraries they use. Such settings can remain.

You can change the class path by using the `-classpath` or `-cp` option of some Java commands when you call the JVM or other JDK tools or by using the `CLASSPATH` environment variable. See JDK Commands Class Path Options. Using the `-classpath` option is preferred over setting the `CLASSPATH` environment variable because you can set it individually for each application without affecting other applications and without other applications modifying its value. See CLASSPATH Environment Variable.

Classes can be stored in directories (folders) or in archive files. The Java platform classes are stored in rt.jar. For more details about archives and information about how the class path works, see Class Path and Package Names.

Note: Some earlier releases of the JDK had a `<jdk-dir>/classes` entry in the default class path. That directory exists for use by the JDK software and should not be used for application classes. Application classes should be placed in a directory outside of the JDK directory hierarchy. That way, installing a new JDK does not force you to reinstall application classes. For compatibility with earlier releases, applications that use the `<jdk-dir>/classes` directory as a class library run in the current release, but there is no guarantee that they will run in future releases.

## JDK Commands Class Path Options

The following commands have a `-classpath` option that replaces the path or paths specified by the `CLASSPATH` environment variable while the tool runs: `java`, `jdb`, `javac`, `javah` and `jdeps`.

The `-classpath` option 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 `java` command also has a `-cp` option that is an abbreviation for `-classpath`.

For very special cases, both the `java` and `javac` commands have options that let you change the path they use to find their own class libraries. Most users will never need to use those options.

## CLASSPATH Environment Variable

As explained in JDK Commands Class Path Options, the `-classpath` command-line option is preferred over the `CLASSPATH` environment variable. However, if you decide to use the `CLASSPATH` environment variable, this section explains how to set and clear it.

### Set CLASSPATH

In csh, the CLASSPATH environment variable is modified with the `setenv` command. The format is:

    setenv CLASSPATH path1:path2

In sh, the `CLASSPATH` environment variable can be modified with these commands:

    CLASSPATH = path1:path2:...
    export CLASSPATH

### Clear CLASSPATH

If your `CLASSPATH` environment variable was set to a value that is not correct, or if your startup file or script is setting an incorrect path, then you can unset `CLASSPATH` with:

    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 correct `CLASSPATH` settings in future sessions.

### Change Startup Settings

If the CLASSPATH variable is set at system startup, then the place to look for it depends on your operating system:

Windows 95 and 98: Examine `autoexec.bat` for the set command.

Other (Windows NT, Windows 2000, ...): The CLASSPATH environment variable can be set with the System utility in the Control Panel.

If the CLASSPATH variable is set at system startup, then the place to look for it depends on the shell you are running:

The `csh`, `tcsh` `shells`: Examine your `.cshrc` file for the `setenv` command.

The `sh`, `ksh` `shells`: Examine your `.profile` file for the `export` command.

## Class Path Wild Cards

Class path entries can contain the base name wildcard character (*), which is considered equivalent to specifying a list of all of the files in the directory with the extension `.jar` or `.JAR`. For example, the class path entry `mydir/*` specifies all JAR files in the directory named `mydir`. A class path entry consisting of * expands to a list of all the jar files in the current directory. Files are considered regardless of whether they are hidden (have names beginning with '.').

A class path entry that contains an asterisk (*) does not match class files. To match both classes and JAR files in a single directory `mydir`, use either `mydir:mydir/*` or `mydir/*:mydir`. The order chosen determines whether the classes and resources in `mydir` are loaded before JAR files in `mydir` or vice versa.

Subdirectories are not searched recursively. For example, `mydir/*` searches for JAR files only in `mydir`, not in `mydir/subdir1`, `mydir/subdir2`, and so on.

The order in which the JAR files in a directory are enumerated in the expanded class path is not specified and may vary from platform to platform and even from moment to moment on the same machine. A well-constructed application should not depend upon any particular order. If a specific order is required, then the JAR files can be enumerated explicitly in the class path.

Expansion of wild cards is done early, before the invocation of a program's main method, rather than late, during the class-loading process. Each element of the input class path that contains a wildcard is replaced by the (possibly empty) sequence of elements generated by enumerating the JAR files in the named directory. For example, if the directory `mydir` contains a.jar, b.jar, and c.jar, then the class path `mydir/*` is expanded into `mydir/a.jar:mydir/b.jar:mydir/c.jar`, and that string would be the value of the system property java.class.path.

The `CLASSPATH` environment variable is not treated any differently from the `-classpath` or `-cp` options. Wild cards are honored in all of these cases. However, class path wild cards are not honored in the Class-Path jar-manifest header.

## Class Path and Package Names

Java classes are organized into packages that 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 and never part of it. For example, the package name for `java.awt.Button` is always specified as `java.awt`.

For example, suppose you want the JRE to find a class named `Cool.class` in the package `utility.myapp`. If the path to that directory is `/java/MyClasses/utility/myapp`, then you would set the class path so that it contains `/java/MyClasses`. To run that application, you could use the following `java` command:

    java -classpath /java/MyClasses utility.myapp.Cool

When the application runs, the JVM uses the class path settings to find any other classes defined in the `utility.myapp` package that are used by the `Cool` class.

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 command `java myapp.Cool`. The class would not be found.

You might wonder 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.

An interesting consequence of the package specification mechanism is that files that are part of the same package can exist in different directories. The package name is the same for each class, but the path to each file might start from a different directory in the class path.

### Folders and Archive Files

When classes are stored in a directory (folder), such as `/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`, because the package name is utility.myapp).

When classes are stored in an archive file (a `zi` `p` or `JAR` file) the class path entry is the path to and including the zip or JAR file. For example, the command to use a class library that is in a `JAR` file as follows:

    java -classpath /java/MyClasses/myclasses.jar utility.myapp.Cool

### Multiple Specifications

To find class files in the directory `/java/MyClasses` and classes in `/java/OtherClasses`, you would set the class path to the following. Note that the two paths are separated by a colon.

    java -classpath /java/MyClasses:/java/OtherClasses ...

### 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 previous example, the Java interpreter will first look for a needed class in the directory `/java/MyClasses`. Only when it does not find a class with the proper name in that directory will the interpreter look in the `/java/OtherClasses` directory.

Contents Previous Next

Copyright © 1993, 2015, Oracle and/or its affiliates. All rights reserved.
Contact Us