Go back

META-INF: The Hidden Directory That Has Been Running Your Java App All Along

Published on March 8, 2026 • 13 min read

Tags:
General TopicJava

META-INF: The Hidden Directory That Powers Every Java Application

"It's always there. You've seen it a hundred times. But do you actually know what it does?"

Every Java developer has encountered META-INF. It appears silently inside every JAR, WAR, and EAR file you've ever opened. Most developers ignore it. A few know about MANIFEST.MF. Almost nobody knows the full story.

This post is the full story.

What Exactly Is META-INF?

META-INF is a reserved, special-purpose directory inside Java archive files. The JVM and frameworks like Spring Boot treat it as a first-class citizen — they read it before loading a single class from your application.

Think of it this way:

📦 A JAR file is like a shipping container
   📄 Your classes and resources = the cargo
   📋 META-INF/ = the shipping manifest on the outside
      → What's inside
      → Who packed it
      → Special handling instructions
      → Authentication seals

Since a JAR is technically just a ZIP file, you can unzip any JAR and inspect it directly:

unzip myapp.jar -d myapp-contents
 
# Result:
myapp-contents/
├── com/example/Main.class
├── com/example/Calculator.class
├── resources/application.properties
└── META-INF/
    ├── MANIFEST.MF
    ├── services/
    ├── maven/
    └── spring.factories

The JVM reads META-INF before loading any of your classes. It is the bootstrap layer of your entire application.

Why Does META-INF Exist?

Before META-INF, Java had a fundamental problem. When you have 50 JARs in an application, how does the JVM answer these questions?

  • Which class has the main() entry point?
  • Which external JARs does this JAR depend on?
  • Who built this JAR, and what version is it?
  • Has this JAR been tampered with?
  • Does this JAR provide any plugins or services?

There was no standardized answer. META-INF was created to be exactly that — a standardized, machine-readable contract between a JAR and the environment running it.

Usage 1: MANIFEST.MF — Making JARs Executable

The most important file in all of META-INF. Every JAR has one, and without it configured correctly, you get the most classic Java error of all time:

no main manifest attribute, in myapp.jar

Every Java developer has seen this. It means the JVM opened META-INF/MANIFEST.MF, looked for Main-Class, and found nothing.

A Complete MANIFEST.MF

Manifest-Version: 1.0
Created-By: 17.0.1 (Oracle Corporation)
Built-By: Alice
Build-Date: 2026-03-08
 
Main-Class: com.example.Main
Class-Path: libs/gson-2.10.jar libs/commons-lang3.jar
 
Implementation-Title: My Application
Implementation-Version: 2.5.1
Implementation-Vendor: Example Corp

Here is what each entry does:

Main-Class — The single most important entry. When you run java -jar myapp.jar, the JVM does exactly this:

Class mainClass = Class.forName("com.example.Main");
Method main = mainClass.getMethod("main", String[].class);
main.invoke(null, args);

Class-Path — Space-separated list of external JARs, relative to where the JAR lives. If your JAR is at /opt/myapp/myapp.jar, the JVM looks for /opt/myapp/libs/gson-2.10.jar.

Implementation-Version — Maps to Package.getImplementationVersion() at runtime. Critical for version reporting and health checks.

Reading MANIFEST.MF at Runtime

public class ManifestReader {
    public static String getVersion() throws Exception {
        String className = ManifestReader.class.getSimpleName() + ".class";
        String classPath = ManifestReader.class.getResource(className).toString();
 
        String manifestPath = classPath
            .substring(0, classPath.lastIndexOf("!") + 1)
            + "/META-INF/MANIFEST.MF";
 
        Manifest manifest = new Manifest(new URL(manifestPath).openStream());
        Attributes attrs = manifest.getMainAttributes();
 
        return attrs.getValue("Implementation-Version");
    }
}

Maven Automates All of This

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jar-plugin</artifactId>
  <configuration>
    <archive>
      <manifest>
        <mainClass>com.example.Main</mainClass>
        <addClasspath>true</addClasspath>
        <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
      </manifest>
      <manifestEntries>
        <Build-Date>${maven.build.timestamp}</Build-Date>
        <Built-By>${user.name}</Built-By>
      </manifestEntries>
    </archive>
  </configuration>
</plugin>

Maven generates and writes the MANIFEST.MF for you at build time. You never have to touch the file manually.

Usage 2: META-INF/services/ — The Plugin System (SPI)

This is where META-INF goes from "useful" to "architectural". The services/ directory is the foundation of Java's Service Provider Interface (SPI) — the mechanism that lets JARs advertise implementations without any central registry or hardcoded wiring.

The Problem SPI Solves

Consider a document export system:

The naive approach — hardcoded and fragile
public void export(Document doc, String format) {
    if (format.equals("PDF"))  { new PdfExporter().export(doc);  }
    if (format.equals("WORD")) { new WordExporter().export(doc); }
    if (format.equals("HTML")) { new HtmlExporter().export(doc); }
    // Adding a new format requires changing this class every time.
    // What if exporters live in separate teams or separate JARs?
}

Every new format means modifying the core class. This violates the Open/Closed Principle and makes the system impossible to extend externally.

The SPI Solution

core.jar          → defines the interface
pdf-plugin.jar    → registers PDF implementation via META-INF/services/
word-plugin.jar   → registers Word implementation via META-INF/services/

Adding a new format = drop a new JAR on the classpath.
The core class never changes.

Full Implementation

Step 1: Define the interface in your core module

package com.example.core;
 
public interface DocumentExporter {
    String getFormatName();
    String getFileExtension();
    boolean supports(String format);
    byte[] export(Document document) throws Exception;
}

Step 2: Implement it in a separate plugin JAR

package com.example.pdf;
 
public class PdfExporter implements DocumentExporter {
 
    @Override public String getFormatName()    { return "PDF"; }
    @Override public String getFileExtension() { return "pdf"; }
 
    @Override
    public boolean supports(String format) {
        return "PDF".equalsIgnoreCase(format);
    }
 
    @Override
    public byte[] export(Document document) throws Exception {
        // Use iText or Apache PDFBox in production
        System.out.println("Exporting as PDF...");
        return buildPdfBytes(document);
    }
}

Step 3: Register the implementation in META-INF

# File: pdf-plugin.jar → META-INF/services/com.example.core.DocumentExporter

com.example.pdf.PdfExporter

The filename is the fully-qualified interface name. The content is a list of implementation classes, one per line.

Step 4: Discover all implementations at runtime

public class ExportEngine {
 
    public byte[] export(Document doc, String format) throws Exception {
        ServiceLoader<DocumentExporter> loader =
            ServiceLoader.load(DocumentExporter.class);
 
        for (DocumentExporter exporter : loader) {
            if (exporter.supports(format)) {
                return exporter.export(doc);
            }
        }
 
        throw new UnsupportedOperationException(
            "No exporter registered for format: " + format
        );
    }
}

ServiceLoader automatically scans every JAR on the classpath for META-INF/services/com.example.core.DocumentExporter and instantiates all registered implementations. Zero hardcoding. Zero reflection hacks.

Usage 3: JDBC Driver Auto-Registration

This is SPI in action in the Java standard library itself, and most developers have been using it for years without knowing.

When you write this:

Connection conn = DriverManager.getConnection(
    "jdbc:postgresql://localhost:5432/mydb", "user", "pass"
);

You never registered the PostgreSQL driver. You never called Class.forName(). It just works. Here is why.

Inside postgresql.jar:

META-INF/services/java.sql.Driver
→ org.postgresql.Driver

On JVM startup, DriverManager runs:

ServiceLoader<Driver> loader = ServiceLoader.load(Driver.class);
// Scans all JARs → finds META-INF/services/java.sql.Driver
// Instantiates org.postgresql.Driver
// Driver's static initializer registers it with DriverManager

By the time your code runs, the driver is already registered. Every major database does the same:

mysql-connector.jar    → META-INF/services/java.sql.Driver → com.mysql.cj.jdbc.Driver
postgresql.jar         → META-INF/services/java.sql.Driver → org.postgresql.Driver
h2.jar                 → META-INF/services/java.sql.Driver → org.h2.Driver
sqlite.jar             → META-INF/services/java.sql.Driver → org.sqlite.JDBC

Add the JAR. Get the driver. META-INF did the rest.

Usage 4: Spring Boot Auto-Configuration

This is the most impactful use of META-INF in the modern Java ecosystem. It is the mechanism behind @SpringBootApplication and the reason adding a dependency to pom.xml "just works".

When Spring Boot starts, it reads one file from every JAR on the classpath:

META-INF/spring.factories

This file maps configuration trigger points to auto-configuration classes. Spring Boot uses this to discover and conditionally apply configuration without any user intervention.

Building a Custom Spring Boot Starter

Let's build a rate-limiting starter from scratch to see exactly how this works.

The core service:

public class RateLimiter {
    private final int maxRequests;
    private final int windowSeconds;
    private final ConcurrentHashMap<String, AtomicInteger> counts
        = new ConcurrentHashMap<>();
 
    public RateLimiter(int maxRequests, int windowSeconds) {
        this.maxRequests   = maxRequests;
        this.windowSeconds = windowSeconds;
    }
 
    public boolean isAllowed(String clientId) {
        AtomicInteger count = counts.computeIfAbsent(
            clientId, k -> new AtomicInteger(0)
        );
        return count.incrementAndGet() <= maxRequests;
    }
}

The properties class — maps application.properties keys to a Java object:

@ConfigurationProperties(prefix = "mylib.ratelimit")
public class RateLimitProperties {
    private int    maxRequests   = 100;  // sensible default
    private int    windowSeconds = 60;   // sensible default
    private boolean enabled      = true;
 
    // getters and setters
}

The auto-configuration class — wires everything together conditionally:

@Configuration
@ConditionalOnClass(RateLimiter.class)
@ConditionalOnProperty(
    prefix = "mylib.ratelimit",
    name = "enabled",
    havingValue = "true",
    matchIfMissing = true
)
@ConditionalOnMissingBean(RateLimiter.class)
@EnableConfigurationProperties(RateLimitProperties.class)
public class RateLimitAutoConfiguration {
 
    @Bean
    public RateLimiter rateLimiter(RateLimitProperties props) {
        return new RateLimiter(props.getMaxRequests(), props.getWindowSeconds());
    }
}

The META-INF registration — the key that makes it a starter:

# META-INF/spring.factories
 
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  com.mylib.ratelimit.RateLimitAutoConfiguration

Now any application that adds your library gets RateLimiter auto-configured. The user's entire integration is:

<dependency>
    <groupId>com.mylib</groupId>
    <artifactId>ratelimit-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
# Optional — only needed to override defaults
mylib.ratelimit.max-requests=50
mylib.ratelimit.window-seconds=30

That is the entire setup. META-INF/spring.factories did the rest.

Note: Spring Boot 2.7+ introduced a new format at META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports, but spring.factories remains widely supported.

Usage 5: Runtime Version Reporting

The META-INF/maven/ directory contains metadata generated automatically by Maven at build time. This is invaluable for runtime diagnostics and health check endpoints.

META-INF/maven/com.example/myapp/pom.properties

groupId=com.example
artifactId=myapp
version=2.5.1

Building a Production-Grade Version Endpoint

public class VersionInfo {
 
    private static final Properties MAVEN_PROPS  = new Properties();
    private static Attributes       MANIFEST_ATTRS;
 
    static {
        // Load from META-INF/maven/
        try (InputStream is = VersionInfo.class.getResourceAsStream(
                "/META-INF/maven/com.example/myapp/pom.properties")) {
            if (is != null) MAVEN_PROPS.load(is);
        } catch (Exception ignored) {}
 
        // Load from META-INF/MANIFEST.MF
        try {
            URL url = VersionInfo.class.getResource("/META-INF/MANIFEST.MF");
            if (url != null) {
                MANIFEST_ATTRS = new Manifest(url.openStream()).getMainAttributes();
            }
        } catch (Exception ignored) {}
    }
 
    public static String getVersion() {
        return MAVEN_PROPS.getProperty("version",
               MANIFEST_ATTRS != null
                   ? MANIFEST_ATTRS.getValue("Implementation-Version")
                   : "unknown");
    }
 
    public static String getBuildDate() {
        return MANIFEST_ATTRS != null
            ? MANIFEST_ATTRS.getValue("Build-Date")
            : "unknown";
    }
}
@RestController
public class HealthController {
 
    @GetMapping("/health")
    public Map<String, String> health() {
        return Map.of(
            "status",    "UP",
            "version",   VersionInfo.getVersion(),
            "buildDate", VersionInfo.getBuildDate(),
            "timestamp", Instant.now().toString()
        );
    }
}
{
  "status"    : "UP",
  "version"   : "2.5.1",
  "buildDate" : "2026-03-08",
  "timestamp" : "2026-03-08T10:30:00Z"
}

Every support ticket that asks "what version are you running?" gets answered automatically.

Usage 6: Bundled Default Configuration

When shipping a library, you want sensible defaults built into the JAR itself. Users should be able to override anything, but if they configure nothing, everything still works.

mylib.jar
└── META-INF/
    ├── mylib-defaults.properties
    └── mylib-messages.properties

# META-INF/mylib-defaults.properties
 
connection.pool.size=10
connection.timeout.ms=5000
connection.retry.count=3
 
cache.enabled=true
cache.ttl.seconds=300
 
feature.compression.enabled=false
feature.encryption.algorithm=AES-256
public class ConfigLoader {
 
    private static final Properties DEFAULTS    = new Properties();
    private static final Properties USER_CONFIG = new Properties();
 
    static {
        // Layer 1: load JAR defaults (lowest priority)
        try (InputStream is = ConfigLoader.class.getResourceAsStream(
                "/META-INF/mylib-defaults.properties")) {
            if (is != null) DEFAULTS.load(is);
        } catch (Exception e) {
            throw new RuntimeException("JAR defaults missing — corrupted artifact!", e);
        }
 
        // Layer 2: load user overrides (highest priority)
        try (InputStream is = ConfigLoader.class.getResourceAsStream(
                "/mylib-config.properties")) {
            if (is != null) USER_CONFIG.load(is);
        } catch (Exception ignored) {}
    }
 
    public static String get(String key) {
        // User config overrides defaults
        return USER_CONFIG.getProperty(key, DEFAULTS.getProperty(key, ""));
    }
 
    public static int    getInt(String key)     { return Integer.parseInt(get(key)); }
    public static boolean getBoolean(String key) { return Boolean.parseBoolean(get(key)); }
}

The layered priority is clean: defaults ship in META-INF inside the JAR, user overrides live outside it. The library always has a working configuration. Users only configure what they actually need to change.

Usage 7: Signed JARs — Tamper Detection

For enterprise and security-sensitive deployments, META-INF contains the signature infrastructure that proves a JAR is authentic and unmodified.

signed-myapp.jar
└── META-INF/
    ├── MANIFEST.MF      ← SHA-256 hash of every file in the JAR
    ├── MYKEY.SF         ← hash of the MANIFEST.MF sections
    └── MYKEY.RSA        ← certificate + encrypted signature

The verification chain works like this:

JVM reads MYKEY.RSA
  → extracts public key from certificate
  → decrypts signature → gets expected hash of MANIFEST.MF
  → recalculates hash of MANIFEST.MF
  → if they match → signature is valid
     → checks each class file hash against MANIFEST.MF entries
     → if all match → JAR is authentic and untampered ✅

# Sign a JAR
keytool -genkeypair -alias mycompany -keyalg RSA -keysize 2048 \
        -validity 365 -keystore mycompany.keystore
 
jarsigner -keystore mycompany.keystore -signedjar signed-myapp.jar \
          myapp.jar mycompany
 
# Verify
jarsigner -verify -verbose signed-myapp.jar
# jar verified.

If anyone modifies a single .class file after signing, the hash check fails and the JVM rejects the JAR.

The Full META-INF Map

META-INF/
│
├── MANIFEST.MF                     → Entry point, classpath, version
│
├── services/
│   ├── java.sql.Driver             → JDBC driver auto-registration
│   ├── java.nio.spi.FileSystem     → Custom file system providers
│   └── com.example.YourInterface  → Your plugin system
│
├── spring.factories                → Spring Boot auto-configuration
│
├── maven/
│   └── {groupId}/{artifactId}/
│       ├── pom.xml                 → Original build file
│       └── pom.properties         → Version metadata
│
├── MYKEY.SF                        → JAR signature file
├── MYKEY.RSA                       → Certificate + encrypted signature
│
├── INDEX.LIST                      → Package index for faster classloading
├── LICENSE                         → License text
├── NOTICE                          → Legal attributions
│
└── your-lib-defaults.properties    → Bundled default configuration

The Bootstrap Sequence

Here is the full picture of what happens when you run java -jar myapp.jar:

JVM opens myapp.jar
  └── Reads META-INF/MANIFEST.MF         → locates Main-Class
       └── Loads all JARs on classpath
            └── Scans META-INF/services/ → auto-registers plugins and drivers
                 └── Spring Boot starts
                      └── Scans META-INF/spring.factories → applies auto-configuration
                           └── Application context is ready
                                └── main() is called ✅

All of this happens before the first line of your application code executes. META-INF is the invisible scaffolding that assembled the entire runtime.

Key Takeaways

META-INF is not a convention. It is a contract. The JVM and major frameworks are built to read it, trust it, and act on it.

SPI is the most underused feature in Java. If you are building any kind of extensible system — parsers, exporters, validators, adapters — META-INF/services/ gives you a clean, zero-dependency plugin architecture for free.

Spring Boot's magic has a source. Every time a Spring Boot app auto-configures itself, it is because a library author put the right class name in META-INF/spring.factories. Now you can do the same.

Version reporting should be free. Maven writes META-INF/maven/pom.properties automatically. Reading it at runtime costs you five lines of code and eliminates an entire class of "what version is deployed?" support questions.

META-INF turns a collection of ZIP files into a self-describing, self-registering, self-configuring ecosystem. Components discover each other. Drivers register themselves. Starters configure themselves. Plugins appear without hardcoding. All of it coordinated through a directory that most developers scroll past without a second thought.

If this post helped you, consider sharing it with your team. Understanding the infrastructure layer makes you a significantly better Java developer — not because you use it every day, but because you stop being surprised by the magic and start understanding exactly why it works.