Gradle Version Catalog (libs.versions.toml): A Beginner’s Guide

If your Android project has several modules, you have probably seen the same library version written in many places – and one module quietly using an older version. A Gradle version catalog solves this: every dependency and version lives in one file, gradle/libs.versions.toml, and every module refers to it. New Android Studio projects already use one. Here is how it works and how to migrate an older project.

Free tool
Generate libs.versions.toml
Paste your dependencies from build.gradle or build.gradle.kts and get a version catalog plus the updated dependency lines. Free – nothing uploaded.
Open Gradle Version Catalog →

The four sections

SectionWhat it holdsExample key
[versions]Version numbers you reusekotlin = “2.1.0”
[libraries]Library coordinates with a version referenceandroidx-core-ktx
[bundles]Groups of libraries added togethercompose
[plugins]Gradle plugins with versionsandroid-application

How you use it in build files

  • A library entry named androidx-core-ktx becomes libs.androidx.core.ktx – dashes turn into dots.
  • Add it with implementation(libs.androidx.core.ktx).
  • Add a bundle with implementation(libs.bundles.compose).
  • Apply a plugin with alias(libs.plugins.android.application).

Android Studio offers code completion for catalog entries and highlights available updates in the TOML file.

Naming tips

  • Use lowercase words separated by dashes: retrofit-converter-gson.
  • Start with the group or product: androidx-room-runtime, androidx-room-compiler.
  • Use the same version reference for libraries released together, for example all Room artifacts share room.
  • For Compose, use the BOM as a library and leave the version out of individual Compose libraries.

How to migrate an existing project

  • Make sure you use a recent Gradle and Android Gradle Plugin (version catalogs are stable since Gradle 7.4).
  • Create gradle/libs.versions.toml.
  • Copy your dependency lines into our Gradle Version Catalog generator to create the TOML and the new libs. lines.
  • Replace the dependencies in each module’s build file.
  • Move plugin versions from the root build file to [plugins].
  • Sync, build and run your tests.

Migrate one module at a time in large projects, and commit after each step.

Benefits

  • One source of truth – update a version once for all modules.
  • Type-safe accessors – typos are caught at build time.
  • Cleaner build files – no long coordinates.
  • Easier updates – tools such as Dependabot and Renovate understand version catalogs.

Related

Your app’s own version (versionCode and versionName) is separate from library versions – see our app versioning guide.

FAQ

Where is the version catalog file?

By default at gradle/libs.versions.toml in your project root.

Does it work with Groovy build files?

Yes. Version catalogs work with both Groovy and Kotlin DSL.

Why does my library name have dots instead of dashes?

Gradle converts dashes, underscores and dots in keys into dot-separated accessors.

Can I have more than one catalog?

Yes. You can define additional catalogs in settings.gradle.

Is my build file uploaded?

No. The generator runs entirely in your browser.

Free tool
Try the free Gradle Version Catalog
No signup and nothing uploaded – it runs right in your browser. Browse all 74 free tools on our Free Tools page.
Open Gradle Version Catalog →

Need help building or publishing your app? Talk to Techpass Master – we design, build and publish Android apps for clients worldwide.

WhatsApp us📞 Call now