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:

build.gradle.kts
dependencies {
    implementation(libs.groovy.core)
}
build.gradle
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.versions.toml file in the gradle directory:

gradle/libs.versions.toml
[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:

build.gradle.kts
dependencies {
    implementation(libs.groovy.core)
    implementation(libs.groovy.json)
    implementation(libs.groovy.nio)
}
build.gradle
dependencies {
    implementation libs.groovy.core
    implementation libs.groovy.json
    implementation libs.groovy.nio
}

Is the same as:

build.gradle.kts
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")
}
build.gradle
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

guava

libs.guava

groovy-core

libs.groovy.core

androidx.awesome.lib

libs.androidx.awesome.lib

Creating a catalog

Version catalogs are conventionally declared using a libs.versions.toml file located in the gradle subdirectory of the root build:

gradle/libs.versions.toml
[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:

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:

build.gradle.kts
dependencies {
    implementation(libs.bundles.groovy)
}
build.gradle
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:

build.gradle.kts
plugins {
    `java-library`
    checkstyle
    alias(libs.plugins.versions)
}
build.gradle
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

groovyCore

libs.groovyCore

groovyJson-core

libs.groovyJsonCore

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:

build.gradle.kts
plugins {
    `version-catalog`
    `maven-publish`
}
build.gradle
plugins {
    id 'version-catalog'
    id 'maven-publish'
}

This plugin will then expose the catalog extension that you can use to declare a catalog:

build.gradle.kts
catalog {
    // declare the aliases, bundles and versions in this block
    versionCatalog {
        library("my-lib", "com.mycompany:mylib:1.2")
    }
}
build.gradle
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:

build.gradle.kts
publishing {
    publications {
        create<MavenPublication>("maven") {
            from(components["versionCatalog"])
        }
    }
}
build.gradle
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:

settings.gradle.kts
dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from("com.mycompany:catalog:1.0")
        }
    }
}
settings.gradle
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:

settings.gradle.kts
dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("../gradle/libs.versions.toml"))
        }
    }
}
settings.gradle
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:

settings.gradle.kts
dependencyResolutionManagement {
    versionCatalogs {
        // declares an additional catalog, named 'testLibs', from the 'test-libs.versions.toml' file
        create("testLibs") {
            from(files("gradle/test-libs.versions.toml"))
        }
    }
}
settings.gradle
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:

settings.gradle.kts
dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
        create("tools") {
            from(files("gradle/tools.versions.toml"))
        }
    }
}
build.gradle.kts
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 Libs.

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:

settings.gradle.kts
dependencyResolutionManagement {
    defaultLibrariesExtensionName = "projectLibs"
}
settings.gradle
dependencyResolutionManagement {
    defaultLibrariesExtensionName = 'projectLibs'
}

Overwriting catalog versions

You can overwrite versions when importing a catalog:

settings.gradle.kts
dependencyResolutionManagement {
    versionCatalogs {
        create("amendedLibs") {
            from("com.mycompany:catalog:1.0")
            // overwrite the "groovy" version declared in the imported catalog
            version("groovy", "3.0.6")
        }
    }
}
settings.gradle
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.

settings.gradle.kts
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")
            }
        }
    }
}
settings.gradle
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:

settings.gradle.kts
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"))
        }
    }
}
settings.gradle
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'])
        }
    }
}