Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 36 ยท Dependencies and Repositories

Repositories and Version Catalogs (libs.versions.toml)

Configure Maven Central, Google and private repositories, centralize repositories in settings, and manage versions with a libs.versions.toml version catalog.

Declaring implementation("com.google.guava:guava:33.4.0-jre") is only half of the story: Gradle also has to know where to download it from. That is the job of repositories. Once a build grows, a second problem appears: the same library version repeated in ten build files. A version catalog solves that with one central list. This lesson covers both: repository declarations and credentials, centralizing them in settings, and writing and using gradle/libs.versions.toml.

Gradle files are read-only; runnable stand-ins parse a catalog and model repository search order.

Repositories

Kotlin
repositories {
    mavenCentral()                 // the default home of most JVM libraries
    google()                       // Android libraries
    gradlePluginPortal()           // Gradle plugins
    mavenLocal()                   // ~/.m2, use sparingly
    maven {
        name = "company"
        url = uri("https://repo.example.com/releases")
        credentials {
            username = providers.gradleProperty("repoUser").orNull
            password = providers.gradleProperty("repoPassword").orNull
        }
    }
}

Facts to remember:

  • Gradle searches repositories in the order declared and takes the first that has the module. Put the most specific or private one where it makes sense; put mavenLocal() last, or not at all, because it makes builds depend on your machine.
  • Credentials come from properties or environment variables, never literals (see properties).
  • ivy { } repositories and flatDir exist for special cases.
  • Limit what a repository may serve with a content filter:
Kotlin
maven {
    url = uri("https://repo.example.com/releases")
    content {
        includeGroupAndSubgroups("com.example")
    }
}

This speeds up resolution and prevents "dependency confusion", where a public repository answers for a name that should come only from your private one.

Centralizing repositories in settings

In multi-project builds, repeating repositories { } in each project is error-prone. Declare them once in settings.gradle.kts:

Kotlin
dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS
    repositories {
        mavenCentral()
    }
}

With FAIL_ON_PROJECT_REPOS, a project that declares its own repositories fails the build, keeping every project consistent. Plugins have their own list in pluginManagement { repositories { ... } }.

Stand-in: repository search order

This Java program is not Gradle. It resolves a module by asking repositories in order and stopping at the first hit, with an optional group filter.

Java Stand-in: first repository that has the module wins

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

com.example:internal-utils exists in both repositories. With Central first, the public copy wins, which is exactly the dependency-confusion risk; with a content filter on the company repository and its position first, only the private one can answer.

Version catalogs

A version catalog is a TOML file, gradle/libs.versions.toml, that Gradle reads automatically (it is a standard name since Gradle 7). It has up to four sections:

TOML
[versions]
guava = "33.4.0-jre"
junit = "5.11.4"
spring-boot = "3.4.1"

[libraries]
guava = { module = "com.google.guava:guava", version.ref = "guava" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
slf4j-api = "org.slf4j:slf4j-api:2.0.16"

[bundles]
testing = ["junit-jupiter"]

[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }

Use the entries in any build script as type-safe accessors. Dashes and dots become nested names: junit-jupiter becomes libs.junit.jupiter.

Kotlin
plugins {
    alias(libs.plugins.spring.boot)
}

dependencies {
    implementation(libs.guava)
    testImplementation(libs.junit.jupiter)
    testImplementation(libs.bundles.testing)
}

Benefits:

  • One place to update a version, for the whole multi-project build.
  • Autocompletion in the IDE and compile-time checks for typos.
  • bundles group libraries that always go together.
  • Tools such as Renovate and Dependabot understand the file.

You can also declare a catalog directly in settings.gradle.kts, or share one from a published artifact:

Kotlin
dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from("com.example:shared-catalog:1.0.0")
        }
    }
}

Stand-in: parse a catalog and resolve accessors

This Java program reads a small TOML-like text, resolves version.ref entries, and prints the coordinates behind each accessor. It handles only the subset used here.

Java Stand-in: reading libs.versions.toml

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Updating the junit version in one line changes every build file that uses libs.junit.jupiter.

Tips

  • Name aliases by purpose, not by version: guava, not guava33.
  • Keep plugin versions in the [plugins] section and apply them with alias(...).
  • A catalog holds versions only; scopes (implementation, testImplementation) are still chosen where you use the alias.
  • For libraries that publish a BOM, combine the catalog with a platform (see constraints and platforms).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In which order does Gradle search the declared repositories?

    Order matters: the first repository that can provide the module wins.
  2. 2. What is the default location of a version catalog?

    Gradle automatically reads gradle/libs.versions.toml and exposes a catalog named libs.
  3. 3. How is the alias junit-jupiter used in a Kotlin build script?

    Dashes in aliases become dots in the generated type-safe accessors.
  4. 4. What does RepositoriesMode.FAIL_ON_PROJECT_REPOS do?

    It enforces central repository declarations in settings.gradle(.kts).

Summary

  • Repositories tell Gradle where to download modules; they are searched in the declared order.
  • Use mavenCentral(), google() and private maven { } repositories with credentials from properties.
  • Centralize repositories in dependencyResolutionManagement and add content filters to avoid dependency confusion.
  • A version catalog (gradle/libs.versions.toml) has versions, libraries, bundles and plugins, and gives type-safe accessors.
  • Update a version in one place and use alias(libs.plugins...) for plugins.

Next: Dependency Resolution and Version Conflicts