ClassGraph is a fast classpath scanner and module scanner for JVM languages, enabling lightweight metaprogramming in JVM languages: the ability to write code that analyzes or responds to the properties of other code.

• ClassGraph API
• The five libraries
• Downloading/Building
• Reading the classpath of a hidden classloader
• Use with maven-shade-plugin
• Use as a module

• Start here:
  • Code examples
  • ClassGraph API overview
  • Recipes -- over sixty worked examples, from setting up a scan to reading jarfiles without scanning
• Additional documentation:
  • JavaDoc
  • Porting ClassGraph 4.x code to ClassGraph 5.x
  • Classpath specification mechanisms -- what ClassGraph can find, and where
  • Build-time scanning -- scanning in Maven or Gradle, for Android, and for GraalVM native-image
  • How fast is ClassGraph?
  • Memory mapping benchmark -- why ClassGraph memory-maps jarfiles on Windows and not anywhere else
  • Shading ClassGraph

ClassGraph is published as five Maven artifacts, each of which is also a Java module. Each artifact depends on the one above it in this table, so a project needs only the dependency for the widest part of ClassGraph it uses:

Depending on classgraph therefore brings in classgraph-classpath, classgraph-vfs and classgraph-base too, and that is all most projects need. Replace X.Y.Z with the latest release number:

<dependency>
    <groupId>io.github.classgraph</groupId>
    <artifactId>classgraph</artifactId>
    <version>X.Y.Z</version>
</dependency>

The two lower libraries can also be used on their own, without scanning anything: classgraph-classpath finds the classpath and the module path of the running JVM, and classgraph-vfs reads directories, jarfiles and modules -- including jarfiles nested inside other jarfiles to any depth -- through one read-only virtual filesystem.

classgraph-base exports only two types, ClassGraphLog and LogNode, which together are the verbose log that ClassGraph writes to and hands to any code it calls out to, such as a ClassLoaderHandler. It is rarely named directly by a project that uses ClassGraph -- it is listed here mostly because it appears in dependency trees.

See the GitHub project homepage for downloading/building instructions.

The JDK enforces strong encapsulation, which means that ClassGraph may not be able to find the classpath of your project, if all of the following are true:

• You are using a legacy classloader (rather than the module system)
• The legacy classloader does not expose its classpath via a public field or method
• The classloader is loaded in a different module from your user code

If ClassGraph cannot find your classes, and the classes are loaded by a classloader like this, you have probably run into this problem.

ClassGraph can use the library Narcissus (also by the ClassGraph author) to circumvent Java's access checks and strong encapsulation, in order to read the classpath from private fields and methods of classloaders. Narcissus reads fields and invokes methods through JNI, which is not subject to Java's access controls.

To use Narcissus, add it to your project as an extra dependency, with X.Y.Z replaced by the latest Narcissus release number:

<dependency>
    <groupId>io.github.toolfactory</groupId>
    <artifactId>narcissus</artifactId>
    <version>X.Y.Z</version>
</dependency>

ClassGraph looks Narcissus up reflectively, and uses it automatically if it is present -- there is nothing to configure. If it is not present, or its native library cannot be loaded, ClassGraph falls back to ordinary reflection.

Two caveats:

• Narcissus includes a native library, and only Linux x86/x64, Windows x86/x64 and macOS x64 are currently supported. (Feel free to contribute native code builds for other platforms or architectures.)
• To avoid the warning WARNING: java.lang.System::load has been called by io.github.toolfactory.narcissus.LibraryLoader in an unnamed module on the commandline, add --enable-native-access=ALL-UNNAMED to your JVM launch arguments. The JDK always warns when a native library is loaded without this argument.

If you need Narcissus to read your classpath, please ask the maintainers of your runtime environment to expose the full classpath from their classloader using a public method or field, otherwise ClassGraph may stop working for that runtime environment in future.

If you use ClassGraph with maven-shade-plugin, you need to shade io.github.classgraph..

Every ClassGraph jarfile includes a module-info.class file, which means it can be added to your project as a Java module. If you are calling ClassGraph from code in a named module, ClassGraph must be added to the module path as a module, rather than included in the traditional classpath (you can't call non-modular code from modular code).

To use ClassGraph as a Java module, add the jar dependency to your project's module path, then add the following to your module-info.java:

requires io.github.classgraph;

The io.github.classgraph module requires the classpath finder, the archive reader and the shared internals transitively, so this one requires clause is all that is needed. If you are using the GraphViz library, requires io.github.classgraph.viz; transitively requires io.github.classgraph in turn, so it can replace the clause above.

If when trying to run your code, you get the following exception, the problem is that the code you are trying to run is modular, but the ClassGraph jar was added to the regular classpath, not the module path, or vice versa:

java.lang.NoClassDefFoundError: io/github/classgraph/ClassGraph

In this case, if you manually added the ClassGraph jar to an Eclipse project, go to Project Properties > Java Build Path > Libraries > Classpath > classgraph-X.Y.Z.jar, open the dropdown, double click on Is not modular, and check the box at the top, Defines one or more modules, then OK, then Apply and Save.

If you are launching from the commandline, make sure both your project and ClassGraph are on the module path, not the classpath.

The Java Platform Module System enforces strict encapsulation on both classes and resources. ClassGraph reads classfiles directly, so to some degree it can get around visibility restrictions, as long as the module exports the package that the classfile is contained within, since classfiles are just like any other files from the point of view of listing resources. If the classfile can be read, even if the class itself is non-public or its fields or methods are non-public, ClassGraph can still build ClassInfo, FieldInfo and MethodInfo objects, as long as you call ClassGraph#ignoreClassVisibility(), ClassGraph#ignoreFieldVisibility() and/or ClassGraph#ignoreMethodVisibility() before starting the scan.

Note also that ClassGraph uses reflective access (often to private fields and/or methods) to get the classpath URLs and paths from classloaders. If a classloader is in a module that is not open to ClassGraph, this can fail; see Reading the classpath of a hidden classloader above.

So the "tl;dr" version is:

1. If you want ClassGraph to be able to scan classfiles or resources in a package, the package or the module must be exported, either to ClassGraph or to the world.
2. If ClassGraph cannot read your classpath from your classloader, you need to open the module containing your classloader to ClassGraph, or add Narcissus to your project.

Your options for opening the module or package to ClassGraph or to the world, given a module name of your.module and a package name of your.pkg, are:

1. Open the entire module for reflection:

  open module your.module {
      requires io.github.classgraph;
  }

2. Open only selected package(s) for reflection:

  module your.module {
      requires io.github.classgraph;
      opens your.pkg;
  }

3. Open selected package(s) to ClassGraph specifically:

  module your.module {
      requires io.github.classgraph;
      opens your.pkg to io.github.classgraph;
  }