Run jdeprscan, the static analysis tool that ships with the JDK. It scans a jar, a directory of class files or a single class for uses of deprecated Java SE APIs. It only reports APIs defined by Java SE itself, so library deprecations need another check.
What the tool is
The Oracle documentation for Java SE 21 describes jdeprscan as a static analysis tool that scans a jar file or other aggregation of class files for uses of deprecated API elements. The arguments can be a directory, a jar, or a class name or class file.
Two limits are stated in the same page. First, the deprecated APIs it reports are only those defined by Java SE. Deprecated APIs defined by third party libraries are not reported. Second, the scanned classes must have their dependencies on the class path, or it prints an error for each missing class.
Running it
A basic scan of one jar:
jdeprscan my-service.jar
To resolve dependencies, pass the same class path your application uses:
jdeprscan --class-path "libs/*" my-service.jar
To focus on what will actually disappear, limit the scan to APIs deprecated for removal:
jdeprscan --for-removal --class-path "libs/*" my-service.jar
The documentation lists a list option too, which prints the set of deprecated APIs without scanning anything. The output names the class that uses the deprecated element and the element itself, in internal slash separated form.
| Option | Use |
|---|---|
| class path option | Make dependent classes resolvable |
| for-removal option | Show only APIs marked for removal |
| list option | Print deprecated APIs, no scan |
| verbose option | Extra output during processing |
Reading the results
Not all findings are equal. Sort them:
- Deprecated for removal and in your own code: fix first, since a future JDK will break the build or the runtime.
- Deprecated for removal and inside a dependency: check for a newer release of that dependency.
- Plain deprecations in your own code: schedule them, they are usually easy.
- Plain deprecations in dependencies: note and monitor, since the dependency owner has to act.
Scanning your jar and your dependency jars separately makes ownership clear. A finding in a library you do not control becomes a ticket for an upgrade or an issue upstream.
What jdeprscan does not cover
The tool looks at API usage. It does not tell you about behavior changes that keep the same signature, such as stronger encapsulation of JDK internals or changed defaults. Those need a test run on the new JDK. Treat jdeprscan as one input beside running your tests on the target JDK in a branch and reading release notes for that version.
It also does not tell you about security. A clean scan says nothing about whether a dependency carries a known vulnerability.
A short upgrade routine
- Build your artifact and collect its dependency jars.
- Run jdeprscan with the for-removal option and save the output.
- Fix or ticket each finding, with owners.
- Run the test suite on the target JDK.
- Repeat the scan against the target release and compare.
Quick check
Does jdeprscan report deprecated methods in my third party libraries?
No. It reports deprecated Java SE APIs only. Library deprecations need other checks.
Why do I see cannot find class errors?
The scanned classes depend on classes missing from the class path. Pass the application class path.
Safeguard covers the dependency side with SBOM generation and vulnerability scanning for Java projects. Try the free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
