Version Catalogs
A version catalog is a selected list of dependencies that can be referenced in build scripts, simplifying dependency management.
Instead of specifying dependencies directly using string notation, you can pick them from a version catalog:
dependencies {
implementation(libs.groovy.core)
}
dependencies {
implementation(libs.groovy.core)
}
In this example, libs
represents the catalog, and groovy
is a dependency available in it.
Where the version catalog defining libs.groovy.core
is a libs.version.toml
file in the gradle
directory:
[libraries]
groovy-core = { group = "org.codehaus.groovy", name = "groovy", version = "3.0.5" }
Version catalogs offer several advantages:
-
Type-Safe Accessors: Gradle generates type-safe accessors for each catalog, enabling autocompletion in IDEs.
-
Centralized Version Management: Each catalog is visible to all projects in a build.
-
Dependency Bundles: Catalogs can group commonly used dependencies into bundles.
-
Version Separation: Catalogs can separate dependency coordinates from version information, allowing shared version declarations.
-
Conflict Resolution: Like regular dependency notation, version catalogs declare requested versions but do not enforce them during conflict resolution.
While version catalogs define versions, they don’t influence the dependency resolution process. Gradle may still select different versions due to dependency graph conflicts or constraints applied through platforms or dependency management APIs.
Versions declared in a catalog are typically not enforced, meaning the actual version used in the build may differ based on dependency resolution. |
Accessing a catalog
To access items in a version catalog defined in the standard libs.versions.toml
file located in the gradle
directory, you use the libs
object in your build scripts.
For example, to reference a library, you can use libs.<alias>
, and for a plugin, you can use libs.plugins.<alias>
.
Declaring dependencies using a version catalog:
dependencies {
implementation(libs.groovy.core)
implementation(libs.groovy.json)
implementation(libs.groovy.nio)
}
dependencies {
implementation libs.groovy.core
implementation libs.groovy.json
implementation libs.groovy.nio
}
Is the same as:
dependencies {
implementation("org.codehaus.groovy:groovy:3.0.5")
implementation("org.codehaus.groovy:groovy-json:3.0.5")
implementation("org.codehaus.groovy:groovy-nio:3.0.5")
}
dependencies {
implementation 'org.codehaus.groovy:groovy:3.0.5'
implementation 'org.codehaus.groovy:groovy-json:3.0.5'
implementation 'org.codehaus.groovy:groovy-nio:3.0.5'
}
Accessors map directly to the aliases and versions defined in the TOML file, offering type-safe access to dependencies and plugins. This enables IDEs to provide autocompletion, highlight typos, and identify missing dependencies as errors.
Aliases and type-safe accessors
Aliases in a version catalog consist of identifiers separated by a dash (-
), underscore (_
), or dot (.
).
Type-safe accessors are generated for each alias, normalized to dot notation:
Example aliases | Generated accessors |
---|---|
|
|
|
|
|
|
Creating a catalog
Version catalogs are conventionally declared using a libs.versions.toml
file located in the gradle
subdirectory of the root build:
[versions]
groovy = "3.0.5"
checkstyle = "8.37"
[libraries]
groovy-core = { module = "org.codehaus.groovy:groovy", version.ref = "groovy" }
groovy-json = { module = "org.codehaus.groovy:groovy-json", version.ref = "groovy" }
groovy-nio = { module = "org.codehaus.groovy:groovy-nio", version.ref = "groovy" }
commons-lang3 = { group = "org.apache.commons", name = "commons-lang3", version = { strictly = "[3.8, 4.0[", prefer="3.9" } }
[bundles]
groovy = ["groovy-core", "groovy-json", "groovy-nio"]
[plugins]
versions = { id = "com.github.ben-manes.versions", version = "0.45.0" }
The TOML catalog format
The TOML file has four sections:
-
[versions]
– Declares version identifiers. -
[libraries]
– Maps aliases to GAV coordinates. -
[bundles]
– Defines dependency bundles. -
[plugins]
– Declares plugin versions.
The TOML file format is very lenient and lets you write "dotted" properties as shortcuts to full object declarations.
Versions
Versions can be declared either as a single string, in which case they are interpreted as a required version, or as a rich version:
[versions]
other-lib = "5.5.0" # Required version
my-lib = { strictly = "[1.0, 2.0[", prefer = "1.2" } # Rich version
Supported members of a version declaration are:
-
require
: the required version -
strictly
: the strict version -
prefer
: the preferred version -
reject
: the list of rejected versions -
rejectAll
: a boolean to reject all versions
Libraries
Each library is mapped to a GAV coordinate: group, artifact, version. They can be declared as a simple string, in which case they are interpreted coordinates, or separate group and name:
[versions]
common = "1.4"
[libraries]
my-lib = "com.mycompany:mylib:1.4"
my-lib-no-version.module = "com.mycompany:mylib"
my-other-lib = { module = "com.mycompany:other", version = "1.4" }
my-other-lib2 = { group = "com.mycompany", name = "alternate", version = "1.4" }
mylib-full-format = { group = "com.mycompany", name = "alternate", version = { require = "1.4" } }
[plugins]
short-notation = "some.plugin.id:1.4"
long-notation = { id = "some.plugin.id", version = "1.4" }
reference-notation = { id = "some.plugin.id", version.ref = "common" }
You can also define strict or preferred versions using strictly
or prefer
:
[libraries]
commons-lang3 = { group = "org.apache.commons", name = "commons-lang3", version = { strictly = "[3.8, 4.0[", prefer = "3.9" } }
In case you want to reference a version declared in the [versions]
section, use the version.ref
property:
[versions]
some = "1.4"
[libraries]
my-lib = { group = "com.mycompany", name="mylib", version.ref="some" }
Bundles
Bundles group multiple library aliases, so they can be referenced together in the build script.
[versions]
groovy = "3.0.9"
[libraries]
groovy-core = { group = "org.codehaus.groovy", name = "groovy", version.ref = "groovy" }
groovy-json = { group = "org.codehaus.groovy", name = "groovy-json", version.ref = "groovy" }
groovy-nio = { group = "org.codehaus.groovy", name = "groovy-nio", version.ref = "groovy" }
[bundles]
groovy = ["groovy-core", "groovy-json", "groovy-nio"]
This is useful for pulling in several related dependencies with a single alias:
dependencies {
implementation(libs.bundles.groovy)
}
dependencies {
implementation libs.bundles.groovy
}
Plugins
This section defines the plugins and their versions by mapping plugin IDs to version numbers.
Just like libraries, you can define plugin versions using aliases from the [versions]
section or directly specify the version.
[plugins]
versions = { id = "com.github.ben-manes.versions", version = "0.45.0" }
Which can be accessed in any project of the build using the plugins {}
block.
To refer to a plugin from the catalog, use the alias()
function:
plugins {
`java-library`
checkstyle
alias(libs.plugins.versions)
}
plugins {
id 'java-library'
id 'checkstyle'
// Use the plugin `versions` as declared in the `libs` version catalog
alias(libs.plugins.versions)
}
You cannot use a plugin declared in a version catalog in your settings file or settings plugin. |
Avoiding subgroup accessors
To avoid generating subgroup accessors, use camelCase notation:
Aliases | Accessors |
---|---|
|
|
|
|
Reserved keywords
Certain keywords, like extensions
, class
, and convention
, are reserved and cannot be used as aliases.
Additionally, bundles
, versions
, and plugins
cannot be the first subgroup in a dependency alias.
For example, the alias versions-dependency
is not valid, but versionsDependency
or dependency-versions
are valid.
Publishing a catalog
In most cases, the gradle/libs.versions.toml
will be checked into a repository and available for consumption.
However, this doesn’t always solve the problem of sharing a catalog in an organization or for external consumers. Another option to share a catalog is to write a settings plugin, publish it on the Gradle plugin portal or an internal repository, and let the consumers apply the plugin on their settings file.
Alternatively, Gradle offers a version catalog plugin, which has the ability to declare and publish a catalog.
To do this, you need to apply the version-catalog
plugin:
plugins {
`version-catalog`
`maven-publish`
}
plugins {
id 'version-catalog'
id 'maven-publish'
}
This plugin will then expose the catalog extension that you can use to declare a catalog:
catalog {
// declare the aliases, bundles and versions in this block
versionCatalog {
library("my-lib", "com.mycompany:mylib:1.2")
}
}
catalog {
// declare the aliases, bundles and versions in this block
versionCatalog {
library('my-lib', 'com.mycompany:mylib:1.2')
}
}
The plugin must be created programmatically, see Programming catalogs for details.
Such a catalog can then be published by applying either the maven-publish
or ivy-publish
plugin and configuring the publication to use the versionCatalog
component:
publishing {
publications {
create<MavenPublication>("maven") {
from(components["versionCatalog"])
}
}
}
publishing {
publications {
maven(MavenPublication) {
from components.versionCatalog
}
}
}
When publishing such a project, a libs.versions.toml
file will automatically be generated (and uploaded), which can then be consumed from other Gradle builds.
Importing a published catalog
A catalog produced by the Version Catalog Plugin can be imported via the Settings API:
dependencyResolutionManagement {
versionCatalogs {
create("libs") {
from("com.mycompany:catalog:1.0")
}
}
}
dependencyResolutionManagement {
versionCatalogs {
libs {
from("com.mycompany:catalog:1.0")
}
}
}
Importing a catalog from a file
Gradle automatically imports a catalog in the gradle directory named libs.versions.toml .
|
The version catalog builder API allows importing a catalog from an external file, enabling reuse across different parts of a build, such as sharing the main build’s catalog with buildSrc
.
For example, you can include a catalog in the buildSrc/settings.gradle(.kts)
file as follows:
dependencyResolutionManagement {
versionCatalogs {
create("libs") {
from(files("../gradle/libs.versions.toml"))
}
}
}
dependencyResolutionManagement {
versionCatalogs {
libs {
from(files("../gradle/libs.versions.toml"))
}
}
}
The VersionCatalogBuilder.from(Object dependencyNotation) method accepts only a single file, meaning that notations like Project.files(java.lang.Object…) must refer to one file. Otherwise, the build will fail.
Remember that you don’t need to import the version catalog named libs.versions.toml if it resides in your gradle folder. It will be imported automatically.
|
However, if you need to import version catalogs from multiple files, it’s recommended to use a code-based approach instead of relying on TOML files. This approach allows for the declaration of multiple catalogs from different files:
dependencyResolutionManagement {
versionCatalogs {
// declares an additional catalog, named 'testLibs', from the 'test-libs.versions.toml' file
create("testLibs") {
from(files("gradle/test-libs.versions.toml"))
}
}
}
dependencyResolutionManagement {
versionCatalogs {
// declares an additional catalog, named 'testLibs', from the 'test-libs.versions.toml' file
testLibs {
from(files('gradle/test-libs.versions.toml'))
}
}
}
Importing multiple catalogs
You can declare multiple catalogs to organize dependencies better by using the Settings API:
dependencyResolutionManagement {
versionCatalogs {
create("libs") {
from(files("gradle/libs.versions.toml"))
}
create("tools") {
from(files("gradle/tools.versions.toml"))
}
}
}
dependencies {
implementation(libs.someDependency)
implementation(tools.someTool)
}
To minimize the risk of naming conflicts, each catalog generates an extension applied to all projects, so it’s advisable to choose a unique name. One effective approach is to select a name that ends with |
Changing the catalog name
By default, the libs.versions.toml
file is used as input for the libs
catalog.
However, you can rename the default catalog if an extension with the same name already exists:
dependencyResolutionManagement {
defaultLibrariesExtensionName = "projectLibs"
}
dependencyResolutionManagement {
defaultLibrariesExtensionName = 'projectLibs'
}
Overwriting catalog versions
You can overwrite versions when importing a catalog:
dependencyResolutionManagement {
versionCatalogs {
create("amendedLibs") {
from("com.mycompany:catalog:1.0")
// overwrite the "groovy" version declared in the imported catalog
version("groovy", "3.0.6")
}
}
}
dependencyResolutionManagement {
versionCatalogs {
amendedLibs {
from("com.mycompany:catalog:1.0")
// overwrite the "groovy" version declared in the imported catalog
version("groovy", "3.0.6")
}
}
}
In the examples above, any dependency referencing the groovy
version will automatically be updated to use 3.0.6
.
Overwriting a version only affects what is imported and used when declaring dependencies. The actual resolved dependency version may differ due to conflict resolution.gi |
Programming catalogs
Version catalogs can be declared programmatically in the settings.gradle(.kts)
file.
dependencyResolutionManagement {
versionCatalogs {
create("libs") {
version("groovy", "3.0.5")
version("checkstyle", "8.37")
library("groovy-core", "org.codehaus.groovy", "groovy").versionRef("groovy")
library("groovy-json", "org.codehaus.groovy", "groovy-json").versionRef("groovy")
library("groovy-nio", "org.codehaus.groovy", "groovy-nio").versionRef("groovy")
library("commons-lang3", "org.apache.commons", "commons-lang3").version {
strictly("[3.8, 4.0[")
prefer("3.9")
}
}
}
}
dependencyResolutionManagement {
versionCatalogs {
libs {
version('groovy', '3.0.5')
version('checkstyle', '8.37')
library('groovy-core', 'org.codehaus.groovy', 'groovy').versionRef('groovy')
library('groovy-json', 'org.codehaus.groovy', 'groovy-json').versionRef('groovy')
library('groovy-nio', 'org.codehaus.groovy', 'groovy-nio').versionRef('groovy')
library('commons-lang3', 'org.apache.commons', 'commons-lang3').version {
strictly '[3.8, 4.0['
prefer '3.9'
}
}
}
}
Don’t use libs for your programmatic version catalog name if you have the default libs.versions.toml in your project.
|
Creating a version catalog programmatically uses the Settings API:
dependencyResolutionManagement {
versionCatalogs {
create("libs") {
version("groovy", "3.0.5")
version("checkstyle", "8.37")
library("groovy-core", "org.codehaus.groovy", "groovy").versionRef("groovy")
library("groovy-json", "org.codehaus.groovy", "groovy-json").versionRef("groovy")
library("groovy-nio", "org.codehaus.groovy", "groovy-nio").versionRef("groovy")
library("commons-lang3", "org.apache.commons", "commons-lang3").version {
strictly("[3.8, 4.0[")
prefer("3.9")
}
bundle("groovy", listOf("groovy-core", "groovy-json", "groovy-nio"))
}
}
}
dependencyResolutionManagement {
versionCatalogs {
libs {
version('groovy', '3.0.5')
version('checkstyle', '8.37')
library('groovy-core', 'org.codehaus.groovy', 'groovy').versionRef('groovy')
library('groovy-json', 'org.codehaus.groovy', 'groovy-json').versionRef('groovy')
library('groovy-nio', 'org.codehaus.groovy', 'groovy-nio').versionRef('groovy')
library('commons-lang3', 'org.apache.commons', 'commons-lang3').version {
strictly '[3.8, 4.0['
prefer '3.9'
}
bundle('groovy', ['groovy-core', 'groovy-json', 'groovy-nio'])
}
}
}