Gradle Versions Plugin: A Read-Only Dependency Update Reporter for Gradle Builds

What Problem It Solves and Who It Is For

The Gradle Versions Plugin answers a narrow question: which of your dependencies, plugins, and the Gradle distribution itself have newer versions available? It is aimed at teams that want to know about updates without changing anything. The README is explicit that the plugin only reports; it never edits build files or version catalogs. That makes it suitable for engineers who need a periodic, low-risk check before deciding to upgrade. It is also useful for maintainers of multi-project builds who want a single report across all subprojects. The plugin follows the spirit of the Maven Versions Plugin, so anyone familiar with that tool will recognize the workflow: run a task, read a report, decide what to do next.

How the dependencyUpdates Task Works

The core is the dependencyUpdates task. When you run it, the plugin resolves your declared dependencies, compares each against available versions, and writes a report. The README shows that the report appears on the console and in build/dependencyUpdates/report.txt. It lists dependencies with later milestone versions, such as com.google.inject:guice [2.0 -> 7.0.0], and it also reports Gradle release-candidate updates. The task checks more than just your direct dependencies. It includes dependencies declared through a version catalog, and it also includes dependencies that plugins contribute lazily, such as the Kotlin standard library and tool versions for jacoco, checkstyle, and pmd. For those lazy contributions, the current version is whatever the contributing plugin supplies when the task runs, which may be a default bundled with Gradle that never appears in your build script. The README notes that an extra line is printed under such entries so they do not read as a resolution failure.

Getting It Running: Settings Plugin and Task Configuration

The recommended way to apply the plugin is as a settings plugin, not a project plugin. In settings.gradle.kts you add plugins { id("io.github.ben-manes.versions.settings") version "$version" }. In Groovy settings.gradle it is id 'io.github.ben-manes.versions.settings' version '$version'. The settings plugin covers the settings script's own plugins and buildscript dependencies, plus every project's plugins, buildscript dependencies, and dependencies. After applying it, you run ./gradlew dependencyUpdates. Configuration happens on the task in the root project's build script. In Kotlin you import com.github.benmanes.gradle.versions.updates.DependencyUpdatesTask and use tasks.named<DependencyUpdatesTask>("dependencyUpdates") { revision = "release"; outputFormatter = "json" }. In Groovy the same is done with tasks.named("dependencyUpdates").configure { revision = 'release'; outputFormatter = 'json' }. If your build has no root build script, you can configure the task from the settings script using gradle.rootProject { tasks.withType(DependencyUpdatesTask::class.java).configureEach { ... } }.

Task Properties and the Recommended Configuration

The task exposes properties that control what the report suggests. The README opens its task properties section with a recommended configuration that most builds need: a stability filter and a bound. The stability filter ensures that a pre-release version is not offered as an update to a stable version, which is a common annoyance when a project publishes release candidates. The bound lets you declare an upper limit so an upgrade the build has ruled out is not offered. There is also a revision property, as shown in the configuration example, which can be set to "release" to only consider release versions. The plugin supports filtering which configurations are checked, with filterConfigurations and filterDeclaredConfigurations, and the README has a whole subsection on choosing between them. It also respects declared bounds from constraints. For Gradle itself, there is a release channel setting and a configurable base URL for the Gradle versions API, which is useful if you want to point at a mirror or a different update source.

Report Output and Formats

The default output is a plain text report written to build/dependencyUpdates/report.txt, but you can change the format. The configuration example sets outputFormatter = "json", which is useful for parsing in scripts or CI. The report shows which dependencies are up-to-date, which exceed the latest version found, which have upgrades, and which failed to resolve. When a dependency cannot be resolved, the exception is logged at the info level, not as a hard failure. That means a broken dependency does not stop the report from being generated for the rest. The README also mentions optional parameters for the report, though the truncated material does not list them all. The report includes a line for Gradle release-candidate updates, as shown in the sample output: Gradle: [8.4 -> 9.7.0]. This is a separate category from dependency updates, which helps you see distribution upgrades at a glance.

Multi-Project Builds and Isolated Projects

The plugin has explicit support for multi-project builds. Because the settings plugin is applied once in the settings script, it automatically covers every subproject. The README has a section on shared task settings, which lets you configure the task once and have it apply across projects. There is also a section on composite builds, which suggests the plugin handles those as well, though the truncated material does not detail the mechanism. Per-project reports are possible, meaning each subproject can have its own report file. The plugin also supports isolated projects, which is a Gradle feature where projects are configured independently. That is a useful distinction because many plugins break under isolated projects. The README does not explain how the plugin achieves this, but the fact that it is listed suggests the authors considered it a supported scenario.

Limitations and Failure Modes

The most obvious limitation is that the plugin does not apply updates. It reports, you act. That is by design, but it means the plugin alone does not reduce the manual work of upgrading. A second limitation is that for lazily contributed plugin dependencies, the current version reported may be a default bundled with Gradle, not a version you actually chose. The README warns that this version appears nowhere in the build script, so you might see an update suggestion for something you never declared. That can be confusing. A third limitation is that the report only checks versions that are resolvable; if a dependency cannot be resolved, it is logged at info level and may not appear in the report at all. That means a broken repository could silently hide updates. The plugin also depends on the Gradle versions API for Gradle updates, and if that API changes or is unreachable, that part of the report fails.

Alternatives and Comparison

The main alternative is an automated updater like the Gradle Versions Plugin's related plugins, which the README references for tools that apply updates automatically. One such tool is the Gradle Update Plugin (gradle-update), which can update dependencies and Gradle itself by editing build files. The difference in approach is that the Versions Plugin is read-only, while an updater like gradle-update writes changes. That matters for safety: a read-only report can be run in CI without risk, but an updater requires review before committing changes. Another alternative is Dependabot, which works on GitHub and creates pull requests for dependency updates. Dependabot integrates with your repository and can run on a schedule, whereas the Versions Plugin runs locally or in your own CI. The Versions Plugin gives you a local, Gradle-native report with no external service dependency, but it does not automate the pull request workflow. If you want a fully automated pipeline, an updater is the better fit.

Maintenance, Upgrade Cost, and License

The plugin is actively maintained, with recent releases v0.61.0, v0.60.0, and v0.59.0 all pushed in August 2026. That suggests a steady release cadence. The README has a migration section for prior versions, including v0.60.0 and v0.59.0, which means upgrading the plugin may require changes to your build configuration. The migration notes are a concrete cost: you need to read them before upgrading the plugin itself. The plugin is licensed under Apache-2.0, which is permissive and allows commercial use with attribution. The license does not impose copyleft obligations, so it is safe to include in proprietary builds. The plugin is written in Groovy, which is a natural fit for Gradle, and it runs as a settings plugin, so it is applied once and affects the whole build. The upgrade cost is mostly about keeping the plugin version current and checking the migration notes, not about adapting your build files, since the plugin does not modify them.

Editorial conclusion

Adopt this plugin if you want a read-only, dependency-by-dependency view of what has newer versions available, especially in multi-project builds where you need a single report across all subprojects. Do not use it if you expect automatic upgrades or if you need to edit version catalogs directly; it explicitly does not modify build files. Before adopting, verify the plugin version against your Gradle version in the Compatibility section of the README, and test the stability filter with your own versioning scheme to ensure pre-releases are not offered as updates. The plugin is a reporting tool, not an updater, and that boundary is its main strength.

Official sources

1. Official README
2. Project repository
3. Release notes