# What Is the Compat Directory in Maven? Role and Implementation Details

> Understand the Maven compat directory and its role in supporting Maven 2 legacy plugins on Maven 3/4 runtimes. Learn about its implementation and upcoming removal.

- Repository: [The Apache Software Foundation/maven](https://github.com/apache/maven)
- Tags: internals
- Published: 2026-07-07

---

**TLDR:** The `compat` directory contains the deprecated Maven 2 compatibility layer (`maven-compat`) that allows legacy plugins to compile and run on Maven 3/4 runtimes while emitting validation warnings about its upcoming removal in Maven 4.

The `compat` directory in the [Apache Maven](https://github.com/apache/maven) repository houses the **maven-compat** module, a backward-compatibility shim designed to preserve binary compatibility for plugins built against Maven 2 APIs. This directory serves as a critical bridge between the legacy Maven 2 codebase and the modern Maven 3/4 architecture, ensuring older plugins function without modification while signaling the transition to current APIs. Understanding the role of the compat directory in Maven helps developers migrate legacy build tooling effectively.

## Architecture of the Maven Compat Directory

The `compat` directory functions as an aggregator for modules that expose deprecated Maven 2-style APIs. According to the source code, this layer bundles classes that existed in Maven 2 but were maintained specifically to let legacy plugins and extensions compile and run unchanged on newer Maven runtimes.

The top-level [[`compat/pom.xml`](https://github.com/apache/maven/blob/main/compat/pom.xml)](https://github.com/apache/maven/blob/master/compat/pom.xml) acts as the parent aggregator, defining modules such as `maven-compat`, `maven-plugin-api`, and `maven-model-builder` that constitute the compatibility set. These modules assemble into the `org.apache.maven:maven-compat` artifact, which Maven core adds as a transitive dependency to maintain backward compatibility.

## Key Implementation Files

Several critical source files define and enforce the compat layer's behavior:

**[`compat/maven-compat/pom.xml`](https://github.com/apache/maven/blob/main/compat/maven-compat/pom.xml)**: This module descriptor explicitly marks the artifact as deprecated with the description "Deprecated Maven2 classes maintained as compatibility layer". It packages the legacy classes that plugin developers historically relied upon.

**[`impl/maven-core/src/main/java/org/apache/maven/plugin/internal/Maven3CompatDependenciesValidator.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/plugin/internal/Maven3CompatDependenciesValidator.java)**: This validator detects when plugins depend on `org.apache.maven:maven-compat`. When identified, it flags the dependency as an incompatibility for Maven 4 and emits a validation warning.

**[`impl/maven-core/src/main/java/org/apache/maven/project/MavenProject.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/project/MavenProject.java)**: This core project model class contains compatibility-related logic and comments regarding "Maven 3 plugin compatibility" and "backward-compat" handling, routing legacy calls through the shim.

## Runtime Validation and Deprecation Warnings

Maven core actively monitors for usage of the compatibility layer to prepare users for Maven 4's removal of this shim.

### How Validation Works

The `Maven3CompatDependenciesValidator` class inspects plugin dependencies during the build process. When it detects a dependency on `org.apache.maven:maven-compat`, it generates a validation issue with the message:

```

Plugin depends on the deprecated Maven 2.x compatibility layer, which will be not supported in Maven 4.x

```

This warning appears in build logs to alert developers that their plugin relies on deprecated APIs that will cease to function in future Maven versions.

### Transitive Dependency Behavior

Although the `maven-compat` artifact is deprecated, it remains available as a transitive dependency of Maven core. This automatic inclusion ensures legacy plugins continue to function without explicit configuration changes, though the validation warnings encourage migration to modern APIs.

## Working with the Maven Compat Layer

The following examples demonstrate how the compat layer functions in practice and how to identify its usage.

### Legacy Plugin Implementation

A classic Maven 2-style mojo might reference `MavenProject` from the compat layer:

```java
package org.apache.maven.plugins.legacy;

import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.project.MavenProject;

/**
 * @goal legacy
 */
public class LegacyMojo extends AbstractMojo {
    /** @parameter default-value="${project}" */
    private MavenProject project;

    public void execute() {
        getLog().info("Legacy plugin runs on Maven " + project.getVersion());
    }
}

```

When built against Maven 4, this code triggers the `maven-compat` dependency automatically, resulting in the validation warning described above.

### Explicit Dependency Declaration

While usually unnecessary, you can explicitly declare the compatibility layer in your [`pom.xml`](https://github.com/apache/maven/blob/main/pom.xml):

```xml
<dependency>
    <groupId>org.apache.maven</groupId>
    <artifactId>maven-compat</artifactId>
    <version>${maven.version}</version>
</dependency>

```

This forces the compatibility shim onto the classpath, allowing legacy code to compile without modifications.

### Runtime Inspection

To verify whether your runtime uses the compat layer, inspect the class loader origin of `MavenProject`:

```java
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.project.MavenProject;

public class CompatCheckerMojo extends AbstractMojo {
    public void execute() throws MojoExecutionException {
        ClassLoader cl = MavenProject.class.getClassLoader();
        getLog().info("MavenProject loaded from: " + 
            cl.getResource("org/apache/maven/project/MavenProject.class"));
    }
}

```

Running this on Maven 4 outputs a path containing `maven-compat-…jar`, confirming the shim's presence.

## Summary

- The `compat` directory contains the **maven-compat** module, a deprecated shim for Maven 2 APIs.
- It enables legacy plugins to run on Maven 3/4 without modification by providing backward-compatible classes.
- Maven core validates against this layer using `Maven3CompatDependenciesValidator`, issuing warnings for Maven 4 compatibility.
- Key files include [`compat/pom.xml`](https://github.com/apache/maven/blob/main/compat/pom.xml) (aggregator), [`compat/maven-compat/pom.xml`](https://github.com/apache/maven/blob/main/compat/maven-compat/pom.xml) (deprecated artifact), and [`MavenProject.java`](https://github.com/apache/maven/blob/main/MavenProject.java) (compatibility logic).
- The layer will be removed in Maven 4, making migration to modern APIs essential.

## Frequently Asked Questions

### What is the compat directory in Maven?

The `compat` directory in the Apache Maven repository houses the maven-compat module and related components that provide a backward-compatibility layer for Maven 2 APIs. It allows legacy plugins to function on modern Maven 3/4 runtimes while signaling that these deprecated APIs will be removed in Maven 4.

### Is maven-compat deprecated in Maven 4?

Yes, the `maven-compat` artifact is explicitly deprecated and scheduled for removal in Maven 4. The `Maven3CompatDependenciesValidator` class detects dependencies on this artifact and emits warnings that the Maven 2.x compatibility layer will not be supported in Maven 4.x.

### How do I know if my plugin uses the compat layer?

Maven automatically validates plugin dependencies during builds. If your plugin uses the compat layer, you will see the validation message: "Plugin depends on the deprecated Maven 2.x compatibility layer, which will be not supported in Maven 4.x". You can also inspect the `MavenProject` class loader to verify if it loads from `maven-compat-…jar`.

### Should I remove maven-compat dependencies from my plugin?

Yes, you should migrate away from `maven-compat` dependencies by updating your plugin to use the modern Maven 3/4 APIs found in `maven-core` and `maven-plugin-api`. Removing this dependency ensures your plugin remains compatible with future Maven versions and eliminates deprecation warnings.