Migrate your build to version catalogs

Gradle version catalogs enable you to add and maintain dependencies and plugins in a scalable way. Using Gradle version catalogs makes managing dependencies and plugins easier when you have multiple modules. Instead of hardcoding dependency names and versions in individual build files and updating each entry whenever you need to upgrade a dependency, you can create a central version catalog of dependencies that various modules can reference in a type-safe way with Android Studio assistance.

This page provides basic information about migrating your Android app to version catalogs. To learn more, see Add build dependencies and the Gradle documentation.

Create a version catalog file

Start by creating a version catalog file. In your root project's gradle folder, create a file called libs.versions.toml. Gradle looks for the catalog in the libs.versions.toml file by default, so we recommend using this default name.

In your libs.versions.toml file, add these sections:

[versions]

[libraries]

[plugins]

The sections are used as follows:

• In the versions block, define variables that hold the versions of your dependencies and plugins. You use these variables in the subsequent blocks (the libraries and plugins blocks).
• In the libraries block, define your dependencies.
• In the plugins block, define your plugins.

Migration steps

We recommend you do the steps in the order listed. A build can consume dependencies and plugins from build scripts and catalogs simultaneously, so take your time to migrate your dependencies and plugins individually.

The migration process is:

1. Add the new entry to the catalog.
2. Sync your Android project.
3. Replace the previous string declaration with the catalog type-safe accessor.

Migrate dependencies

Add an entry for each dependency in both the versions and libraries sections of the libs.versions.toml file. Sync your project, and then replace their declarations in the build files with their catalog names.

This code snippet shows the build.gradle.kts file before removing the dependency:

dependencies {
    implementation("androidx.core:core-ktx:1.9.0")

}

dependencies {
    implementation 'androidx.core:core-ktx:1.9.0'

}

This code snippet shows how to define the dependency in the version catalog file:

[versions]
ktx = "1.9.0"

[libraries]
androidx-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "ktx" }

The recommended naming for dependencies block in catalogs is kebab case (such as androidx-ktx) for better code completion assistance in your build files.

In the build.gradle.kts file of each module that requires the dependency, define the dependencies by the names you defined in the TOML file.

dependencies {
   implementation(libs.androidx.ktx)

}

dependencies {
   implementation libs.androidx.ktx

}

Migrate plugins

Add an entry for each plugin in both the versions and the plugins sections of the libs.versions.toml file. Sync your project, and then replace their declarations in the plugins{} block in the build files with their catalog names.

This code snippet shows the build.gradle.kts file before removing the plugin:

// Top-level `build.gradle.kts` file
plugins {
   id("com.android.application") version "7.4.1" apply false

}

// Module-level `build.gradle.kts` file
plugins {
   id("com.android.application")

}

// Top-level `build.gradle` file
plugins {
   id 'com.android.application' version '7.4.1' apply false

}

// Module-level `build.gradle` file
plugins {
   id 'com.android.application'

}

This code snippet shows how to define the plugin in the version catalog file:

[versions]
androidGradlePlugin = "7.4.1"

[plugins]
android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }

As with dependencies, the recommended formatting for plugins block catalog entries is kebab case (such as android-application) for better code completion assistance in your build files.

The following code shows how to define the com.android.application plugin in the top and module level build.gradle.kts files. Use alias for plugins that come from the version catalog file and id for plugins that don't come from the version catalog file, such as convention plugins.

// Top-level build.gradle.kts
plugins {
   alias(libs.plugins.android.application) apply false

}

// module build.gradle.kts
plugins {
   alias(libs.plugins.android.application)

}

// Top-level build.gradle
plugins {
   alias libs.plugins.android.application apply false

}

// module build.gradle
plugins {
   alias libs.plugins.android.application

}

Learn more

To learn about additional options for configuring your version catalog, see these resources:

• The version catalog TOML file format documents additional options for configuring your catalog file.
• Now in Android is our sample app that uses version catalogs.

Known issues

Gradle version catalogs is still under active development. For more info about what isn't yet supported, see the known issues and limitations.