Declaring Versions and Ranges
You can specify dependencies with exact versions or version ranges to define which versions your project can use:
dependencies {
implementation("org.springframework:spring-core:5.3.8")
implementation("org.springframework:spring-core:5.3.+")
implementation("org.springframework:spring-core:latest.release")
implementation("org.springframework:spring-core:[5.2.0, 5.3.8]")
implementation("org.springframework:spring-core:[5.2.0,)")
}
Understanding version declaration
Gradle supports various ways to declare versions and ranges:
Version | Example | Note |
---|---|---|
Exact version |
|
A specific version. |
Maven-style range |
|
When the upper or lower bound is missing, the range has no upper or lower bound. An upper bound exclude acts as a prefix exclude. |
Prefix version range |
|
Only versions exactly matching the portion before the Declaring a version as |
|
|
Matches the highest version with the specified status. See ComponentMetadata.getStatus(). |
Maven |
|
Indicates a snapshot version. |
Understanding version ordering
dependencies {
implementation("org.springframework:spring-core:1.1") // This is a newer version than 1.a
implementation("org.springframework:spring-core:1.a") // This is a older version than 1.1
}
Version ordering is used to:
-
Determine if a particular version is included in a range.
-
Determine which version is newest when performing conflict resolution (using "base versions").
Versions are ordered based on the following rules:
-
Splitting Versions into Parts:
-
Versions are divided into parts using the characters
[. - _ +]
. -
Parts containing both digits and letters are split further, e.g.,
1a1
becomes1.a.1
. -
Only the parts are compared, not the separators, so
1.a.1
,1-a+1
,1.a-1
, and1a1
are equivalent. (Note: There are exceptions during conflict resolution).
-
-
Comparing Equivalent Parts:
-
Numeric vs. Numeric: Higher numeric value is considered higher:
1.1 < 1.2
. -
Numeric vs. Non-numeric: Numeric parts are higher than non-numeric parts:
1.a < 1.1
. -
Non-numeric vs. Non-numeric: Parts are compared alphabetically and case-sensitively:
1.A < 1.B < 1.a < 1.b
. -
Extra Numeric Part: A version with an additional numeric part is higher, even if it’s zero:
1.1 < 1.1.0
. -
Extra Non-numeric Part: A version with an extra non-numeric part is lower:
1.1.a < 1.1
.
-
-
Special Non-numeric Parts:
-
dev
is lower than any other non-numeric part:1.0-dev < 1.0-ALPHA < 1.0-alpha < 1.0-rc
. -
rc
,snapshot
,final
,ga
,release
, andsp
are higher than any other string part, in this order:1.0-zeta < 1.0-rc < 1.0-snapshot < 1.0-final < 1.0-ga < 1.0-release < 1.0-sp
. -
These special values are not case-sensitive and their ordering does not depend on the separator used:
1.0-RC-1
==1.0.rc.1
.
-
Declaring rich versions
When you declare a version using the shorthand notation, then the version is considered a required version:
dependencies {
implementation("org.slf4j:slf4j-api:1.7.15")
}
dependencies {
implementation('org.slf4j:slf4j-api:1.7.15')
}
This means the minimum version will be 1.7.15
and it can be optimistically upgraded by the engine.
To enforce a strict version and ensure that only the specified version of a dependency is used, rejecting any other versions even if they would normally be compatible:
dependencies {
implementation("org.slf4j:slf4j-api") {
version {
strictly("[1.7, 1.8[")
prefer("1.7.25")
}
}
}
dependencies {
implementation("org.slf4j:slf4j-api") {
version {
strictly("[1.7, 1.8[")
prefer("1.7.25")
}
}
}
dependencies {
implementation('org.slf4j:slf4j-api') {
version {
strictly '[1.7, 1.8['
prefer '1.7.25'
}
}
}
dependencies {
implementation('org.slf4j:slf4j-api') {
version {
strictly '[1.7, 1.8['
prefer '1.7.25'
}
}
}
Gradle supports a model for rich version declarations, allowing you to combine different levels of version specificity.
The key terms, listed from strongest to weakest, are:
strictly
or!!
-
This is the strongest version declaration. Any version not matching this notation will be excluded. If used on a declared dependency,
strictly
can downgrade a version. For transitive dependencies, if no acceptable version is found, dependency resolution will fail.Dynamic versions are supported.
When defined, it overrides any previous
require
declaration and clears any previousreject
already declared on that dependency.
require
-
This ensures that the selected version cannot be lower than what
require
accepts, but it can be higher through conflict resolution, even if the higher version has an exclusive upper bound. This is the default behavior for a direct dependency.Dynamic versions are supported.
When defined, it overrides any previous
strictly
declaration and clears any previousreject
already declared on that dependency.
prefer
-
This is the softest version declaration. It applies only if there is no stronger non-dynamic version specified.
This term does not support dynamic versions and can complement
strictly
orrequire
.When defined, it overrides any previous
prefer
declaration and clears any previousreject
already declared on that dependency.
Additionally, there is a term outside the hierarchy:
reject
-
This term specifies versions that are not accepted for the module, causing dependency resolution to fail if a rejected version is selected.
Dynamic versions are supported.
Rich version declaration is accessed through the version
DSL method on a dependency or constraint declaration, which gives you access to MutableVersionConstraint:
dependencies {
implementation("org.slf4j:slf4j-api") {
version {
strictly("[1.7, 1.8[")
prefer("1.7.25")
}
}
constraints {
add("implementation", "org.springframework:spring-core") {
version {
require("4.2.9.RELEASE")
reject("4.3.16.RELEASE")
}
}
}
}
dependencies {
implementation('org.slf4j:slf4j-api') {
version {
strictly '[1.7, 1.8['
prefer '1.7.25'
}
}
constraints {
implementation('org.springframework:spring-core') {
version {
require '4.2.9.RELEASE'
reject '4.3.16.RELEASE'
}
}
}
}
To enforce strict versions, you can also use the !!
notation:
dependencies {
// short-hand notation with !!
implementation("org.slf4j:slf4j-api:1.7.15!!")
// is equivalent to
implementation("org.slf4j:slf4j-api") {
version {
strictly("1.7.15")
}
}
// or...
implementation("org.slf4j:slf4j-api:[1.7, 1.8[!!1.7.25")
// is equivalent to
implementation("org.slf4j:slf4j-api") {
version {
strictly("[1.7, 1.8[")
prefer("1.7.25")
}
}
}
dependencies {
// short-hand notation with !!
implementation('org.slf4j:slf4j-api:1.7.15!!')
// is equivalent to
implementation("org.slf4j:slf4j-api") {
version {
strictly '1.7.15'
}
}
// or...
implementation('org.slf4j:slf4j-api:[1.7, 1.8[!!1.7.25')
// is equivalent to
implementation('org.slf4j:slf4j-api') {
version {
strictly '[1.7, 1.8['
prefer '1.7.25'
}
}
}
The notation [1.7, 1.8[!!1.7.25
above is equivalent to:
-
strictly
[1.7, 1.8[
-
prefer
1.7.25
This means that the engine must select a version between 1.7
(included) and 1.8
(excluded).
If no other component in the graph needs a different version, it should prefer 1.7.25
.
A strict version cannot be upgraded and overrides any transitive dependency versions, therefore using ranges with strict versions is recommended. |
The following table illustrates several use cases:
Which version(s) of this dependency are acceptable? | strictly |
require |
prefer |
rejects |
Selection result |
---|---|---|---|---|---|
Tested with version |
1.5 |
Any version starting from |
|||
Tested with |
[1.0, 2.0[ |
1.5 |
Any version between |
||
Tested with |
[1.0, 2.0[ |
1.5 |
Any version between |
||
Same as above, with |
[1.0, 2.0[ |
1.5 |
1.4 |
Any version between |
|
No opinion, works with |
1.5 |
|
|||
No opinion, prefer the latest release. |
|
The latest release at build time. |
|||
On the edge, latest release, no downgrade. |
|
The latest release at build time. |
|||
No other version than 1.5. |
1.5 |
1.5, or failure if another |
|||
|
[1.5,1.6[ |
Latest |
Lines annotated with a lock (🔒) indicate situations where leveraging dependency locking is recommended. NOTE: When using dependency locking, publishing resolved versions is always recommended.
Using strictly
in a library requires careful consideration, as it affects downstream consumers.
However, when used correctly, it helps consumers understand which combinations of libraries may be incompatible in their context.
For more details, refer to the section on overriding dependency versions.
Rich version information is preserved in the Gradle Module Metadata format.
However, converting this information to Ivy or Maven metadata formats is lossy.
The highest level of version declaration— |
Endorsing strict versions
Gradle resolves any dependency version conflicts by selecting the greatest version found in the dependency graph. Some projects might need to divert from the default behavior and enforce an earlier version of a dependency e.g. if the source code of the project depends on an older API of a dependency than some of the external libraries.
In general, forcing dependencies is done to downgrade a dependency. There are common use cases for downgrading:
-
A bug was discovered in the latest release.
-
Your code depends on an older version that is not binary compatible with the newer one.
-
Your code does not use the parts of the library that require a newer version.
Forcing a version of a dependency requires careful consideration, as changing the version of a transitive dependency might lead to runtime errors if external libraries expect a different version. It is often better to upgrade your source code to be compatible with newer versions if possible. |
Let’s say a project uses the HttpClient
library for performing HTTP calls.
HttpClient
pulls in Commons Codec
as transitive dependency with version 1.10
.
However, the production source code of the project requires an API from Commons Codec
1.9
which is no longer available in 1.10
.
The dependency version can be enforced by declaring it as strict
it in the build script:
dependencies {
implementation("org.apache.httpcomponents:httpclient:4.5.4")
implementation("commons-codec:commons-codec") {
version {
strictly("1.9")
}
}
}
dependencies {
implementation 'org.apache.httpcomponents:httpclient:4.5.4'
implementation('commons-codec:commons-codec') {
version {
strictly '1.9'
}
}
}
Consequences of using strict versions
Using a strict version must be carefully considered:
-
For Library Authors: Strict versions effectively act like forced versions. They take precedence over transitive dependencies and override any other strict versions found transitively. This could lead to build failures if the consumer project requires a different version.
-
For Consumers: Strict versions are considered globally during resolution. If a strict version conflicts with a consumer’s version requirement, it will trigger a resolution error.
For example, if project B
strictly
depends on C:1.0
, but consumer project A requires C:1.1
, a resolution error will occur.
To avoid this, it is recommended to use version ranges and a preferred version within those ranges.
For example, B
might say, instead of strictly 1.0
, that it strictly depends on the [1.0, 2.0[
range, but prefers 1.0
.
Then if a consumer chooses 1.1
(or any other version in the range), the build will no longer fail.
Declaring without version
For larger projects, it’s advisable to declare dependencies without versions and manage versions using platforms:
dependencies {
implementation("org.springframework:spring-web")
}
dependencies {
constraints {
implementation("org.springframework:spring-web:5.0.2.RELEASE")
}
}
dependencies {
implementation 'org.springframework:spring-web'
}
dependencies {
constraints {
implementation 'org.springframework:spring-web:5.0.2.RELEASE'
}
}
This approach centralizes version management, including transitive dependencies.
Declaring dynamic versions
There are many situations where you might need to use the latest version of a specific module dependency or the latest within a range of versions. This is often necessary during development or when creating a library that needs to be compatible with various dependency versions. Projects might adopt a more aggressive approach to consuming dependencies by always integrating the latest version to access cutting-edge features.
You can easily manage these ever-changing dependencies by using a dynamic version.
A dynamic version can be either a version range (e.g., 2.+
) or a placeholder for the latest available version (e.g., latest.integration
):
plugins {
`java-library`
}
repositories {
mavenCentral()
}
dependencies {
implementation("org.springframework:spring-web:5.+")
}
plugins {
id 'java-library'
}
repositories {
mavenCentral()
}
dependencies {
implementation 'org.springframework:spring-web:5.+'
}
Using dynamic versions and changing modules can lead to unreproducible builds. As new versions of a module are published, its API may become incompatible with your source code. Therefore, use this feature with caution.
For reproducible builds, it’s crucial to use dependency locking when declaring dependencies with dynamic versions. Without this, the module you request may change even for the same version, which is known as a changing version.
For example, a Maven SNAPSHOT module always points to the latest artifact published, making it a "changing module."
|
Declaring changing versions
A team may implement a series of features before releasing a new version of the application or library. A common strategy to allow consumers to integrate an unfinished version of their artifacts early is to release a module with a changing version. A changing version indicates that the feature set is still under active development and hasn’t released a stable version for general availability yet.
In Maven repositories, changing versions are commonly referred to as snapshot versions.
Snapshot versions contain the suffix -SNAPSHOT
.
The following example demonstrates how to declare a snapshot version on the Spring dependency:
plugins {
`java-library`
}
repositories {
mavenCentral()
maven {
url = uri("https://repo.spring.io/snapshot/")
}
}
dependencies {
implementation("org.springframework:spring-web:5.0.3.BUILD-SNAPSHOT")
}
plugins {
id 'java-library'
}
repositories {
mavenCentral()
maven {
url 'https://repo.spring.io/snapshot/'
}
}
dependencies {
implementation 'org.springframework:spring-web:5.0.3.BUILD-SNAPSHOT'
}
Gradle is flexible enough to treat any version as a changing version.
All you need to do is to set the property ExternalModuleDependency.setChanging(boolean) to true
.