Master Maven Dependency Scopes: Optimize Builds and Avoid Conflicts

1. Overview

Maven is one of the most popular build tools in the Java ecosystem, and one of its core functions is dependency management. It retrieves libraries and resources from the central repository, greatly simplifying the build process.

In this tutorial we explore the mechanism of transitive dependencies — dependency scopes. Understanding and using these scopes correctly is essential for optimizing builds, reducing unnecessary conflicts, and improving project maintainability.

2. Transitive Dependencies

Maven has two types of dependencies: direct and transitive.

Direct dependencies are explicitly declared in the project using the <dependency> tag:

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

Transitive dependencies are the dependencies required by direct dependencies. Maven automatically includes them, which reduces manual configuration but can also introduce unnecessary libraries, causing conflicts or longer build times.

The mvn dependency:tree command lists all dependencies, including transitive ones, helping you understand and adjust the dependency graph.

Dependency scopes help limit transitivity and modify classpaths for different build tasks, ensuring appropriate dependency sets for compile, test, and runtime phases.

Except for the import scope, each scope influences transitive dependencies. Proper use of scopes can avoid conflicts and optimize the build.

3. Dependency Scopes

3.1 Compile

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

Dependencies with compile scope are available on all classpaths during build and are packaged into the final artifact (JAR/WAR). They are also transitive, propagating to downstream projects.

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

Typical use: core libraries needed for compilation, testing, and runtime, such as Spring core in a web project.

3.2 Provided

Used for dependencies that are supplied by the JDK or the runtime container.

Common example: the Servlet API provided by an application server.

Example declaration:

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

Provided dependencies are only available on the compile and test classpaths, not packaged in the final artifact, and are not transitive.

3.3 Runtime

Dependencies needed at runtime but not for compilation.

Typical example: JDBC drivers.

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

These appear on the runtime and test classpaths, but not on the compile classpath.

3.4 Test

Dependencies used only for testing; they are not included in the final artifact.

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

Test scope ensures test libraries do not affect production builds.

3.5 System

The system scope is similar to provided but requires an explicit path to a JAR on the local system.

It is deprecated because it reduces build reproducibility.

<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>

Avoid using system scope; prefer installing the JAR in a local Maven repository and using compile or provided scopes.

3.6 Import

Applicable only to dependencies of type pom . It replaces the declared dependency with all dependencies defined in the referenced POM, typically used in dependencyManagement to centralize version control.

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

Import scope is valuable for large multi‑module projects to ensure consistent dependency versions.

4. Scope and Transitivity

Each scope influences transitive dependencies differently. Provided and test dependencies never become part of the main artifact because they are supplied by the runtime or used only for testing.

Understanding these rules helps avoid conflicts, optimize build performance, and maintain project health.

5. Usage Scenarios

Scenario 1: Web Application Development

Compile : core business logic libraries such as Spring core.

Provided : Servlet API supplied by the application server.

Runtime : database drivers.

Test : testing frameworks like JUnit.

Example POM configuration:

<!-- compile dependency: Spring core -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
    <version>5.3.23</version>
</dependency>
<!-- provided dependency: Servlet API -->
<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.0.0</version>
    <scope>provided</scope>
</dependency>
<!-- runtime dependency: MySQL driver -->
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.28</version>
    <scope>runtime</scope>
</dependency>
<!-- test dependency: JUnit -->
<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.12</version>
    <scope>test</scope>
</dependency>

Scenario 2: Multi‑module Project Management

Use the import scope in dependencyManagement to centralize versions:

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

This ensures all sub‑modules share the same dependency versions.

6. Best Practices

Prefer compile scope for most core libraries.

Use provided scope wisely for container‑supplied APIs.

Separate test dependencies with test scope.

Avoid system scope because it is deprecated and harms reproducibility.

Leverage import scope for consistent version management in large multi‑module projects.

7. Conclusion

This article examined Maven dependency scopes, their purposes, operational details, and practical scenarios. Proper use of scopes enables effective dependency management, conflict avoidance, build optimization, and improved maintainability.