How to include or exclude a specific dependency in Gradle

Understanding Dependency Management in Gradle

Gradle manages dependencies by resolving a graph of modules based on the rules defined in your build.gradle script. When you declare a dependency, such as org.springframework.boot:spring-boot-starter-data-jpa, Gradle automatically pulls in its own set of required libraries, known as transitive dependencies. While this automation simplifies development, it can sometimes lead to issues where an unwanted library is pulled in, or two different versions of the same library are present, causing runtime errors.

The primary goal of managing these dependencies is to ensure consistency across your application. By explicitly including or excluding specific artifacts, you gain precise control over what ends up in your classpath. This is particularly critical in large projects where multiple starters might depend on conflicting versions of common libraries like Jackson, Lombok, or logging frameworks.

Excluding Transitive Dependencies

Excluding dependencies is the most common scenario in Gradle builds. It prevents a specific module from being added to your project's classpath when it is pulled in as a transitive dependency. This is useful when a starter brings in a library that conflicts with another one you have already declared, or when you want to reduce the final artifact size by removing unnecessary components.

To exclude a dependency, you use the exclude closure inside your dependency declaration. The syntax requires you to specify either the group name, the module name, or both. If you only specify the group, all modules from that group are excluded. If you specify the module, only that specific artifact is removed.

dependencies {
    implementation('org.springframework.boot:spring-boot-starter-web') {
        exclude group: 'org.springframework.boot', module: 'spring-boot-starter-tomcat'
    }
}

In the example above, we are excluding the Tomcat starter from the web starter. This is often done when deploying to an external servlet container like Apache Tomcat or Jetty, where the embedded server would otherwise conflict with the external one. Note that you must use the correct group and module identifiers, which can be found in the Maven Central repository or by inspecting the dependency tree.

Using Exclude Rules for Global Exclusions

If you need to exclude a dependency from all configurations in your project, rather than just one specific line, you can use global exclusion rules. This is helpful when a particular library is problematic across multiple modules or when you want to enforce a policy that certain libraries should never be included.

You can define these rules in the configurations block. This approach keeps your dependencies block cleaner and ensures that the exclusion applies universally throughout the build lifecycle.

configurations.all {
    exclude group: 'commons-logging', module: 'commons-logging'
}

This configuration tells Gradle to ignore any dependency named commons-logging regardless of which parent dependency tries to pull it in. This is particularly useful in Spring Boot applications that might accidentally bring in older logging implementations that clash with SLF4J.

Handling Include Filters for Specific Artifacts

While exclude removes items, there are scenarios where you might want to include only specific parts of a dependency. This is less common with standard JAR dependencies but is highly relevant when dealing with multi-module projects or when using dependency variants. However, for standard single-JAR dependencies, inclusion is implicit. You simply declare the dependency, and all its contents are included unless filtered out.

If you are working with complex configurations or custom configurations, you might use includeFilter and excludeFilter within the configurations block to manage which classes or resources are visible. This is advanced usage typically reserved for specialized build setups.

configurations {
    myConfig {
        extendsFrom implementation
        // You can add filters here if needed for specific resolution strategies
    }
}

dependencies {
    myConfig 'com.example:my-library:1.0'
}

For most Spring Boot developers, sticking to exclude within the dependencies block is sufficient. It provides clear visibility into exactly what is being removed from which starter, making debugging easier. Always verify your changes by running ./gradlew dependencies to see the resolved dependency tree.

Verifying Your Changes

After modifying your build.gradle file, it is crucial to verify that the changes have taken effect as intended. Gradle provides a powerful command-line tool to visualize the dependency graph. Run the following command in your terminal:

./gradlew dependencies --configuration compileClasspath

This command outputs the entire dependency tree for the compile classpath. Look for the dependency you expected to be excluded; it should no longer appear in the list. If it is still present, double-check the group and module names. Typos in these identifiers are a common source of confusion. Additionally, consider checking for related issues such as Troubleshooting Spring Boot JPA Issues: A Comprehensive Guide, as dependency conflicts often manifest as JPA initialization failures or Hibernate dialect errors.

Frequently Asked Questions

How do I find the correct group and module name to exclude?

You can find the exact group and module names by running ./gradlew dependencies and looking at the output tree. Alternatively, check the Maven coordinates in the documentation of the library you are trying to exclude. The group is usually the package namespace, and the module is the artifact ID.

Can I exclude a dependency globally for all configurations?

Yes, you can use the configurations.all block to apply exclusion rules globally. This ensures that no matter which dependency tries to pull in the unwanted library, it will be blocked. This is useful for removing logging bridges or conflicting utilities across the entire project.

What happens if I exclude a required transitive dependency?

If you exclude a dependency that another part of your application relies on, you will likely encounter ClassNotFoundException or NoSuchMethodError at runtime. In such cases, you must manually add the required dependency back into your dependencies block to ensure it remains available.

Does excluding a dependency affect the build speed?

Excluding dependencies does not significantly impact build speed, as resolution happens during the dependency phase. However, it can reduce the size of your final JAR or WAR file, leading to faster deployment times. It also helps avoid caching conflicts in CI/CD environments.

How do I handle version conflicts after excluding dependencies?

After excluding a conflicting dependency, you may need to explicitly declare the correct version of the library you want to use. Use the resolutionStrategy in your build.gradle to force a specific version if Gradle’s default selection is incorrect. For more details on managing connection pools after such changes, see HikariCP Connection Pool Configuration and Tuning in AKS.