We don't plan add new functionality to this plugin. We focus mainly on compatibility with new version of Gradle.
Much of the functionality of this project can be replicated by a new feature coming in Gradle 4.6 and the default in Gradle 5.0. We would recommend new users seeking this functionality to adopt the feature directly from the Gradle. You can find details Sharing dependency versions between projects
We are actively working on switching from this plugin to Gradle Platform support too with eventual long term goal to deprecate this plugin.
A Gradle plugin that allows you to leave off version numbers in your dependencies section and have versions recommended by several possible sources. The most familiar recommendation provider that is supported is the Maven BOM (i.e. Maven dependency management metadata). The plugin will control the versions of any dependencies that do not have a version specified.
- Nebula Dependency Recommender
- Usage
- Dependency recommender configuration
- Built-in recommendation providers
- Producing a Maven BOM for use as a dependency recommendation source
- Version selection rules
- Conflict resolution and transitive dependencies
- Accessing recommended versions directly
- Notes on POMs Generated by Gradle maven-publish
Dependency recommenders are the source of versions. If more than one recommender defines a recommended version for a module, the last recommender specified will win.
dependencyRecommendations {
propertiesFile uri: 'http://somewhere/extlib.properties', name: 'myprops'
}
dependencies {
nebulaRecommenderBom 'netflix:platform:latest.release@pom'
implementation 'com.google.guava:guava' // no version, version is recommended
implementation 'commons-lang:commons-lang:2.6' // I know what I want, don't recommend
implementation project.recommend('commmons-logging:commons-logging', 'myprops') // source the recommendation from the provider named myprops'
}You can also specify bom lookup via a configuration
dependencies {
nebulaRecommenderBom 'test.nebula:bom:1.0.0@pom'
}Experimental Isolated Projects resolution changes are disabled by default. Opt in for
the build using gradle.properties:
nebula.dependency-recommender.isolatedProjectsSupport=trueAlternatively, pass -Pnebula.dependency-recommender.isolatedProjectsSupport=true.
Leaving the property unset or setting it to false retains legacy resolution behavior,
including the shared bomResolver service and its coordinate-based cache. Enabling Gradle's
Isolated Projects mode does not enable this flag automatically, and the flag does not enable
Gradle's mode. The setting is tracked as a configuration-cache input; changing it selects
the corresponding behavior on the next invocation, including when reusing the same daemon.
Use the build-wide property rather than project extra properties or changing it after plugin
application.
With the flag enabled, the default ConflictResolved strategy skips dependency-project declaration inspection,
which it does not use. Sibling and nested project dependencies with complete project-local
recommendation policy are tested on Gradle 9.1.0 and 9.7.1 with strict ordinary configuration
cache and Isolated Projects. Coverage compares resolved artifacts and reasons without cache,
on cold storage, on warm reuse, and after policy, producer declaration, and force changes.
Each project applies and configures the plugin locally. Policy misses can require
explicit local ancestor layers as described below. OverrideTransitives uses producer-owned
inspection metadata when participating producers adopt the plugin locally; see its migration
requirements below.
With the flag enabled, BOM recommendation and reason caches belong to each project and configuration for the
current build. Matching BOM coordinates in different projects still resolve against each
project's repositories and interpolation inputs. Coverage on Gradle 9.1.0 and 9.7.1 verifies
fixed and dynamic BOM requests, changed POM bytes, repositories and Gradle/system properties,
parallel projects, strict ordinary configuration cache and Isolated Projects. Automatic eager
resolution and both public manual-resolution adapters retain their existing timing. Affected
builds can select different versions and reasons because the first project's BOM policy no
longer contaminates other projects. Service names become bomResolver plus each project path;
use the public manual-resolution adapters instead of looking up the experimental services by name.
Turning the flag off restores the legacy cache behavior, including its known sharing defects.
This flag is the rollout gate for future experimental Isolated Projects resolution work. Automatic parent policy import and automatic cross-project core-BOM distribution remain outside the supported isolated scope. Core-BOM consumers can adopt local policy as described below. With the flag disabled, ordinary parent-to-child recommendation inheritance is unchanged. The existing BOM publishing/configuration-cache fix remains active independently of this flag.
A BOM's Maven <parent> still contributes inherited properties and dependency management.
The project-owned cache preserves this behavior; enabling the support flag does not detach
a child BOM from its Maven parent. Parent POMs are resolved by coordinates using the consuming
project's Gradle repositories. Declare repositories containing the child BOM and its parents
locally, and supply any required Gradle or system interpolation properties before resolution.
Repositories declared inside POMs and filesystem-relative parent lookup are not used.
Regression coverage on Gradle 9.1.0 and 9.7.1 verifies identical child/parent coordinates with different repository contents in sibling and nested projects, multiple parent levels, inherited property precedence, and Gradle/system interpolation changes. It compares actual JAR contents, selected versions, and dependency-insight reasons without configuration cache, with strict ordinary cache storage/reuse, and with strict Isolated Projects storage/reuse. Changing only a local repository's parent POM, while leaving the child BOM unchanged, also invalidates the tested cached policy. Reasons continue to identify the effective child BOM; inherited parents are not added as separate recommendation sources.
Maven inheritance requires no additional DSL. Automatic eager resolution and
eagerlyResolve=false with either manual-resolution adapter retain their existing timing.
The default-false support gate and rollback instructions above still apply.
Remote repository refresh policy and provider fallback paths need separate evidence.
Gradle root/ancestor recommendation
inheritance uses the local policy adoption described below.
The non-core Maven BOM recommendation provider builds effective dependency management from
BOM imports (<type>pom</type> and <scope>import</scope>), including nested imports.
With the support flag enabled, each imported model uses the consuming project's repositories
and interpolation inputs. Declare repositories for the complete import graph locally.
Imported models retain their own Maven property context; properties in the importing BOM
do not act as inherited parent properties for an import.
Within a Maven model, explicit dependency-management entries override imported entries. When imports manage the same dependency, the first imported definition wins. Recommendation reasons identify the effective top-level BOM declared to the provider; imported models do not become separate reason sources.
Local Maven regressions on Gradle 9.1.0 and 9.7.1 verify resolved JAR contents, selected
versions and native reasons for sibling/nested consumers, parallel and reversed order,
changed repositories, import order and Gradle/system interpolation inputs. Editing only a
direct or nested imported POM invalidates the tested cached policy while the top-level BOM
stays unchanged. Comparisons cover no cache, strict ordinary configuration-cache storage/reuse,
and strict Isolated Projects storage/reuse. Both manual-resolution adapters retain late
customization timing with eagerlyResolve=false; unset/false/true and rollback are also
checked in one daemon.
These cases require no additional DSL or migration. The existing default-false flag and rollback instructions still apply. Remote repository refresh policy and fallback-provider behavior remain outside this imported-BOM coverage.
An explicit lookup through the non-core Maven BOM provider can run before automatic eager resolution
or a manual-resolution adapter has populated the service cache. This uses the provider's
direct-parser fallback. With the support flag enabled, fallback interpolation reads Gradle
and system properties through the owning project's provider factory, avoiding the dynamic
Project.getProperties() access rejected by Gradle 9.7.1 Isolated Projects. The flag-disabled
fallback retains its existing project-property behavior.
Supply external interpolation inputs in gradle.properties, with -P, or as system
properties when opting in. Move any interpolation values supplied only through project extra
properties to those inputs; the enabled fallback uses the same sources as the service parser.
Maven model properties and system/Gradle precedence are retained. Local regression coverage
on Gradle 9.1.0 and 9.7.1 checks actual artifacts and native reasons, sibling/nested ownership,
parallel/reversed ordering, changed BOM/property inputs, strict ordinary configuration-cache
and Isolated Projects storage/reuse, and flag rollback in one daemon.
Finish customization before explicitly requesting recommendations. Setting
eagerlyResolve=false disables automatic eager resolution; it does not postpone a direct
lookup. Both manual-resolution adapters and the default eager timing are unchanged. Existing
fallback error handling is also unchanged; this coverage does not establish compatibility
for service failures, invalid BOMs, remote refresh policy, other source types, or custom streams.
To roll back, unset the support flag or set it to false, and disable Gradle's Isolated
Projects mode for the legacy path.
With the support flag enabled, non-core OverrideTransitives resolution reads producer-owned
Gradle metadata instead of another project's configurations. Explicitly versioned declarations
in dependency projects remain protected from transitive recommendations. Versionless requests
can still receive recommendations, and forces retain precedence. Strategy selection remains
lazy, including customization in afterEvaluate.
Before opting in:
- Apply the same dependency-recommender plugin version locally in every producer reached
through project dependencies, including nested producers. A producer can keep the default
ConflictResolvedstrategy. Java or other language plugins alone do not export inspection metadata; missing participation fails with an actionable error. - Supply complete recommendation policy locally in each consumer, including any required ancestor layers. Use a shared convention applied locally to keep policies equivalent.
- Set the build-wide support flag to
true. Compare resolved artifacts, versions, and dependency-insight reasons with the legacy build, then test strict configuration-cache storage/reuse and Isolated Projects, including changed producer declarations and policy.
Inspection deliberately follows the declared project dependency's target configuration, or
default when none is specified, retaining the existing inspection scope. It does not replace
that scope with the normally selected variant: for example, a test-fixtures variant can contain
declarations absent from default. Ordinary classpath variant selection is unchanged. The
separate inspection graph resolves no external modules or artifacts and requires no generated
tasks. Each declared producer scope is inspected independently, preserving declarations even
when different producer projects publish identical coordinates. A local visited set terminates
project cycles. Configurations prefixed nebulaRecommenderProjectInspection_ and their metadata
are internal; do not use them in build DSL or configure them through broad configuration rules.
Explicit inspection targets must be consumable. Unused non-consumable configurations keep
their dependency providers deferred. If a default-only legacy inspection edge points to a
non-consumable target that the actual classpath never selects, opt-in resolution reports that
unsupported scope explicitly. It does not silently drop those declarations. The conventional
default inspection scope remains available regardless of its role.
Coverage on Gradle 9.1.0 and 9.7.1 compares real local Maven artifacts and contents, versions, and native reasons with legacy resolution. It includes sibling/nested producers, multiple source configurations, matching producer coordinates, explicit targets, test fixtures, project cycles, changed declarations, policy and forces, parallel/reversed task order, strict ordinary configuration cache and Isolated Projects cold/warm runs, and rollout/rollback in one daemon. Composite builds and custom recommendation strategies are outside this guarantee; custom strategies retain their existing inspection path.
To roll back, remove the property or set it to false, and disable Gradle's Isolated Projects
mode for the legacy path. The next invocation restores legacy inspection, including in the
same daemon. The flag remains disabled by default; existing builds require no migration until
they opt in. This does not import a root BOM or ancestor policy automatically.
On Gradle 9+, the build service is already the default. The existing
nebula.dependency-recommender.useBuildService setting only opts into that mechanism:
false does not disable the Gradle 9+ default. With experimental support enabled,
the plugin selects that default before looking up the setting. This avoids dynamic
parent-property access, including the Gradle 9.1.0 isolation failure when no local value
is declared. No migration of this setting is needed on Gradle 9+; its local, inherited,
and build-wide values cannot change service selection there. With the flag disabled,
the legacy lookup remains, including its parent-property isolation limitation on 9.1.0.
Automatic BOM resolution still runs after project evaluation. To defer it, use
dependencyRecommendations.eagerlyResolve = false, finish customization, and call
either existing public manual-resolution adapter. This setting is independent of the
build-service default and retains its timing. Tests on Gradle 9.1.0 and 9.7.1 cover
missing, ancestor, local and Gradle property declarations, both adapters, actual artifacts
and reasons, strict cache storage/reuse, Isolated Projects, and rollout/rollback.
With the flag enabled, consumers provide equivalent ancestor policy through a local
convention. For a project at :parent:leaf, configure its sources locally:
dependencyRecommendations {
// Consumer providers always take precedence over inherited layers.
map name: 'local', recommendations: ['sample:local': '3.0']
inheritedPolicy(':parent') {
propertiesFile file: new File(rootDir, 'parent-policy.properties')
}
inheritedPolicy(':') {
mavenBom module: 'sample:platform:1.0'
}
}The paths label policy scopes; they do not access those projects. Declare layers nearest parent first and root last, including an empty layer for an intermediate scope without policy. Repeated calls for an existing layer append providers. Lookup checks consumer providers first, then each local layer, retaining provider LIFO order and fuzzy matching. Reasons retain the existing independent lookup: the nearest nonempty reason set wins, even if a more distant scope supplied the version. A needed undeclared layer produces an actionable error instead of silently omitting inherited policy or reading a foreign extension.
Apply a shared convention in each consumer to supply equivalent sources, repositories, and interpolation values. Changes to the shared convention, files, BOMs, and tracked properties then affect each consumer. A change made only to an ancestor's build script is not automatically imported. Existing parent/root-only declarations remain supported on the flag-disabled path; adopting local layers is required for inherited policy on the flag-enabled path, including ordinary configuration-cache builds. No settings plugin is required.
Each layer uses the existing provider DSL with consumer-owned instances and a separate local
BOM configuration. Providers are queried lazily; custom callbacks must be local and deterministic.
The consumer controls strategy, strictness, and exclusions. The top-level eagerlyResolve
property is shared across its layers: the normal eager default and both public manual
resolution adapters resolve the complete local chain after customization. Disabling
automatic eager resolution still permits late BOM replacement followed by a manual call.
Local Maven coverage compares legacy inheritance with adopted sibling/nested consumers on Gradle 9.1.0 and 9.7.1 using real artifacts and reasons, strict cache storage/reuse and Isolated Projects, changed policy inputs, explicit versions, forces, and unused-source laziness.
Core-BOM mode uses Gradle's native platform resolution and remains a separate opt-in:
systemProp.nebula.features.coreBomSupport=true
nebula.dependency-recommender.isolatedProjectsSupport=trueWith experimental support unset or false, core mode keeps its existing behavior: a plugin
applied at the root distributes its BOM policy to descendant classpaths. With experimental
support true, each plugin instance wires only its own project's configurations to its live
local nebulaRecommenderBom. It neither enumerates descendants nor copies a root BOM into
them. A root BOM therefore still applies to the root, but does not automatically apply to
children on the enabled path. Consumers must adopt equivalent local policy before rollout,
including in ordinary builds without Isolated Projects.
Move the effective shared policy into a convention applied in each participating consumer. For example, this script is evaluated separately in each project:
// dependency-policy.gradle
repositories { maven { url = uri('https://repo.example.org/releases') } }
dependencyRecommendations {
mavenBom module: 'example:platform:1.0', enforced: true
// Include all effective root/parent BOMs and exact-name exclusions here.
}Keep the root applying the plugin and policy for the legacy path:
// Root build.gradle: keep your existing plugin version.
plugins { id 'com.netflix.nebula.dependency-recommender' version '<your-version>' }
apply from: new File(rootDir, 'dependency-policy.gradle')In each consumer, including nested consumers, apply the plugin and the same policy locally when adopting the experimental path:
// Consumer build.gradle
plugins { id 'com.netflix.nebula.dependency-recommender' apply false }
if (providers.gradleProperty('nebula.dependency-recommender.isolatedProjectsSupport')
.orElse('false').get().toBoolean()) {
apply plugin: 'com.netflix.nebula.dependency-recommender'
apply from: new File(rootDir, 'dependency-policy.gradle')
}A convention plugin can supply the same local setup. Reproduce all effective BOM declarations,
repositories, exclusions, and any relevant local inputs; a change made only to an ancestor's
build script is not imported. The inheritedPolicy layers above describe recommender-provider
fallback in non-core mode; native core mode needs its BOM declarations in the consumer's main
dependencyRecommendations container. An unadopted child may fail on a versionless dependency
or resolve an explicitly versioned dependency without the intended BOM constraints. There is
no automatic check that every child has adopted the policy.
The enabled path preserves platform versus enforcedPlatform semantics, classpath and
annotation-processor name filtering, exact-name exclusions, and wiring after project evaluation.
Existing core-mode behavior ignores excludeConfigurationPrefixes; this opt-in does not change
that limitation. The default eager resolution remains after evaluation. For late customization,
set eagerlyResolve = false, finish changes, and call either public manual-resolution adapter.
Local classpaths then see the final BOM policy, including a replacement made after the wiring
callback. Legacy descendant snapshot copies retain their existing timing when the flag is off.
Before rollout, compare actual artifacts, versions, and dependency-insight reasons against the
legacy build, then run twice with strict configuration cache and twice with Isolated Projects.
Test changed policy inputs too. To roll back the example, set the support flag to false or
remove it: consumer application stops and root distribution resumes on the next build, including
in the same daemon. Disable Gradle's Isolated Projects mode for that legacy path. Core mode's
separate switch is unchanged.
Regression coverage uses local Maven artifacts for sibling and nested consumers on Gradle 9.1.0
and 9.7.1, native selection reasons, explicit versions, forces, platform/enforced-platform,
manual adapters, changed BOM inputs, and strict cache storage/reuse. Java publication checks
cover resolved POM versions and absence of the policy BOM from POM/module dependencies; other
publishing plugins, custom recommendation providers in core mode, and composite builds are not
established by this coverage. Automatic distribution remains separate work. Non-core
OverrideTransitives project inspection has its own adoption requirements documented above.
Several recommendation providers pack with the plugin. The file-based providers all a shared basic configuration that is described separately.
Suppose you want to produce a BOM that contains a recommended version for commons-configuration.
buildscript {
repositories { mavenCentral() }
dependencies { classpath 'com.netflix.nebula:nebula-dependency-recommender:4.+' }
}
apply plugin: 'maven-publish'
apply plugin: 'com.netflix.nebula.dependency-recommender'
group = 'netflix'
configurations { implementation }
repositories { mavenCentral() }
dependencies {
implementation 'commons-configuration:commons-configuration:1.6'
}
publishing {
publications {
parent(MavenPublication) {
// the transitive closure of this configuration will be flattened and added to the dependency management section
nebulaDependencyManagement.fromConfigurations { configurations.implementation }
// alternative syntax when you want to explicitly add a dependency with no transitives
nebulaDependencyManagement.withDependencies { 'manual:dep:1' }
// the bom will be generated with dependency coordinates of netflix:module-parent:1
artifactId = 'module-parent'
version = 1
// further customization of the POM is allowed if desired
pom.withXml { asNode().appendNode('description', 'A demonstration of maven POM customization') }
}
}
repositories {
maven {
url = "$buildDir/repo" // point this to your destination repository
}
}
}fromConfigurations accepts a closure returning one resolvable Configuration or an
Iterable<Configuration>. It includes resolved transitive modules and Gradle's selected
versions. withDependencies accepts a closure returning one coordinate string or an
Iterable<String> and does not resolve transitives. Both closures run during publication
configuration; configuration resolution stays lazy until the publication is needed.
Multiple calls append contributions to one dependency-management section, preserving
duplicates between contributions and the registration order of user pom.withXml actions.
BOM POM generation with these APIs is verified on Gradle 9.1.0 and 9.7.1 with JDK 21,
using strict configuration cache both with and without Isolated Projects. Coverage checks
the generated XML against a no-cache build, cold storage, warm reuse, regeneration after
deleting the POM, and changed dependency coordinates and versions. It includes a single
project and independently configured sibling/nested publications. Unselected publications
do not resolve their configurations. On Gradle 9.1 use
-Dorg.gradle.unsafe.isolated-projects=true; on Gradle 9.7 use --isolated-projects.
This scope covers project-local publications using Gradle's maven-publish plugin.
Apply and configure plugins in each participating project. Custom pom.withXml actions
and subclass callbacks through the protected closure helper must themselves satisfy
Gradle's configuration-cache restrictions. This does not establish general Isolated
Projects support for the recommender: automatic ancestor policy import and automatic
cross-project core-BOM distribution still have isolation limitations. Core consumers can adopt
the local policy convention documented above. Other publishing-plugin combinations are not
covered by this cache matrix.
The resultant BOM would look like this:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
<groupId>netflix</groupId>
<artifactId>module-parent</artifactId>
<version>1</version>
<packaging>pom</packaging>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>commons-digester</groupId>
<artifactId>commons-digester</artifactId>
<version>1.8</version>
</dependency>
<dependency>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
<version>1.1.1</version>
</dependency>
<dependency>
<groupId>commons-lang</groupId>
<artifactId>commons-lang</artifactId>
<version>2.4</version>
</dependency>
<dependency>
<groupId>commons-configuration</groupId>
<artifactId>commons-configuration</artifactId>
<version>1.6</version>
</dependency>
<dependency>
<groupId>commons-beanutils</groupId>
<artifactId>commons-beanutils</artifactId>
<version>1.7.0</version>
</dependency>
<dependency>
<groupId>commons-collections</groupId>
<artifactId>commons-collections</artifactId>
<version>3.2.1</version>
</dependency>
<dependency>
<groupId>commons-beanutils</groupId>
<artifactId>commons-beanutils-core</artifactId>
<version>1.8.0</version>
</dependency>
<dependency>
<groupId>manual</groupId>
<artifactId>dep</artifactId>
<version>1</version>
</dependency>
</dependencies>
</dependencyManagement>
<description>A demonstration of maven POM customization</description>
</project>The hierarchy of preference for versions is:
configurations.all {
resolutionStrategy {
force 'commons-logging:commons-logging:1.2'
}
}
dependencyRecommendations {
map recommendations: ['commons-logging:commons-logging': '1.1']
}
dependencies {
implementation 'commons-logging:commons-logging' // version 1.2 is selected
}Direct dependencies with a version qualifier trump recommendations, even if the version qualifier refers to an older version.
dependencyRecommendations {
map recommendations: ['commons-logging:commons-logging': '1.2']
}
dependencies {
implementation 'commons-logging:commons-logging:1.0' // version 1.0 is selected
}This is the basic case described elsewhere in the documentation;
dependencyRecommendations {
map recommendations: ['commons-logging:commons-logging': '1.0']
}
dependencies {
implementation 'commons-logging:commons-logging' // version 1.0 is selected
}Transitive dependencies interact with the plugin in different ways depending on which of two available strategies is selected.
Consider the following example with dependencies on commons-configuration and commons-logging. commons-configuration:1.6 depends on commons-logging:1.1.1. In this case, the transitive dependency on commons-logging via commons-configuration is conflict resolved against the recommended version of 1.0 if we have a direct on commons-logging. Normal Gradle conflict resolution selects 1.1.1.
dependencyRecommendations {
strategy ConflictResolved // this is the default, so this line is NOT necessary
map recommendations: ['commons-logging:commons-logging': '1.0']
}
dependencies {
implementation 'commons-logging:commons-logging'
implementation 'commons-configuration:commons-configuration:1.6'
}In the following example version commons-logging:commons-logging:1.0 is selected even though commons-logging is not explicitly mentioned in dependencies. This would not work with the ConflictResolved strategy:
dependencyRecommendations {
strategy OverrideTransitives
map recommendations: ['commons-logging:commons-logging': '1.0']
}
dependencies {
implementation 'commons-configuration:commons-configuration:1.6'
}If no recommendation can be found in the recommendation sources for a dependency that has no version, but a version is provided by a transitive, the version provided by the transitive is applied. In this scenario, if several transitives provide versions for the module, normal Gradle conflict resolution applies.
dependencyRecommendations {
map recommendations: ['some:other-module': '1.1']
}
dependencies {
implementation 'commons-configuration:commons-configuration:1.6'
implementation 'commons-logging:commons-logging' // version 1.1.1 is selected
}The dependencyRecommendations container can be queried directly for a recommended version:
dependencyRecommendations.getRecommendedVersion('commons-logging', 'commons-logging')The getRecommendedVersion method returns null if no recommendation is found.
dependencyRecommendations {
strictMode = true
}Strict mode will cause the plugin to fail if a dependency version is omitted and not found in a recommendation source.
Gradle requires that version numbers are present in the dependencies block to create a valid POM file that includes version numbers. To fix the issue this causes when using the dependency-recommender plug-in, apply the nebula.maven-resolved-dependencies plug-in from the nebula-publishing-plugin set.