Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 41 ยท Dependencies

Dependency Scopes

Understand Maven dependency scopes: compile, provided, runtime, test, system and import, which classpath each one joins, and how scope changes transitively.

Not every library belongs everywhere. JUnit should help you run tests, but it has no business inside the JAR you ship. A servlet API is needed to compile a web application, but the server that runs it already contains one. A database driver is never touched by your source code, yet the program fails without it at run time.

Maven handles these differences with the <scope> element of a dependency. A scope answers one question: on which classpaths does this library appear? Picking the right scope keeps your artifacts small, keeps accidental imports out of your code and avoids nasty runtime surprises.

All pom.xml snippets here are read-only, because Maven cannot run in the browser. The two runnable programs are Java stand-ins that apply the same rules Maven uses, so you can see the classpaths they produce. They illustrate the rules. They are not Maven itself.

Three classpaths

A Maven build does not have one classpath. It has several, each used by a different step:

  • The compile classpath is what javac sees when it compiles src/main/java.
  • The test classpath is what javac and the test runner see for src/test/java. It contains your compiled classes plus everything the tests need.
  • The runtime classpath is what your program needs when it actually runs.

Each scope is a recipe for which of these three lists a library joins.

Where does each scope go?

compile Everywhere. The default.
provided Compile and test. The server brings it at run time.
runtime Test and run. Not visible to your source.
test Only your tests.

If you never write a scope, you get compile.

1 / 2

The scopes one by one

compile is the default. The library is on all three classpaths and travels with your artifact to the people who depend on it. Use it for anything your production code imports: a JSON library, a utility library, a logging API.

provided means "needed to compile, but someone else supplies it at run time". The classic case is the Jakarta Servlet API in a web application deployed to Tomcat or Jetty: the container ships its own copy, so including yours would conflict. Annotation processors such as Lombok are also usually provided, because they matter only while compiling. A provided dependency is on the compile and test classpaths but not the runtime one, and it is not passed on to projects that depend on yours.

runtime means "not needed to compile, but needed to run". A JDBC driver is the standard example. Your code talks to java.sql.Connection, an interface from the JDK, and never imports the PostgreSQL driver classes directly. The driver must still be present when the program starts. Making it runtime stops you from accidentally importing driver classes into business code.

test is for libraries that only tests use: JUnit, Mockito, AssertJ, test containers. They are on the test classpath only and are never packaged or inherited. This is how your production artifact stays free of test frameworks.

system works like provided, but you point at a JAR on your own disk with <systemPath>. It is deprecated in spirit, because it ties the build to one machine's file layout and cannot be resolved from a repository. Do not use it for new work. If you have a JAR that is not on Maven Central, install it into a repository (or your company's repository) and depend on it normally.

import is special. It is allowed only on a dependency with <type>pom</type> inside <dependencyManagement>, where it pulls in a BOM, a list of recommended versions. You will use it in Managing Versions.

One more thing that looks like a scope but is not: optional. It is a separate flag that hides a dependency from your consumers, covered in Transitive Dependencies.

A realistic POM

This block uses four scopes, the way a small web service often does:

XML
<dependencies>
  <!-- compile (default): our code imports it -->
  <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.19.2</version>
  </dependency>

  <!-- provided: the servlet container supplies it -->
  <dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.1.0</version>
    <scope>provided</scope>
  </dependency>

  <!-- runtime: needed when running, never imported -->
  <dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.7.7</version>
    <scope>runtime</scope>
  </dependency>

  <!-- test: only src/test/java sees it -->
  <dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>5.13.4</version>
    <scope>test</scope>
  </dependency>
</dependencies>

The versions are examples. Check Maven Central for current releases.

Scope matrix

Putting it together, here is which classpath each scope joins:

Scope Compile classpath Test classpath Runtime classpath Inherited by consumers
compile yes yes yes yes (as compile)
provided yes yes no no
runtime no yes yes yes (as runtime)
test no yes no no
system yes yes no no

You can see the logic: the test classpath is the biggest, because tests need to compile against and run with almost everything. The runtime classpath is what ships.

Classpaths by phase: a calculator

The next program takes a list of dependencies with scopes and builds the three classpaths using the matrix above. Try changing a scope (for example, move the JDBC driver to compile) and see which list gains it. Then think about what that would mean for compile-time mistakes.

Java Which classpath sees which library?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Scopes and transitive dependencies

Your dependencies have dependencies of their own, each with its own scope declared in its POM. Maven combines the two scopes to decide what your project gets. The rules, in short:

  • A library's own test and provided dependencies are never passed on. They are that library's private business.
  • A compile dependency of a compile dependency stays compile.
  • A runtime dependency of a compile dependency becomes runtime for you.
  • If you declare a dependency as provided, runtime or test, everything it brings is weakened to match: it can never be wider than the way you asked for it.

Here is the full table. Rows are the scope you used for your direct dependency, and columns are the scope that dependency declares for its own dependency. Dependencies that the library declares as test or provided are dropped before this table applies.

Your scope Library's compile Library's runtime
compile compile runtime
provided provided provided
runtime runtime runtime
test test test

If the same library is reached through several paths with different scopes, Maven generally keeps the wider one (compile over runtime, runtime over test).

The second program encodes the table as a function and applies it to a small graph. Check the result against the table, and notice that the mock-helper and servlet-api dependencies of web-lib never reach your project.

Java Scope inheritance through a graph

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Common mistakes

  • JUnit left on compile. It still works, but the framework ends up in the classpath of every consumer and in a fat JAR. Give test libraries <scope>test</scope>.
  • provided for something you need at run time. Everything compiles, then the application dies with NoClassDefFoundError. Only use provided when a container or runtime really supplies the library.
  • runtime for a library you import. The compiler cannot see it and reports package ... does not exist. Use compile if your code needs it at compile time.
  • Using system. Install the JAR in a repository instead.
  • Forgetting the IDE. After changing a scope, reload the project. Otherwise the IDE keeps old classpaths and shows misleading errors. See Adding Dependencies.

A quick way to check the effect of a scope is mvn dependency:tree, which prints the scope of every library next to its coordinates.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A JDBC driver is never imported by your code, but the app needs it when it runs. Which scope fits best?

    runtime keeps the driver off the compile classpath, which prevents accidental imports, but includes it when the app runs and in the test classpath.
  2. 2. Which scope would you give the Servlet API in a WAR deployed to Tomcat?

    The code needs it to compile, but Tomcat supplies its own copy at run time. provided gives compile and test visibility without packaging a conflicting copy.
  3. 3. Where is a dependency with scope test visible?

    test scope is limited to compiling and running your tests. It is neither packaged nor inherited by projects that depend on yours.
  4. 4. Your project declares library A with scope compile. A's own POM declares library B with scope test. Does B reach your project?

    test and provided dependencies are private to the library that declares them, so they are never transitive.
  5. 5. Which scope value is only legal inside dependencyManagement with type pom?

    import merges the managed versions of a BOM into your dependencyManagement. optional is not a scope at all but a separate flag.

Summary

  • A scope decides on which of the three classpaths (compile, test, runtime) a library appears.
  • compile is the default, provided is supplied by the platform, runtime is needed only to run, test is for tests, system should be avoided and import is only for BOMs.
  • Test and provided dependencies of a library are never passed on to its consumers.
  • Your own scope can only narrow what a transitive dependency gets, never widen it.
  • A wrong scope shows up as a missing package at compile time or as NoClassDefFoundError at run time.

Next: Transitive Dependencies and Mediation