Using Gradle Version Catalog for Unified Dependency Management

As projects grow, managing hundreds of dependencies becomes essential, and Gradle offers several solutions such as loop‑optimized dependency management, buildSrc, and includeBuild. Gradle 7.0 introduces the Version Catalog feature, which provides a centralized way to declare and share dependency versions.

The catalog supports visibility for all modules, declaration of bundles (grouped dependencies), separation of version numbers from dependency names, and configuration via a separate libs.versions.toml file, making it possible to share versions across projects.

Using Version Catalog

To enable the feature, add enableFeaturePreview('VERSION_CATALOGS') to settings.gradle . Dependencies can then be referenced through the generated libs accessor, e.g.:

dependencies {
    implementation(libs.retrofit)
    implementation(libs.groovy.core)
}

Gradle generates type‑safe accessors for each catalog, allowing IDE auto‑completion.

Catalog entries are visible to all modules, enabling unified version updates.

Bundles allow grouping of frequently used dependencies.

Version references can be shared across multiple dependencies.

All declarations can reside in a separate libs.versions.toml file.

The catalog can be shared between projects.

Declaring Version Catalog

In settings.gradle you can declare the catalog:

dependencyResolutionManagement {
    versionCatalogs {
        libs {
            alias('retrofit').to('com.squareup.retrofit2:retrofit:2.9.0')
            alias('groovy-core').to('org.codehaus.groovy:groovy').versionRef('groovy')
            // ... other aliases ...
        }
    }
}

Aliases must consist of ASCII identifiers separated by dashes, underscores, or dots.

Bundles

Bundles group dependencies under a single alias:

dependencyResolutionManagement {
    versionCatalogs {
        libs {
            bundle('groovy', ['groovy-core', 'groovy-json', 'groovy-nio'])
        }
    }
}

Then use implementation libs.bundles.groovy to add all bundled dependencies.

Plugin Versions

Plugins can also be declared in the catalog:

dependencyResolutionManagement {
    versionCatalogs {
        libs {
            alias('jmh').toPluginId('me.champeau.jmh').version('0.6.5')
        }
    }
}

And applied with plugins { alias(libs.plugins.jmh) } .

Separate Catalog Files

A libs.versions.toml file can define [versions] , [libraries] , [bundles] , and [plugins] sections, which Gradle will automatically import.

Sharing Catalogs Between Projects

Catalogs can be shared via file imports or by publishing a Maven artifact containing the catalog. Example of publishing:

publishing {
    publications {
        maven(MavenPublication) {
            groupId = 'com.zj.catalog'
            artifactId = 'catalog'
            version = '1.0.0'
            from components.versionCatalog
        }
    }
}

Consumers can then import the catalog from Maven Local or a remote repository and optionally override versions.

Summary

Gradle's Version Catalog provides a unified, type‑safe way to manage dependency versions, declare bundles, separate version numbers from dependency names, configure them in a dedicated TOML file, and share them across multiple projects, greatly simplifying large‑scale dependency management.