What goes in a JAR's META-INF/MANIFEST.MF, what in the JDK reads each attribute, and when does java -jar ignore your -cp?
answer
- name-value text, main section first
- different JDK code reads each attribute
- launcher attributes apply only under -jar
- Class-Path resolves against the JAR itself
- -jar overwrites java.class.path
basics
~10 sMETA-INF/MANIFEST.MF holds name-value attributes about the JAR, and different JDK code reads them: the launcher reads Main-Class and Add-Opens, the class path loader Class-Path, JarFile Multi-Release, module lookup Automatic-Module-Name. java -jar always ignores -cp.
solid answer
~40 sThe manifest is a text file of `Name: value` attributes: a main section about the whole JAR, then optional per-entry sections. Different JDK code reads each attribute. `sun.launcher.LauncherHelper` reads `Main-Class` and `Add-Opens`, along with `Add-Exports` and `Enable-Native-Access`, only under `java -jar` and only from that JAR. `URLClassPath`, JDK-internal, follows `Class-Path` in any class path JAR, resolving entries against that JAR's location. `JarFile` checks `Multi-Release`. The module path code reads `Automatic-Module-Name` when the JAR has no `module-info.class`. And `-jar` ignores `-cp` and `CLASSPATH` every time: the native launcher replaces the class path with the JAR, without a warning. To add libraries, use `Class-Path`, or run `java -cp 'app.jar:lib/*' app.Main`, which loses the launcher-read attributes, so pass `--add-opens` yourself.
code
java · 20 linesimport java.util.jar.Attributes;
import java.util.jar.JarFile;
import java.util.jar.Manifest;
public class ManifestDump {
public static void main(String[] args) throws Exception {
try (JarFile jar = new JarFile(args[0])) {
Manifest manifest = jar.getManifest();
if (manifest == null) {
System.out.println("no manifest");
return;
}
Attributes main = manifest.getMainAttributes();
System.out.println("Main-Class = " + main.getValue(Attributes.Name.MAIN_CLASS));
System.out.println("Class-Path = " + main.getValue(Attributes.Name.CLASS_PATH));
System.out.println("Add-Opens = " + main.getValue("Add-Opens"));
System.out.println("isMultiRelease = " + jar.isMultiRelease());
}
}
}go deeper
Recall that a JAR is a ZIP with META-INF/MANIFEST.MF, that Main-Class is what makes java -jar work, and that -cp has no effect once you use -jar.
Explain which JDK code reads each attribute and when: launcher attributes only under java -jar, Class-Path for any class path JAR relative to that JAR, Automatic-Module-Name only on the module path.
Show you can diagnose startup failures from this: a dependency lost because -jar dropped -cp, Add-Opens placed in a library JAR, a Class-Path typo that surfaces late as ClassNotFoundException, a manifest missing its final newline.
Weigh how a team launches its applications: -jar with a manifest keeps settings inside the artifact, while an explicit class path and flags keep them in the deploy script. Either works, so pick one and give overrides a single home.
## What the manifest is A **JAR** is a ZIP archive with a conventional entry, `META-INF/MANIFEST.MF`, that describes the archive. The manifest is a text file of `Name: value` attributes grouped into sections: - The **main section** comes first and describes the JAR as a whole. It ends at an empty line. - **Individual sections** follow, each opening with a `Name:` attribute that names an entry. They hold per-entry data such as `Sealed` or a signature digest. - No line may exceed **72 bytes**. A longer value continues on the next line, which starts with one space, and the `jar` tool wraps lines for you. - Attribute names are case-insensitive. ```text Manifest-Version: 1.0 Main-Class: app.Main Class-Path: lib/dep.jar Add-Opens: java.base/java.lang ``` ## Who reads which attribute The manifest does nothing by itself. An attribute has an effect only if some JDK code looks for it, and each reader has its own conditions. | Attribute | What it says | Reader | When it takes effect | |---|---|---|---| | `Main-Class` | The class to launch | `sun.launcher.LauncherHelper`, private `getMainClassFromJar` | `java -jar`; it also becomes an automatic module's main class | | `Class-Path` | More JARs or directories to search | `jdk.internal.loader.URLClassPath` | Any JAR on the class path, followed transitively | | `Multi-Release` | The JAR holds versioned classes | `java.util.jar.JarFile`, private `checkForSpecialAttributes` | Read by any `JarFile`, but it selects classes only in one opened with a runtime version, as the class loaders open JARs; main section only | | `Add-Opens`, `Add-Exports` | Open or export a module's package to class path code | `LauncherHelper` | `java -jar` only, and only from that JAR | | `Automatic-Module-Name` | The module's name | `jdk.internal.module.ModulePath`, and `javac` | On the module path, when the JAR has no `module-info.class` | The launcher also reads `Launcher-Agent-Class`, `Enable-Native-Access` and, since JDK 26, `Enable-Final-Field-Mutation`, which JDK 25's launcher does not read. Package-versioning attributes such as `Implementation-Version` reach `java.lang.Package` through the built-in class loaders. Agent JARs have attributes of their own, covered with Java agents. ## Why java -jar ignores -cp `-jar` ignores `-cp`, `--class-path` and the `CLASSPATH` variable **every time**, with no warning. A launch runs in this order: 1. The native launcher parses the options, then replaces the class path with the JAR. 2. `LauncherHelper` opens the JAR, reads `Main-Class` and applies `Add-Opens` and the other launcher attributes. 3. The system class loader loads the main class, following `Class-Path` as it searches. So a program started this way sees only the JAR: ```text $ CLASSPATH=/x java -cp /y -jar app.jar java.class.path=app.jar (as printed by the program) ``` There are two ways to add libraries: - Put them in `Class-Path` inside the JAR's manifest. - Leave `-jar` out and name the class: `java -cp 'app.jar:lib/*' app.Main`. The second changes more than the class path. Without `-jar`, `LauncherHelper` never reads the manifest, so `Main-Class` goes unused and `Add-Opens` is not applied. Reflection into private members of `java.lang` classes then throws `InaccessibleObjectException` until you pass `--add-opens java.base/java.lang=ALL-UNNAMED` yourself. ## Rules that surprise people - **`Class-Path` resolves against the JAR**, not the working directory. Entries are space-separated relative URLs, and running from another directory still finds them. - **Invalid or missing `Class-Path` entries are ignored.** A typo therefore surfaces later, as `ClassNotFoundException` or `NoClassDefFoundError`, and not at startup. - **An automatic module's `Class-Path` is not followed**, so a JAR that works under `-jar` can lose its libraries when moved to the module path. - **Launcher attributes in a dependency JAR do nothing.** JEP 261 limits `Add-Opens` to the JAR named by `-jar`, so a library cannot open packages for itself this way. - **A bad `Add-Opens` pair is dropped silently**, whereas `Enable-Native-Access` with any value but `ALL-UNNAMED` aborts startup with an error. - **The last line needs a newline.** The manifest reader drops an unterminated final line, so `jar cfm` succeeds on `Main-Class: app.Main` with no newline, and `java -jar` then prints `no main manifest attribute, in app.jar`. - **`Automatic-Module-Name` has no use on the class path**, where all code sits in the unnamed module. - **`java -jar` puts even a modular JAR on the class path.** Its `module-info.class` is not used. ## Checking a JAR Read the actual manifest before trusting a build script: `unzip -p app.jar META-INF/MANIFEST.MF` prints it, including how the tool wrapped long lines. In code, `JarFile.getManifest()` and `Attributes.Name` give the same data, and the example below prints the attributes that matter here.
- You switch from `java -jar app.jar` to `java -cp 'app.jar:lib/*' app.Main`, and reflective access starts failing. Why, and what is the fix?Without `-jar`, `LauncherHelper` never reads the manifest, so `Add-Opens` in `app.jar` is not applied, and `setAccessible` on a private member of a `java.lang` class throws `InaccessibleObjectException`. Pass the same request on the command line: `--add-opens java.base/java.lang=ALL-UNNAMED`. `Add-Exports` and `Enable-Native-Access` likewise have their own launcher options.
- Your manifest input file has a `Main-Class` line, yet `java -jar` prints `no main manifest attribute`. What is the likely cause?The line probably has no trailing newline. The manifest reader drops an unterminated final line without an error, so `jar cfm` succeeds and the attribute never reaches the JAR. End the file with a newline and rebuild, or use `jar --main-class`, then check the result with `unzip -p app.jar META-INF/MANIFEST.MF`.
- What happens when you run a modular JAR, one with `module-info.class`, using `java -jar`?It runs on the class path, in the unnamed module, because `-jar` makes the JAR the class path. Its `module-info.class` is not used, so its `requires` and `exports` are not applied. To run it as a module, use `java -p <path> -m <module>`. Module resolution itself belongs with the module system.
A manifest works like the label on a parcel: each handler reads only its own line. The launcher reads the delivery line, the class path loader reads the also-collect line, and a line meant for a handler who is not on this route is never read, so it does nothing.
- -cp entries are added to the JAR's Class-Path when you run java -jar.
- Add-Opens in any JAR on the class path opens the package.
- Class-Path entries resolve against the current working directory.
- A missing Class-Path target stops the JVM at startup.
- Automatic-Module-Name gives a JAR a module name on the class path too.
- java -cp app.jar starts the manifest's Main-Class without naming a class.
- Main-Class manifest attribute
- Java 1.2
- Class-Path manifest attribute
- Java 1.2
- Multi-Release manifest attribute
- Java 9
- Add-Opens manifest attribute
- Java 9
- Automatic-Module-Name manifest attribute
- Java 9
Assumes Java 27; Enable-Final-Field-Mutation is read since JDK 26, and JDK 25's launcher does not read it.
context
- JAR File Specificationdocs.oracle.com
- The java Commanddocs.oracle.com
- LauncherHelper.java at jdk-27-gagithub.com