Skip to content

Lesson 16 ยท 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