[Gradle version catalogs](https://docs.gradle.org/current/userguide/platforms.html)
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](https://developer.android.com/topic/modularization). 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](https://developer.android.com/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](https://docs.gradle.org/current/userguide/platforms.html#sub:conventional-dependencies-toml),
so we recommend using this default name.
| **Note:** It's possible to change the catalog file name; however, this requires changing your build files, so we don't recommend doing it.

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:  

### Kotlin

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

}
```

### Groovy

```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](https://www.jetbrains.com/help/idea/auto-completing-code.html)
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

```kotlin
dependencies {
   implementation(libs.androidx.ktx)

}
```

### Groovy

```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

```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

```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](https://www.jetbrains.com/help/idea/auto-completing-code.html)
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](https://docs.gradle.org/current/samples/sample_convention_plugins.html#organizing_build_logic).  

### Kotlin

```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

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

}

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

}
```
| **Note:** If you are using a version of Gradle below 8.1, you need to annotate the `plugins{}` block with `@Suppress("DSL_SCOPE_VIOLATION")` when using version catalogs. Refer to [issue #22797](https://github.com/gradle/gradle/issues/22797) for more info.

## Learn more

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

- [The version catalog TOML file format](https://docs.gradle.org/current/userguide/platforms.html#sub::toml-dependencies-format) documents additional options for configuring your catalog file.
- [Now in Android](https://github.com/android/nowinandroid) is our sample app that uses version catalogs.