ben-manes/gradle-versions-plugin: a read-only dependency report for Gradle builds

What the dependencyUpdates task actually answers

Most dependency tooling in the Gradle ecosystem does something to your build: it resolves, it substitutes, it rewrites. This plugin does none of that. According to the README, it reports which of a build's dependencies, plugins and Gradle itself have newer versions available, following the Maven Versions Plugin. The output is a list of up-to-date, outdated, exceeded and unresolved entries, printed to the console and written to build/dependencyUpdates/report.txt.

The audience is anyone who owns a Gradle build and has to decide, deliberately, what to upgrade. That includes library maintainers who want a periodic inventory, and platform teams who need to know whether a subproject is pinned to something ancient. The README is explicit that the report includes dependencies declared through a version catalog, but that the plugin only reports and never edits build files or the catalog. Tools that apply updates automatically are listed separately under Related plugins. If your goal is an unattended bot that opens upgrade pull requests, this is the wrong half of the workflow.

Applying it once in the settings script instead of per project

The recommended application point is the settings script, not each project's build script. The README gives the reason: a settings plugin can report updates for the plugins and buildscript dependencies that the settings script itself declares, plus each project's plugins, buildscript dependencies and dependencies, and it covers every subproject in a multi-project build automatically.

That choice matters in composite and multi-project builds, where applying a plugin per project means the report only reflects whichever project you invoked. The README also notes the task is configured in the root project's build script, and for a build with no root build script, configuration can move into the settings script via gradle.rootProject. Version catalogs are read, not written.

One detail worth knowing before you read a report: the plugin also lists dependencies a plugin contributes lazily rather than ones the build declares, such as the Kotlin standard library and the tool versions of the jacoco, checkstyle and pmd plugins. Their current version is whatever the contributing plugin supplies at task runtime, so a tool version the build never sets shows up at the default bundled with Gradle, a version that appears nowhere in the build script. The README says an extra line is printed under such an entry so it does not read as a resolvable dependency.

Installing the plugin and reading your first report

The README's getting-started path is short. Add the settings plugin once, replacing the version placeholder with the current release shown in the badge at the top of the README page. The Kotlin form goes in settings.gradle.kts:

plugins {
  id("io.github.ben-manes.versions.settings") version "$version"
}

The Groovy form is the same declaration in settings.gradle:

plugins {
  id 'io.github.ben-manes.versions.settings' version '$version'
}

Then run the task:

./gradlew dependencyUpdates

The README states the report prints to the console and is written to build/dependencyUpdates/report.txt. Its sample output shows entries in the form com.google.inject:guice [2.0 -> 7.0.0] with a project URL underneath, and a separate section for Gradle release-candidate updates such as Gradle: [8.4 -> 9.7.0].

To configure the task, the README puts it in the root project's build script. This example turns the output into JSON and restricts revisions to releases:

import com.github.benmanes.gradle.versions.updates.DependencyUpdatesTask

tasks.named<DependencyUpdatesTask>("dependencyUpdates") {
  revision = "release"
  outputFormatter = "json"
}

If the build has no root build script, the README shows the same configuration applied from the settings script through gradle.rootProject and tasks.withType(DependencyUpdatesTask).

Filters, revisions and the bounds you already declared

Two knobs decide what the report contains, and they are easy to confuse. filterConfigurations selects which configurations the task resolves and inspects, while filterDeclaredConfigurations narrows the report to dependencies the build declares rather than ones inherited transitively. The README covers both and includes a section on choosing between them, plus notes on how each behaves with the Kotlin Gradle Plugin and the Android Gradle Plugin. A default report that looks too long, or one that omits something you expected, is usually a filter question rather than a resolution failure.

The version side has its own settings. Revisions control which kinds of version are offered. Filtering unstable versions keeps pre-release candidates out of the report. Respecting declared bounds stops the plugin from proposing an upgrade the build has already ruled out, which is the setting that prevents a report full of suggestions you will never accept. Gradle itself has a release channel setting and a configurable versions API base URL.

The README's recommended configuration combines a stability filter with a declared bound, and describes it as what most builds need. That framing is honest about the default: without a stability filter, a pre-release can surface as an available update, and without bounds, so can a version your build has excluded. Neither is a bug, but both make the first run noisier than the steady-state report. Cache invalidation is documented separately, which matters if you run the task repeatedly and wonder why the answers look stale.

Where the report stops being useful

The plugin does not resolve dependency conflicts, and it does not tell you whether an upgrade is safe. It compares versions. A dependency that cannot be resolved is logged at the info level rather than failing the task, which means a broken resolution can pass quietly unless you are reading the log.

The read-only design is the real boundary. If your team wants dependency bumps applied automatically, the README points to other tools under Related plugins rather than claiming this one does it. There is also a category of entry that is not actionable at all: the lazily contributed tool versions described earlier, where the reported current version comes from whatever the contributing plugin supplies at runtime. An entry like that cannot be fixed by editing the build script, because the build script never set it.

Output format is another constraint. The report is text by default, with JSON available through outputFormatter, and the examples directory ships a sample HTML report image. The README does not document a machine-readable schema for the JSON output, so any dashboard you build on top of it is parsing something the project has not promised to keep stable.

How it differs from Gradle's own dependency reporting and from updater tools

Gradle itself can tell you what a configuration resolves to, and the dependencyUpdates task builds on that resolution machinery. The difference is the comparison step. Gradle reports the graph your build currently has; this plugin goes and asks what versions exist and diffs the two, then groups the result. It also reaches outside the project's own dependencies to cover plugins, buildscript dependencies and Gradle releases, which the README lists as the reason to apply it as a settings plugin.

The other comparison is against tools that apply updates. Those consume the same kind of version information and then rewrite the build or the version catalog. The README draws that line itself: the plugin reports, the related tools edit. In practice the two are complementary, and the split is deliberate, because a version bump that compiles is not the same as a version bump that is correct. The cost of the split is that this plugin will never close the loop for you, and if your build has hundreds of outdated entries, the report alone does not reduce that number.

Maintenance, licence and the cost of upgrading the plugin

The repository is not archived, and the last push was on 2026-08-09, the same date as the v0.61.0 release. The two releases before it, v0.60.0 and v0.59.0, landed on 2026-08-07 and 2026-08-03, so the recent cadence is dense rather than occasional.

That cadence has a cost the README documents directly: there is a Migrating from prior versions section with subsections for v0.60.0, v0.59.0, v0.58.0, v0.57.0, v0.56.0, v0.55.0 and v0.54.0 and earlier. Frequent releases plus a migration section means the upgrade path is not always a version bump. Budget for reading the relevant subsection when you move across one of those boundaries, especially around v0.59.0 and v0.60.0, which are the two most recent changes.

The licence is Apache-2.0, stated in the repository's LICENSE.txt and in the project metadata. That is a permissive licence, and it is the same licence the plugin's dependencies may or may not share; the README does not enumerate them, so treat transitive licence review as your own work rather than something the project has done for you. Nothing in the README describes a commercial edition, a hosted service or a support contract.

Editorial conclusion

Adopt it if you maintain a Gradle build of any size and want a single task that lists outdated dependencies, plugins and Gradle releases without touching your files. Skip it if you need automated upgrades, since the README states the plugin never edits build files or the version catalog. Before relying on it, run ./gradlew dependencyUpdates on your own build and check whether the default output includes the configurations you care about, because the report is filtered by filterConfigurations and filterDeclaredConfigurations, and confirm which pre-release versions the default revision setting allows through.

Frequently asked questions

Official sources

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