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.
Page Contents
The four sections
| Section | What it holds | Example key |
|---|---|---|
| [versions] | Version numbers you reuse | kotlin = “2.1.0” |
| [libraries] | Library coordinates with a version reference | androidx-core-ktx |
| [bundles] | Groups of libraries added together | compose |
| [plugins] | Gradle plugins with versions | android-application |
How you use it in build files
- A library entry named
androidx-core-ktxbecomeslibs.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.
Need help building or publishing your app? Talk to Techpass Master – we design, build and publish Android apps for clients worldwide.
