skip to content

JAR Manifest, Multi-Release JARs

A JAR is a zip with a manifest, and the JDK itself reads that manifest when it starts and loads your code. Interviewers ask what it carries and how one JAR can hold classes for several Java releases.

part ofJavaread it →
on this pageshow

questions

2

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?

level: middleimportance: should knowfreq 46%

answer

  1. name-value text, main section first
  2. different JDK code reads each attribute
  3. launcher attributes apply only under -jar
  4. Class-Path resolves against the JAR itself
  5. -jar overwrites java.class.path

basics

~10 s

META-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 s

The 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 lines
java
import 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

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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

open as a page

What is a Java multi-release JAR, how do META-INF/versions and the Multi-Release attribute select classes, and when is it worth using over separate artifacts?

level: seniorimportance: nice to knowfreq 24%

basics

~20 s

A multi-release JAR, added in Java 9, carries Multi-Release: true and class overlays under META-INF/versions/N. The runtime loads the highest N not above its own release, else the root copy. Use it for small version-specific internals behind one API.

open as a page