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 (thelibraries
andplugins
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:
- Add the new entry to the catalog.
- Sync your Android project.
- 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:
Kotlin
dependencies { implementation("androidx.core:core-ktx:1.9.0") }
Groovy
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.
Kotlin
dependencies { implementation(libs.androidx.ktx) }
Groovy
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:
Kotlin
// 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") }
Groovy
// 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.
Kotlin
// Top-level build.gradle.kts plugins { alias(libs.plugins.android.application) apply false } // module build.gradle.kts plugins { alias(libs.plugins.android.application) }
Groovy
// 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.