When programming in Java, you make other classes available to the class you are writing by putting something like this at the top of your source file:

import org.javaguy.coolframework.MyClass;

Or sometimes you 'bulk import' stuff by saying:

import org.javaguy.coolframework.*;

So later in your program when you say:

MyClass mine = new MyClass();

The Java Virtual Machine will know where to find your compiled class.

It would be impractical to have the VM look through every folder on your machine, so you have to provide the VM a list of places to look. This is done by putting folder and jar files on your classpath.

Before we talk about how the classpath is set, let's talk about .class files, packages, and .jar files.

First, let's suppose that MyClass is something you built as part of your project, and it is in a directory in your project called output. The .class file would be at output/org/javaguy/coolframework/MyClass.class (along with every other file in that package). In order to get to that file, your path would simply need to contain the folder 'output', not the whole package structure, since your import statement provides all that information to the VM.

Now let's suppose that you bundle CoolFramework up into a .jar file, and put that CoolFramework.jar into a lib directory in your project. You would now need to put lib/CoolFramework.jar into your classpath. The VM will look inside the jar file for the org/javaguy/coolframework part, and find your class.

So, classpaths contain:

• JAR files, and
• Paths to the top of package hierarchies.

How do you set your classpath?

The first way everyone seems to learn is with environment variables. On a unix machine, you can say something like:

export CLASSPATH=/home/myaccount/myproject/lib/CoolFramework.jar:/home/myaccount/myproject/output/

On a Windows machine you have to go to your environment settings and either add or modify the value that is already there.

The second way is to use the -cp parameter when starting Java, like this:

java -cp "/home/myaccount/myproject/lib/CoolFramework.jar:/home/myaccount/myproject/output/"  MyMainClass

A variant of this is the third way which is often done with a .sh or .bat file that calculates the classpath and passes it to Java via the -cp parameter.

There is a "gotcha" with all of the above. On most systems (Linux, Mac OS, UNIX, etc) the colon character (:) is the classpath separator. On Windows the separator is the semicolon (;)

So what's the best way to do it?

Setting stuff globally via environment variables is bad, generally for the same kinds of reasons that global variables are bad. You change the CLASSPATH environment variable so one program works, and you end up breaking another program.

The -cp is the way to go. I generally make sure my CLASSPATH environment variable is an empty string where I develop, whenever possible, so that I avoid global classpath issues (some tools aren't happy when the global classpath is empty though - I know of two common, mega-thousand dollar licensed J2EE and Java servers that have this kind of issue with their command-line tools).

I'm not a Java programmer, so I don't know the correct value for CLASSPATH. But, you seem to. You can add it to ~/.bashrc like so:

CLASSPATH=/path/to/1:/path/to/2:/etc

The change will take effect globally the next time you log in. However, it will take effect immediately in new shells.

Additionally, if you want to set it for just one particular command, do this:

CLASSPATH=/something command-here arg1 arg2

A third way would be to create a wrapper script, which would be appropriate if you needed to set multiple variables or if you needed to determine appropriate values programmatically:

#!/bin/bash
export CLASSPATH=/something
export ANOTHER_ENV_Variable=foo

exec your_fancy_program "$@"

Update 2023: as commented below by Holger

The only way to add jar files to the class path working in Java 9 and newer, is through the Instrumentation API, but it requires a Java Agent.

If you are in control of the launcher/main jar, you can use the Launcher-Agent-Class attribute in the jar file’s manifest to start an embedded Agent.

Update Q4 2017: as commented below by vda8888, in Java 9, the System java.lang.ClassLoader is no longer a java.net.URLClassLoader.

See "Java 9 Migration Guide: The Seven Most Common Challenges"

The class loading strategy that I just described is implemented in a new type and in Java 9 the application class loader is of that type.
That means it is not a URLClassLoader anymore, so the occasional (URLClassLoader) getClass().getClassLoader() or (URLClassLoader) ClassLoader.getSystemClassLoader() sequences will no longer execute.

java.lang.ModuleLayer would be an alternative approach used in order to influence the modulepath (instead of the classpath). See for instance "Java 9 modules - JPMS basics".

For Java 8 or below:

Some general comments:

you cannot (in a portable way that's guaranteed to work, see below) change the system classpath. Instead, you need to define a new ClassLoader.

ClassLoaders work in a hierarchical manner... so any class that makes a static reference to class X needs to be loaded in the same ClassLoader as X, or in a child ClassLoader. You can NOT use any custom ClassLoader to make code loaded by the system ClassLoader link properly, if it wouldn't have done so before. So you need to arrange for your main application code to be run in the custom ClassLoader in addition to the extra code that you locate.
(That being said, cracked-all mentions in the comments this example of extending the URLClassLoader)

And you might consider not writing your own ClassLoader, but just use URLClassLoader instead. Create a URLClassLoader with a url that are not in the parent classloaders url's.

URL[] url={new URL("file://foo")};
URLClassLoader loader = new URLClassLoader(url);

A more complete solution would be:

ClassLoader currentThreadClassLoader
 = Thread.currentThread().getContextClassLoader();

// Add the conf dir to the classpath
// Chain the current thread classloader
URLClassLoader urlClassLoader
 = new URLClassLoader(new URL[]{new File("mtFile").toURL()},
                      currentThreadClassLoader);

// Replace the thread classloader - assumes
// you have permissions to do so
Thread.currentThread().setContextClassLoader(urlClassLoader);

If you assume the JVMs system classloader is a URLClassLoader (which may not be true for all JVMs), you can use reflection as well to actually modify the system classpath... (but that's a hack;)):

public void addURL(URL url) throws Exception {
  URLClassLoader classLoader
         = (URLClassLoader) ClassLoader.getSystemClassLoader();
  Class clazz= URLClassLoader.class;

  // Use reflection
  Method method= clazz.getDeclaredMethod("addURL", new Class[] { URL.class });
  method.setAccessible(true);
  method.invoke(classLoader, new Object[] { url });
}

addURL(new File("conf").toURL());

// This should work now!
Thread.currentThread().getContextClassLoader().getResourceAsStream("context.xml");

A complete (coded) solution would be a bit beyond a single Stack Overflow answer, so I'll outline the points you need to be aware of instead if you decide to write your own ClassLoader:

1. The classloader represents (part of) a namespace, and two otherwise identical classes loaded by different classloaders are not "equal". Which means there are a few dangers lurking in classloading, notably singletons suddenly not being so single anymore as well as casts failing unexpectedly.
2. Classloaders (should) work on a pattern of delegating to the "parent" loader before attempting anything themselves (see above).
3. Class loading and linking are two distinct steps (even though example implementations of a classloader such as may be found in blog posts/online Java articles, will combine the two into one for simplicity) Therefore you should not assume that if a parent loader has loaded a class it has also loaded all dependencies ...
4. All this means there is a problem if class A loaded by loader A references a class B which neither loader A nor any of its parents can load: class A may load just fine in loader A but at the point of use it fails because loader A cannot fully resolve (link) it.
5. And you should make sure that your classloader loads classes in a synchronized manner otherwise the issues hinted at in step #1 can leap from duplicates due to classloaders to duplicates from multiple threads using the same classloader as well...

Note: it is far easier to just use the -cp switch in some wrapper script/batch file for your program.