skip to content

How does the dependencyResolutionManagement {} block declare version catalogs, and where does libs.versions.toml fit structurally?

level: middleimportance: should knowfreq 46%

answer

  1. versionCatalogs {} nested in the block
  2. gradle/libs.versions.toml auto-creates 'libs'
  3. create("name") { from(files(...)) }
  4. settings-only, before project config
  5. TOML = data, block = declaration

basics

~10 s

Inside dependencyResolutionManagement {} you add a versionCatalogs {} block. A catalog named 'libs' is auto-created from gradle/libs.versions.toml, or you create one explicitly and point it at a TOML file with from(files(...)).

solid answer

~40 s

Version catalogs are *declared structurally* inside `dependencyResolutionManagement {}` via a nested `versionCatalogs {}` block. Gradle has a convention: if a file `gradle/libs.versions.toml` exists, a catalog named `libs` is created automatically and you do not need any DSL at all. To customize — a different file, a second catalog, or extra entries — you call `create("name") { from(files("path/to/file.toml")) }`. The settings block is the only place catalogs can be declared, because catalogs must exist before any project build script tries to reference accessors like `libs.someLibrary`. So structurally: the TOML file is the *data*; the `versionCatalogs {}` block in settings is the *declaration* that turns that data into type-safe accessors available to every project. The internal TOML schema and accessor-generation details belong to the version-catalog-declaration topic; here the point is *where* the declaration sits.

code

kotlin · 11 lines
kotlin
// settings.gradle.kts
dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}

// If gradle/libs.versions.toml already exists, the 'libs'
// catalog is created automatically and this block is optional.

go deeper

for a junior

Know that version catalogs are declared in settings and the default 'libs' comes from gradle/libs.versions.toml.

for a middle

Explain the versionCatalogs {} block, the create(...).from(files(...)) form, and the auto-creation convention.

for a senior

Explain why declaration must precede project config and when multiple catalogs are justified.

for a principal

Discuss catalog strategy across a large org (shared catalog distribution, single source of truth for versions).

## Two layers: the file and the declaration A version catalog has two parts: 1. **The data** — a TOML file (conventionally `gradle/libs.versions.toml`) listing versions, libraries, bundles, and plugins. 2. **The declaration** — a `versionCatalogs {}` block *inside* `dependencyResolutionManagement {}` in the settings script that registers that data as a named catalog. The settings block is the *only* legal home for the declaration, because catalogs must be created during settings evaluation — before any project build script references the generated accessors. ## The convention shortcut Gradle auto-creates a catalog named `libs` if `gradle/libs.versions.toml` exists. With that file present, you can use `libs.xxx` accessors in build scripts *without writing any versionCatalogs DSL*. This is the most common setup. ## Explicit declaration When you need a non-default file name, a second catalog, or programmatic entries, declare explicitly: ```kotlin // settings.gradle.kts dependencyResolutionManagement { versionCatalogs { // customize the default 'libs' catalog source create("libs") { from(files("gradle/libs.versions.toml")) } // a second catalog from another file create("testLibs") { from(files("gradle/test-libs.versions.toml")) } } } ``` Each `create(name)` produces an accessor object (`libs`, `testLibs`) usable in any module's `dependencies {}` block. ## Why it must be in settings Projects are configured *after* settings. The type-safe accessors (`libs.foo`) that build scripts use have to be generated up front from the catalog declaration. There is no project-level hook to declare a catalog, which is exactly why the declaration lives in this settings block. ## Scope boundary The *internals* — TOML sections (`[versions]`, `[libraries]`, `[bundles]`, `[plugins]`), alias-to-accessor mapping, version refs — are the version-catalog-declaration topic. Structurally, all you need here is: the catalog declaration is a child block of `dependencyResolutionManagement {}`, and the default `libs` catalog comes for free from `gradle/libs.versions.toml`.

  • Can you declare a version catalog in a project's build.gradle.kts?
    No. Catalogs must be declared in the settings script (inside dependencyResolutionManagement) so the accessors exist before projects are configured. There is no project-level catalog-declaration DSL.
  • If gradle/libs.versions.toml exists, do you still need the versionCatalogs {} block?
    No — Gradle auto-creates the 'libs' catalog from that conventional path. You only add the block to use a different file, add more catalogs, or add programmatic entries.

saying these in an interview costs you the question

  • Claiming catalogs are declared in build.gradle.kts.
  • Saying you must always write a versionCatalogs block (the convention auto-creates libs).
  • Confusing the TOML file (data) with the declaration block (registration).

context

resolving links…