Maven Dependency Scopes

1. Overview

Maven is one of the most popular build tools in the Java ecosystem, and one of its core features is dependency management.

In this tutorial, we’re going to describe and explore the mechanism that helps in managing transitive dependencies in Maven projects — dependency scopes.

2. Transitive Dependency

There are two types of dependencies in Maven: direct and transitive.

Direct dependencies are the ones that we explicitly include in the project.

These can be included using <dependency> tags:

<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.12</version>
</dependency>

On the other hand, transitive dependencies are required by direct dependencies. Maven automatically includes required transitive dependencies in our project.

We can list all dependencies including transitive dependencies in the project using mvn dependency:tree command.

3. Dependency Scopes

Dependency scopes can help to limit the transitivity of the dependencies. They also modify the classpath for different build tasks. Maven has six default dependency scopes.

And it’s important to understand that each scope — except for import — has an impact on transitive dependencies.

3.1. Compile

This is the default scope when no other scope is provided.

Dependencies with this scope are available on the classpath of the project in all build tasks. They are also propagated to the dependent projects.

More importantly, these dependencies are also transitive:

<dependency> 
    <groupId>org.apache.commons</groupId> 
    <artifactId>commons-lang3</artifactId> 
    <version>3.14.0</version> 
</dependency>

3.2. Provided

We use this scope to mark dependencies that should be provided at runtime by JDK or a container.

A good use case for this scope would be a web application deployed in some container, where the container already provides some libraries itself. For example, this could be a web server that already provides the Servlet API at runtime.

In our project, we can define those dependencies with the provided scope:

<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.0.0</version>
    <scope>provided</scope>
</dependency>

The provided dependencies are available only at compile time and in the test classpath of the project. These dependencies are also not transitive.

3.3. Runtime

The dependencies with this scope are required at runtime. But we don’t need them for the compilation of the project code. Because of that, dependencies marked with the runtime scope will be present in the runtime and test classpath, but they will be missing from the compile classpath.

A JDBC driver is a good example of dependencies that should use the runtime scope:

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.28</version>
    <scope>runtime</scope>
</dependency>

3.4. Test

We use this scope to indicate that dependency isn’t required at standard runtime of the application but is used only for test purposes.

Test dependencies aren’t transitive and are only present for test and execution classpaths.

The standard use case for this scope is adding a test library such as JUnit to our application:

<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.12</version>
    <scope>test</scope>
</dependency>

3.5. System

System scope is very similar to the provided scope. The main difference is that system requires us to directly point to a specific jar on the system.

It’s worthwhile to mention that system scope is deprecated.

The important thing to remember is that building the project with system scope dependencies may fail on different machines if dependencies aren’t present or are located in a different place than the one systemPath points to:

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>custom-dependency</artifactId>
    <version>1.3.2</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/custom-dependency-1.3.2.jar</systemPath>
</dependency>

3.6. Import

It’s only available for the dependency type pom.

import indicates that this dependency should be replaced with all effective dependencies declared in its POM.

Here, below custom-project dependency will be replaced with all dependencies declared in custom-project’s pom.xml <dependencyManagement> section.

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>custom-project</artifactId>
    <version>1.3.2</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

4. Scope and Transitivity

Each dependency scope affects transitive dependencies in its own way. This means that different transitive dependencies may end up in the project with different scopes.

However, dependencies with scopes provided and test will never be included in the main project.

Let’s take a detailed look at what this means:

• For the compile scope, all dependencies with runtime scope will be pulled in with the runtime scope in the project, and all dependencies with the compile scope will be pulled in with the compile scope in the project.
• For the provided scope, both runtime and compile scope dependencies will be pulled in with the provided scope in the project.
• For the test scope, both runtime and compile scope transitive dependencies will be pulled in with the test scope in the project.
• For the runtime scope, both runtime and compile scope transitive dependencies will be pulled in with the runtime scope in the project.

5. Conclusion

In this quick article, we focused on Maven dependency scopes, their purpose and the details of how they operate.

To dig deeper into Maven, the documentation is a great place to start.