Optional Dependency in Maven

1. Overview

This brief tutorial will describe Maven's <optional> tag and how we can use it to reduce the size and scope of a Maven project's artifact, such as a WAR, EAR, or JAR.

For a refresher on Maven, check out our comprehensive guide.

2. What is <optional>?

Sometimes we'll create a Maven project to be a dependency for other Maven projects. When working on such a project, it may be required to include one or more dependencies that are only useful to a subset of that project's features.

If an end-user doesn't use that feature subset, the project still transitively pulls in those dependencies. This bloats the user's project size unnecessarily, and might even introduce conflicting dependency versions with other project dependencies.

Ideally, we should split the project's feature subset into its own module and therefore not pollute the rest of the project. However, this is not always practical.

In order to exclude these special dependencies from the main project, we can apply Maven's <optional> tag to them. This forces any user who wants to use those dependencies to declare them explicitly. However, it does not force those dependencies into a project that doesn't need them.

3. How to Use <optional>

As we're going to see we can include the <optional> element with a value of true to make any Maven dependency optional.

Let's assume we have the following project pom:

<project>
    ...
    <artifactId>project-with-optionals</artifactId>
    ...
    <dependencies>
        <dependency>
            <groupId>com.baeldung</groupId>
            <artifactId>optional-project</artifactId>
            <version>0.0.1-SNAPSHOT</version>
            <optional>true</optional>
        </dependency>
    </dependencies>
</project>

In this example, although optional-project is labeled as optional, it remains as a usable dependency of project-with-optionals as if the <optional> tag was never there.

In order to see the effect of the <optional> tag, we need to create a new project that depends on project-with-optionals:

<project>
    ...
    <artifactId>main-project</artifactId>
    ...
    <dependencies>
        <dependency>
            <groupId>com.baeldung</groupId>
            <artifactId>project-with-optionals</artifactId>
            <version>0.0.1-SNAPSHOT</version>
        </dependency>
    </dependencies>
</project>

Now if we try to reference optional-project from within main-project, we see that optional-project doesn't exist. This is because the <optional> tag prevents it from being transitively included.

If we find that we need optional-project in our main-project, we simply need to declare it as a dependency.

4. Conclusion

In this article, we looked at Maven's <optional> tag. The main benefits of using the tag are that it can reduce a project's size and help prevent version conflicts. We also saw that the tag doesn't affect the project that uses it.

The source code in this article is available over on Github.