Gradle Version Catalog

“A version catalog is a list of dependencies, represented as dependency coordinates, that a user can pick from when declaring dependencies in a build script.”

This image was created using an AI image creation program.

💡 Update: Since Android Studio Hedgehog, Gradle Version Catalog has become a default for new projects. If we want a sample Version Catalog template, create a new project, and we will have it instantly. Later, Android Studio versions even highlight the dependencies on the build.gradle(.kts), so we can right-click on that and migrate to the version catalog.

We can use the version catalog to keep all our dependency declarations and version numbers in a single place. This allows us to easily share a list of dependency and version configurations between modules and projects.

With IDE plugin support, importing dependencies to our projects is easier as it provides an auto-complete function based on what we have defined in a version catalog.

The best way to do this is to create a TOML (Tom’s Obvious Minimal Language) file for its portability. Please note that this TOML file is not a single source of truth, as we can always hardcode some other dependencies and versions at different places of our script, and the IDE will not bother enforcing to have everything kept inside the version catalog.

It only takes a few steps to create a version catalog. Most of the effort will be on preparing the TOML file, which depends on our project dependencies.

Enabling the Version Catalog

Version Catalog is stable in Gradle version 7.4, this step is not required when using version 7.4+.

Upgrading Gradle

Run ./gradlew wrapper --gradle-version=7.6 to update the project to 7.6.

Using enableFeaturePreview on older Gradle Versions

Please note that enableFeaturePreview is no longer needed on Gradle 8.0+.

Make this change at settings.gradle or settings.gradle.kts:

Kotlin DSL

enableFeaturePreview("VERSION_CATALOGS")
include(":app")

Groovy

enableFeaturePreview("VERSION_CATALOGS")
include ':app'

Fetch the version catalog

Again, add this to the same settings.gradle or settings.gradle.kts. Same syntax for both languages.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

Declaring dependencies in a libs.versions.toml file

• Create gradle/libs.versions.toml
• It is worth checking that your .gitignore is not ignoring the /gradle/ directory, so that your repository will keep libs.versions.toml
• Android Studio should have the Toml plugin bundled; For IntelliJ Idea you may double check to make sure you have it for extended IDE support.

My sample libs.versions.toml

A very early version to be further refined. Note that we have four sections there:

• versions
• libraries
• plugins
• bundles

Also note that if the names include - , when we refer them in our Gradle build scripts, we have to change them to . there. For example, if we definehilt-android , it will become libs.hilt.android when we call it.

Update the dependencies block:

// change from
    implementation 'com.google.dagger:hilt-android:2.43.2'
    kapt 'com.google.dagger:hilt-compiler:2.43.2'

// change to
    implementation libs.hilt.android
    kapt libs.hilt.complier

Extended usages

We can also move the minSdk and targetSdk to version catalog.

Groovy

defaultConfig {
         applicationId "uk.ryanwong.skycatnews"
-        minSdk 26
-        targetSdk 33
+        minSdk libs.versions.minSdk.get().toInteger()
+        targetSdk libs.versions.targetSdk.get().toInteger()

References:

• Sharing dependency versions between projects — Official Gradle documentation
• Gradle version catalogs for an awesome dependency management — more useful reference
• Version Catalogs in Gradle 7.0
• Integrating a Version Catalog