Skip to content
javahacks.dev
DevOps

Maven Dependency Scopes Explained With Examples and Traps

What compile, provided, runtime and test scopes mean, which classpaths each one joins, how scope changes transitively and where the import scope fits.

7 min read
Summarize in AI
Flat illustration of shipping containers stacked on a ship, with the Docker and Kubernetes logos.

A Maven dependency has a scope, and the scope decides on which classpaths the jar appears: compiling your main code, compiling your tests, running the tests, running the application and packaging it. Getting it wrong has three characteristic symptoms. The code compiles and fails at runtime with NoClassDefFoundError, because a library you needed was left out of the package. The application is bloated with test libraries that ship to production. Or a transitive dependency appears where you did not ask for it, and the scope that you did not write is the reason it behaves strangely. This post sets out the six scopes and the classpaths they join, when to use each, how scope changes along a transitive chain, the special import scope for BOMs and the traps that cause most of the trouble. Examples use Maven 3.9 and Java 25, and every table can be checked with mvn dependency:tree.

The scopes and the classpaths

Maven builds several classpaths during a build. A dependency's scope selects which of them it joins:

ScopeCompile (main)Compile (test)Test runtimeApplication runtimePackaged in the app
compile (default)yesyesyesyesyes
providedyesyesyesnono
runtimenoyesyesyesyes
testnoyesyesnono
systemyesyesyesnono
importnot a classpath scope

Read the table by column. For the application to run, the library must be in "Application runtime", which only compile and runtime offer. For your code to compile against it, it must be in "Compile (main)", which compile, provided and system offer. That is the whole story, and the rest of this post is its consequences. The authoritative table is in the dependency mechanism guide, and the element itself in the POM reference.

You can print the effective scopes any time:

Shell
mvn -B dependency:tree
Text
[INFO] dev.javahacks:shop:jar:1.0.0
[INFO] +- org.springframework.boot:spring-boot-starter-web:jar:4.0.0:compile
[INFO] +- org.postgresql:postgresql:jar:42.7.4:runtime
[INFO] +- jakarta.servlet:jakarta.servlet-api:jar:6.1.0:provided
[INFO] \- org.junit.jupiter:junit-jupiter:jar:5.12.0:test

The scope is the last word on each line. Learn to read it; it answers most "why is this jar here or not here" questions.

When to use each

**compile** is for anything your main code uses directly and the application needs to run: Spring, Jackson, your own libraries. It is the default, so it is the scope of an unadorned <dependency>. If you are unsure, it is the safest choice, because it errs on the side of availability.

**runtime** is for what the application needs to run but your code never references by name. The classic example is a JDBC driver: you write against java.sql interfaces and the driver is found at runtime. With runtime scope the driver is packaged but cannot be imported by accident into main code, which keeps the compile classpath honest:

pom.xmlXML
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

Logging backends (Logback behind SLF4J) and other service-provider implementations follow the same pattern. Using test instead of runtime for a driver is the mistake behind No suitable driver found.

**provided** means "needed to compile, but the platform will supply it at runtime, so do not package it". The servlet API in a WAR deployed to Tomcat is the textbook case, since the container ships its own. Annotation-only libraries and compile-time processors (Lombok) also use it. The risk is the mirror image of the benefit: if the platform does not supply the library, the application fails with NoClassDefFoundError. Spring Boot's executable jar with an embedded server is not a platform that supplies a servlet API, so marking it provided there breaks the run.

**test** is for test frameworks and anything used only by test code: JUnit, AssertJ, Mockito, Testcontainers. It is available when compiling and running tests and is not packaged. Spring Boot's test starter is test-scoped for exactly this reason.

**system** points at a jar by absolute path with <systemPath>. It is deprecated; the path is machine specific and breaks portability. Install the jar into a repository instead.

**import** is different in kind, covered below.

Transitive scope

You declare direct dependencies, and each brings its own, with their own scopes. Maven combines the two scopes by a fixed table: the resulting scope is the weaker of the two in terms of reach.

Direct dependency scopeIts compile dependency becomesIts runtime dependency becomes
compilecompileruntime
providedprovidedprovided
runtimeruntimeruntime
testtesttest

So a library declared compile brings its own compile dependencies as compile (visible to your code at compile time, which is why you can accidentally import classes you never declared), and its runtime ones as runtime. A library you declared test drags its whole transitive set to test. A transitive dependency declared provided or test by its owner is not inherited at all: the library's test dependencies never reach you.

Two consequences matter in practice. First, you can compile against a transitive library you did not declare, and when the direct dependency later drops it, your build breaks with no change on your side; declare what you import directly. The command mvn dependency:analyze lists "used but undeclared" and "declared but unused" dependencies:

Shell
mvn -B dependency:analyze
Text
[WARNING] Used undeclared dependencies found:
[WARNING]    com.fasterxml.jackson.core:jackson-databind:jar:2.18.2:compile
[WARNING] Unused declared dependencies found:
[WARNING]    org.apache.commons:commons-lang3:jar:3.17.0:compile

Second, when the same library arrives by two routes with different scopes, Maven keeps the strongest scope for the version it picks. A library that you declared test and a transitive path brings as compile ends up compile, which can put a test tool in the production package. Check the tree for surprises, and see the version side of this in Maven dependency mediation.

The import scope

import is valid only on a dependency of type pom inside <dependencyManagement>, and it means "copy the managed versions from that POM into mine". It is how a Bill of Materials is consumed, so one line aligns the versions of many libraries:

pom.xmlXML
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>4.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

After this, a <dependency> for Jackson without a <version> takes the version from the BOM. The imported POM contributes only version management, never dependencies, so nothing lands on a classpath because of it. Use it when you cannot inherit from the Boot parent (you already have another parent) or when you manage your own platform of versions.

Common traps

**A library in provided that the runtime does not supply.** Symptom: it compiles, tests pass (the test classpath includes provided), and production fails with NoClassDefFoundError. The test classpath hides it, which is why it surprises people. The failure is analyzed in ClassNotFoundException and NoClassDefFoundError. Check what is packaged:

Shell
unzip -l target/shop.jar | grep -i servlet

**A test dependency needed by main code.** A utility class in src/main that imports AssertJ or a test double compiles never, since test is not on the main compile classpath; the error is package org.assertj.core.api does not exist. Either move the class to src/test or give the library the right scope.

A runtime-only dependency imported by name. Importing org.postgresql.Driver in main code fails to compile under runtime scope. That is the feature working: depend on the abstraction. If you genuinely need the class, use compile.

An IDE that disagrees. Some IDEs put provided and test jars on the run configuration's classpath, so the application runs from the IDE and fails when packaged. Always run the packaged artifact (java -jar) before trusting a green IDE run.

Optional dependencies. <optional>true</optional> is not a scope: the dependency is on your classpath but is not passed to consumers. A library that marks Jackson optional does not bring Jackson into your project, and you must add it if you use that feature. A missing optional dependency is a frequent cause of ClassNotFoundException for a feature that "should have worked".

Duplicate declarations with different scopes. Declaring the same artifact twice, once compile and once test, makes Maven warn and keep one; remove the duplicate. Maven 3 prints a warning ('dependencies.dependency.(groupId:artifactId:type:classifier)' must be unique), and the last one wins in some versions.

For the basics of the POM that these elements live in, see the Maven tutorial on the POM and packaging.

Where this does not apply

Gradle uses configurations with different names (implementation, api, runtimeOnly, compileOnly, testImplementation) that map approximately onto these scopes, with a useful addition: api versus implementation controls what leaks to consumers at compile time. In a Spring Boot fat jar, scope still decides what is packaged, and provided is mostly relevant for the one case of deploying the jar as a WAR. And in a multi-module project, a module's scopes apply to its own build; a module that depends on another gets that module's compile and runtime dependencies transitively, per the table above.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.