Maven Dependencies, Scopes & Mediation

A project lists what it needs in <dependencies>. Here is the tidepool engine module, which needs its own model module and Commons CSV:

The elements of a <dependency> are:

The identity of a dependency is groupId:artifactId:type:classifier; the version is not part of it. A project may therefore declare each identity once. That rule used to be only a warning and is now enforced; see Maven 3.10 refuses duplicate declarations.

Source: POM reference: Dependencies

A scope does two things: it limits the classpaths a dependency appears on in this build, and it limits how the dependency travels to projects that depend on this one.

The five classpath-bearing scopes are easy to verify on a throwaway project. Its four dependencies are empty jars in a local file:// repository whose group is demo, one per scope (dep-compile, dep-provided, dep-runtime, dep-test), so that nothing but the scope can explain the result. The dependency plugin’s build-classpath goal takes an includeScope and prints the artifacts for it; the file names below are what remained after cutting each path to its last segment (mvn dependency:build-classpath -DincludeScope=compile, then runtime, then test):

That is the table above, measured: provided is missing from the runtime classpath, runtime is missing from the compile classpath, and test is only on the test classpath. The system scope was run separately, with one jar declared through systemPath: includeScope=compile and includeScope=test listed it, and includeScope=runtime listed nothing, which is the same pattern as provided.

Source: Dependency mechanism: Dependency Scope

Maven reads the POM of every dependency and adds that POM’s own dependencies, and theirs, to the graph. There is no depth limit; only a cycle is an error. The scope that a transitive dependency ends up with is the combination of how you declared the dependency above it and how that dependency declared it. For a dependency A declared in your project (rows) and a dependency B that A declares (columns), the resulting scope of B is:

Two rules fall out of it: provided and test dependencies of a dependency are never inherited, and the inherited scope is never wider than the scope you gave the dependency above it. The documentation gives the table as a matrix; here it was reproduced by running it. A library lib declares one dependency per scope (dep-compile as compile, dep-provided as provided, dep-runtime as runtime, dep-test as test), and four projects declare lib with each of the four scopes in turn:

mvn dependency:tree on each of the four projects (the first line of every tree is the project itself):

dep-provided and dep-test never appear, and the other two keep or lose width exactly as the table says. Maven 3.9.16 and Maven 4.0.0-rc-7 print the same four trees. The system scope is not part of the table in the documentation and was not tabulated here.

Source: Dependency mechanism: Transitive Dependencies

When the same artifact (same groupId:artifactId:type:classifier) is reached by several paths with different versions, Maven keeps exactly one version. The rule is nearest definition: the version on the path with the fewest edges from your project wins. If two paths are equally long, the one whose first edge was declared first in the POM wins.

The order of the jars on a classpath matters when two jars hold the same class. Maven 3.10.0 changed how a dependency graph is flattened into a list: from pre-order (depth first: a dependency, then everything below it, then the next sibling) to level-order (breadth first: all direct dependencies, then their dependencies, and so on). This aligns it with Maven 4 and the Maven Resolver 2.x default. The release notes list it as a potentially breaking change and give a switch back: -Daether.system.dependencyVisitor=preOrder.

To see it, two direct dependencies are declared in this order: p, which depends on p1, which depends on p2, and then q. Pre-order gives p p1 p2 q; level-order gives p q p1 p2. The classpath handed to javac by mvn -X compile was identical on Maven 3.9.16, Maven 3.10.0 (with and without the switch) and Maven 4.0.0-rc-7:

In this experiment the order of the project’s own compile classpath therefore did not change. Where the change is visible is in the class realm of a plugin that is given extra <dependencies>, because a plugin’s realm is built from the resolver’s list. The same two dependencies were added to the dependency plugin’s declaration, and the order of the Included: lines in the mvn -X dependency:tree output (pipeline: keep the Included: demo: lines that follow Populating class realm plugin>org.apache.maven.plugins:maven-dependency-plugin) was:

So 3.10 and 4 agree with each other, and the switch restores the 3.9 order. What other consumers of the resolver’s list exist, and whether a given plugin builds its classpath from it, was not investigated here; if a build relies on one jar shadowing another, make the order explicit (and better, remove the duplicate class) instead of depending on either traversal.

Source: Maven 3.10.0 release notes: Classpath ordering change

Marking a dependency <optional>true</optional> keeps it in the declaring project’s own graph and hides it from every project that depends on the declaring project. Think of it as "excluded by default". The typical author is a library that supports many backends and cannot be split: it needs every driver to compile, but its users need only one. Here store declares driver-a as optional and driver-b as a normal dependency:

A project that depends on store gets only driver-b:

The project chooses driver-a by declaring it itself:

Optional dependencies keep jars that conflict, or whose licence you cannot ship, out of WARs, EARs and fat jars. They are a stop-gap: the clean design is to split the library into modules whose dependencies are all normal.

Source: Optional dependencies

An <exclusion> removes an artifact, and everything that is reachable only through it, from the graph below one specific dependency. It is the consumer’s tool, used when the library you depend on did not mark the dependency optional. In the example, top depends on mid, which depends on leaf1 and leaf2; the project declares top.

Without an exclusion the whole chain arrives:

Excluding demo:leaf1 on the top dependency removes only that leaf:

Excluding demo:mid instead removes mid and, because they are reachable only through it, both leaves: the tree of that project is just demo:top:jar:1.0:compile under the project. A wildcard exclusion, with * as both groupId and artifactId, removes every transitive dependency of that dependency and leaves you in charge of the rest:

An exclusion applies to the path it is written on, not to the whole project. If the same artifact is reachable by another path, it comes back. With top (excluding leaf1) and a second, direct dependency on mid:

Because of that, exclusions are also published: if you deploy a project with an exclusion, the projects that depend on it inherit the exclusion for that edge. If the intent is that an artifact must never appear anywhere, the enforcer’s bannedDependencies rule fails the build and names the paths that still need an exclusion (the enforcer is covered on The Enforcer Plugin). Use exclusions as a last resort, after asking the library to mark the dependency optional, and write down why.

Source: POM reference: Exclusions, Optional and excluded dependencies: How to use dependency exclusions

A system dependency is not looked up in any repository. The dependency names a jar on the local disk with systemPath:

It works, and the tree shows it with the scope system. The build is also now loud about it. Maven 3.10.0 and Maven 4.0.0-rc-7 warn that the scope is deprecated and that a path inside the project directory cannot be resolved by dependent projects (in Maven 3.9.16 the first warning is absent; the second is printed):

(The ellipsis line replaces the rest of the Maven warning block.) The reasons are practical: the build is bound to one path on one machine, and a system dependency cannot be told apart as compile-only or test-only. Install the jar into a repository instead; see Installing Third-Party JARs & Relocation.

In the past system was also used to point at JDK-supplied Java EE packages, for example javax.security:jaas with ${java.home}/lib/rt.jar. That no longer works and should never be done: classes that belong to the JDK need no dependency at all, and those that were removed from the JDK come from Maven Central. The clearest case is the XML binding API javax.xml.bind, which JEP 320 removed from the JDK in Java 11. This one-class project compiles javax.xml.bind.DatatypeConverter with maven.compiler.release 21 on JDK 26 and fails:

Declaring javax.xml.bind:jaxb-api:2.3.1 fixes it, and brings in the activation API as a transitive dependency:

The Java EE specifications have since moved to the Eclipse Foundation and to the jakarta.* package names, so new code should use those. Changing the import to jakarta.xml.bind.DatatypeConverter and the dependency to jakarta.xml.bind:jakarta.xml.bind-api:4.0.5 compiled on the same setup, with jakarta.activation:jakarta.activation-api:2.1.4 as the transitive dependency. Moving a large code base from javax.* to jakarta.* is a source change, not a build setting; that part is not covered here.

Source: Dependency mechanism: System Dependencies, Historical usage: Java EE (javax) libraries of the JDK

Declaring the same identity twice, with the same or different versions, used to be a warning and the last declaration won. Maven 3.10.0 turns it into an error. A project that declares demo:d 1.0 and then demo:d 2.0:

Maven 4.0.0-rc-7 also rejects the project with the same message. This is part of the stricter POM validation listed in the 3.10.0 release notes; the fix is to keep one declaration (or to put the version in dependencyManagement). The release notes also describe a maven.resolver.validation property, but that property concerns the validation of artifact coordinates, not this check. Passing the lowercase -Dmaven.resolver.validation=off shown in the release notes made Maven 3.10.0 stop with an internal error about an unknown enum constant off when tried here, so it is not recommended as a way around this check.

Source: Maven 3.10.0 release notes: Stricter POM validation