// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[version-catalog]]
= Version Catalogs
:keywords: toml, libs.versions.toml

A version catalog is a selected list of dependencies that can be referenced in build scripts, simplifying dependency management.

++++
<p>
  <div style="position:relative;padding-top:56.25%;">
    <iframe src="https://www.youtube-nocookie.com/embed/dZmlSsRdctE?si=2u96T8ieHzOu4_48&rel=0" frameborder="0" allowfullscreen
      style="position:absolute;top:0;left:0;width:100%;height:100%;"></iframe>
  </div>
</p>
++++

Instead of specifying dependencies directly using string notation, you can pick them from a version catalog:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/kotlin",files="build.gradle.kts[tags=simple_dependency_use]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/groovy",files="build.gradle[tags=simple_dependency_use]"]
====

In this example, `libs` represents the catalog, and `groovy` is a dependency available in it.

Where the version catalog defining `libs.groovy.core` is a `libs.versions.toml` file in the `gradle` directory:

[source,toml]
.gradle/libs.versions.toml
----
[libraries]
groovy-core = { group = "org.codehaus.groovy", name = "groovy", version = "3.0.5" }
----

Version catalogs offer several advantages:

- *Type-Safe Accessors*: Gradle generates type-safe accessors for each catalog, enabling autocompletion in IDEs.
- *Centralized Version Management*: Each catalog is visible to all projects in a build.
- *Dependency Bundles*: Catalogs can group commonly used dependencies into <<#sec:dependency-bundles,bundles>>.
- *Version Separation*: Catalogs can separate dependency coordinates from version information, allowing shared version declarations.
- *Conflict Resolution*: Like regular dependency notation, version catalogs declare requested <<#sec:common-version-numbers,versions>> but do not enforce them during <<dependency_constraints.adoc#dependency-constraints,conflict resolution>>.

NOTE: Version catalogs declare _requested_ versions but do not enforce them.
Gradle may still select different versions due to dependency graph conflicts or constraints applied through <<platforms.adoc#platforms,platforms>> or other dependency management APIs.

[[sec:accessing-catalog]]
== Using a catalog

To access items in a version catalog defined in the standard `libs.versions.toml` file located in the `gradle` directory, you use the `libs` object in your build scripts.
For example, to reference a library, you can use `libs.<alias>`, and for a plugin, you can use `libs.plugins.<alias>`.

Declaring dependencies using a version catalog:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/kotlin",files="build.gradle.kts[tags=use_catalog]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/groovy",files="build.gradle[tags=use_catalog]"]
====

Is the same as:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/kotlin",files="build.gradle.kts[tags=use_catalog_equiv]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/groovy",files="build.gradle[tags=use_catalog_equiv]"]
====

If the catalog looks as follows:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/common",files="gradle/libs.versions.toml[]"]
====

Where the catalog can be imported from a <<#sec:importing-catalog-from-file,local file>> or a <<#sec:importing-published-catalog,repository>>.

[[sec:type-unsafe-access-to-catalog]]
Version catalogs use a <<#sec::toml-dependencies-format,TOML format>> in which accessors map directly to the aliases and versions defined in it, providing type-safe access to dependencies and plugins.
This enables IDEs to provide autocompletion, highlight typos, and identify missing dependencies as errors.

[[sec:mapping-aliases-to-accessors]]
=== Aliases and type-safe accessors

Aliases in a version catalog consist of identifiers separated by a dash (`-`) or underscore (`_`).
Type-safe accessors are generated for each alias, normalized to dot notation.

Consider the following catalog:

[source,toml]
.libs.versions.toml
----
[libraries]
# Dashes create nested accessor groups
ktor-client-core    = "io.ktor:ktor-client-core:3.1.0"
ktor-client-cio     = "io.ktor:ktor-client-cio:3.1.0"
ktor-client-logging = "io.ktor:ktor-client-logging:3.1.0"

# A single-segment alias stays flat
junit               = "junit:junit:4.13.2"
----

Each dash in the alias maps to a dot in the accessor, creating a nested group that IDEs can autocomplete:

[cols="1,1"]
|===
|Alias |Generated accessor

|`ktor-client-core`
|`libs.ktor.client.core`

|`ktor-client-cio`
|`libs.ktor.client.cio`

|`ktor-client-logging`
|`libs.ktor.client.logging`

|`junit`
|`libs.junit`
|===

[[sec:classifiers_artifact_types_and_capabilities]]
=== Classifiers, artifact types, and capabilities

Version catalogs intentionally capture only dependency coordinates: `group`, `name`, and `version`.
They do not support classifiers, artifact types (`@aar`, `@zip`), excludes, or capabilities directly in the <<#sec::toml-dependencies-format,TOML>> file.

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-classifiers/common/gradle",files="libs.versions.toml[]"]
====

When you need a specific classifier for a dependency declared in a version catalog, use `variantOf()` at the dependency declaration site in your build script:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-classifiers/kotlin",files="build.gradle.kts[tags=use_classifier]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-classifiers/groovy",files="build.gradle[tags=use_classifier]"]
====

For example, to depend on the sources or Javadoc JAR:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-classifiers/kotlin",files="build.gradle.kts[tags=use_classifier_sources]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-classifiers/groovy",files="build.gradle[tags=use_classifier_sources]"]
====

*Common use cases for classifiers*:

* *Sources and Javadoc JARs*: use the `sources` or `javadoc` classifiers, for example when a code-analysis or documentation-generation task needs the artifact as an input.

* *Platform-specific artifacts*: native libraries may publish separate artifacts for different operating systems or architectures (for example, `linux-x86_64`, `windows-x86_64`), as shown in the primary example above.

* *Test fixtures*: prefer the dedicated `testFixtures(libs.my.lib)` API over declaring the `test-fixtures` classifier explicitly.

For artifact types (common in Android projects needing `@aar`), use the `artifact` block:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-classifiers/kotlin",files="build.gradle.kts[tags=use_artifact_type]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-classifiers/groovy",files="build.gradle[tags=use_artifact_type]"]
====

See <<#sec:toml-limitations, TOML Limitations>> to learn more.

[[sec:importing-published-catalog]]
== Importing a published catalog

A catalog published with the <<#sec:version-catalog-plugin, `version-catalog` plugin>> can be imported in a consumer's `settings.gradle(.kts)` file using the link:{javadocPath}/org/gradle/api/initialization/resolve/DependencyResolutionManagement.html#getVersionCatalogs()[Settings API]:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-javaPlatformCatalog/kotlin/consumer",files="settings.gradle.kts[tags=consume_catalog]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-javaPlatformCatalog/groovy/consumer",files="settings.gradle[tags=consume_catalog]"]
====

The `from()` method accepts standard dependency notation (`"group:artifact:version"`).
Gradle downloads the <<#sec::toml-dependencies-format,TOML>> file from whatever repositories are configured in the `dependencyResolutionManagement` block and makes its entries available as type-safe accessors.

Once imported, all projects in the build can reference the catalog's libraries, plugins, and bundles using the catalog name (e.g., `libs.someLibrary`).

[[sec:importing-catalog-from-file]]
== Importing a catalog from a file

IMPORTANT: Gradle *automatically* imports a catalog in the `gradle` directory named `libs.versions.toml`. You do not need to import it programmatically.

[[sec:sharing-catalogs]]
The link:{javadocPath}/org/gradle/api/initialization/dsl/VersionCatalogBuilder.html[version catalog builder API] allows importing a catalog from an external file, enabling reuse across different parts of a build, such as sharing the main build's catalog with `buildSrc`.

For example, you can include a catalog in the `buildSrc/settings.gradle(.kts)` file as follows:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-toml/kotlin/buildSrc",files="settings.gradle.kts[tags=import_main_catalog]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-toml/groovy/buildSrc",files="settings.gradle[tags=import_main_catalog]"]
====

The link:{javadocPath}/org/gradle/api/initialization/dsl/VersionCatalogBuilder.html#from-java.lang.Object-[VersionCatalogBuilder.from(Object dependencyNotation)] method accepts only a single file, meaning that notations like link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:files(java.lang.Object++[]++)[Project.files(java.lang.Object...)] must refer to one file.
Otherwise, the build will fail.

TIP: Remember that you don't need to import the version catalog named `libs.versions.toml` if it resides in your `gradle` folder. It will be imported automatically.

[[sec:multiple-catalogs]]
== Importing multiple catalogs

You can declare multiple catalogs using the link:{javadocPath}/org/gradle/api/initialization/Settings.html#dependencyResolutionManagement(org.gradle.api.Action)[Settings API].

For example, the default `libs` catalog is auto-imported from `gradle/libs.versions.toml`.
To add additional catalogs for build tools and test dependencies, create `gradle/tools.versions.toml` and `gradle/test.versions.toml` files and register them:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-multipleCatalogs/kotlin",files="settings.gradle.kts[tags=multiple-catalogs]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-multipleCatalogs/groovy",files="settings.gradle[tags=multiple-catalogs]"]
====

Each catalog generates its own extension, so you reference them by name in build scripts:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-multipleCatalogs/kotlin",files="build.gradle.kts[tags=use-multiple-catalogs]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-multipleCatalogs/groovy",files="build.gradle[tags=use-multiple-catalogs]"]
====

[NOTE]
====
To minimize the risk of naming conflicts, each catalog generates an extension applied to all projects, so it's advisable to choose a unique name. One effective approach is to select a name that ends with `Libs`.
====

[[sec:version-catalog-declaration]]
== Creating a catalog

[[sub:conventional-dependencies-toml]]
Version catalogs are conventionally declared using a `libs.versions.toml` file located in the `gradle` subdirectory of the root build.
They use the TOML format:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-toml/common",files="gradle/libs.versions.toml[]"]
====

However, they can reside in other folders and use different names.
See <<sec:importing-catalog-from-file>> for importing a catalog from a custom location, or <<sec:multiple-catalogs>> for registering additional catalogs.

[[sec::toml-dependencies-format]]
=== The TOML format

The version catalog https://toml.io/[TOML] file has four sections:

- `[versions]` – Declares version identifiers.
- `[libraries]` – Maps aliases to GAV coordinates.
- `[bundles]` – Defines dependency bundles.
- `[plugins]` – Declares plugin versions.

The TOML file format is very lenient and allows you to write "dotted" properties as shortcuts for full object declarations.

[[sec:common-version-numbers]]
==== Versions

Versions can be declared either as a single string, in which case they are interpreted as a _required_ version, or as a <<dependency_versions.adoc#sec:rich-version-constraints,rich version>>:

[source,toml]
----
[versions]
other-lib = "5.5.0" # Required version
my-lib = { strictly = "[1.0, 2.0[", prefer = "1.2" } # Rich version
----

Supported members of a version declaration are:

- `require`: the <<dependency_versions.adoc#sec:required-version,required version>>
- `strictly`: the <<dependency_versions.adoc#sec:strict-version,strict version>>
- `prefer`: the <<dependency_versions.adoc#sec:preferred-version,preferred version>>
- `reject`: the list of <<dependency_versions.adoc#sec:rejected-version,rejected versions>>
- `rejectAll`: a boolean to reject all <<dependency_versions.adoc#sec:rejected-version,versions>>

[[sec:libraries]]
==== Libraries

Each library is mapped to a GAV coordinate: `group`, `artifact`, `version`.
They can be declared as a simple string, in which case they are interpreted as coordinates, or a separate group and name:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-toml/common",files="gradle/test-libs.versions.toml[tags=catalog]"]
====

You can also define strict or preferred versions using `strictly` or `prefer`:

[source,toml]
----
[libraries]
commons-lang3 = { group = "org.apache.commons", name = "commons-lang3", version = { strictly = "[3.8, 4.0[", prefer = "3.9" } }
----

In case you want to reference a version declared in the `[versions]` section, use the `version.ref` property:

[source,toml]
----
[versions]
some = "1.4"

[libraries]
my-lib = { group = "com.mycompany", name="mylib", version.ref="some" }
----

[[sec:dependency-bundles]]
==== Bundles

Bundles group multiple library aliases, so they can be referenced together in the build script.

[source,toml]
----
[versions]
groovy = "3.0.9"

[libraries]
groovy-core = { group = "org.codehaus.groovy", name = "groovy", version.ref = "groovy" }
groovy-json = { group = "org.codehaus.groovy", name = "groovy-json", version.ref = "groovy" }
groovy-nio = { group = "org.codehaus.groovy", name = "groovy-nio", version.ref = "groovy" }

[bundles]
groovy = ["groovy-core", "groovy-json", "groovy-nio"]
----

This is useful for pulling in several related dependencies with a single alias:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/kotlin",files="build.gradle.kts[tags=use_dependency_bundle]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/groovy",files="build.gradle[tags=use_dependency_bundle]"]
====

[[sec:plugins-ver]]
==== Plugins

This section defines the plugins and their versions by mapping plugin IDs to version numbers.
Just like libraries, you can define plugin versions using aliases from the `[versions]` section or directly specify the version.

[source,toml]
----
[plugins]
versions = { id = "com.github.ben-manes.versions", version = "0.45.0" }
----

Which can be accessed in any project of the build using the `plugins {}` block.
To refer to a plugin from the catalog, use the `alias()` function:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/kotlin",files="build.gradle.kts[tags=use_plugin]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/groovy",files="build.gradle[tags=use_plugin]"]
====

WARNING: You cannot use a plugin declared in a version catalog in your settings file or settings plugin.

[[sec:avoiding_subgroup_accessors]]
=== Avoiding subgroup accessors

To avoid generating subgroup accessors, use camelCase notation:

[cols="1,1"]
|===
|Aliases |Accessors

|`groovyCore`
|`libs.groovyCore`

|`groovyJson-core`
|`libs.groovyJson.core`

|===

If you cannot rename aliases, for example, when consuming a published catalog, use `asProvider()` to access the parent version directly.

Given a catalog with both `jackson` and `jackson-databind` version aliases, `libs.versions.jackson` returns the subgroup accessor (because `jackson-databind` creates a `jackson.databind` subgroup).
To get the `jackson` version itself, call `asProvider()`:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-asprovider/kotlin",files="build.gradle.kts[tags=use_version_asprovider]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-asprovider/groovy",files="build.gradle[tags=use_version_asprovider]"]
====

[[sec:reserved_keywords]]
=== Reserved keywords

Certain keywords, like `extensions`, `class`, and `convention`, are reserved and cannot be used as aliases.
Additionally, `bundles`, `versions`, and `plugins` cannot be the first subgroup in a dependency alias.

For example, the alias `versions-dependency` is not valid, but `versionsDependency` or `dependency-versions` are valid.

[[sec:toml-limitations]]
=== Limitations

These are explicit limitations the catalog TOML format does not support:

* `classifier` attributes
* `type = "aar"` or `ext = "zip"` artifact types
* `exclude` rules
* `capabilities` requirements

*Workarounds*: for classifiers and artifact types, see <<#sec:classifiers_artifact_types_and_capabilities, Classifiers, artifact types, and capabilities>>.
For excludes and capabilities, apply them at the dependency declaration site in your build script using the standard dependency configuration DSL.

[[sec:programmatic-catalog-versions]]
== Programming catalogs

Version catalogs can be declared programmatically in the `settings.gradle(.kts)` file using the link:{javadocPath}/org/gradle/api/initialization/Settings.html[Settings API]:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/kotlin",files="settings.gradle.kts[tags=catalog_with_versions]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-settings/groovy",files="settings.gradle[tags=catalog_with_versions]"]
====

TIP: Don't use `libs` for your programmatic version catalog name if you have the default `libs.versions.toml` in your project.

[[sec:version-catalog-plugin]]
== Publishing a catalog

There are three ways to share a version catalog across builds:

1. **Check the TOML file into source control** — The simplest approach.
Place `gradle/libs.versions.toml` in a shared repository that all builds can access.
This works well for monorepos or when teams can reference a common Git repository.

2. **Write a <<implementing_gradle_plugins_precompiled.adoc#settings_pre_compiled_plugins,settings plugin>>** — Create a plugin that programmatically declares catalog entries, publish it to the Gradle Plugin Portal or an internal repository, and have consumers apply it in their settings file.
This offers the most flexibility but requires more effort.

3. **Use the `version-catalog` plugin** — Publish the catalog as a Maven or Ivy artifact so it can be consumed like any other dependency.
This is the best approach for organizations that need to distribute a catalog to many independent builds.

[[sec:using_the_version_catalog_plugin]]
=== Using the `version-catalog` plugin

The `version-catalog` plugin lets you publish a catalog as a Maven or Ivy artifact.
It works with both an existing TOML file and programmatic catalog declarations.

If you already have a `gradle/libs.versions.toml` file, you can publish it directly by importing it into the link:{javadocPath}/org/gradle/api/plugins/catalog/CatalogPluginExtension.html[catalog extension]:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-publishTomlFile/kotlin",files="build.gradle.kts[tags=publish_toml_file]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-publishTomlFile/groovy",files="build.gradle[tags=publish_toml_file]"]
====

This keeps the TOML file as the single source of truth — there is no need to redeclare entries in the build script.

Alternatively, you can declare the catalog entries programmatically in the `catalog` extension:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-versionCatalogPlugin/kotlin",files="build.gradle.kts[tags=catalog_spec]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-versionCatalogPlugin/groovy",files="build.gradle[tags=catalog_spec]"]
====

In both cases, configure a publication using the `versionCatalog` component:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-versionCatalogPlugin/kotlin",files="build.gradle.kts[tags=catalog_publish]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-versionCatalogPlugin/groovy",files="build.gradle[tags=catalog_publish]"]
====

When you run `./gradlew publish`, the catalog is uploaded as a Maven artifact (with the `.toml` extension).
This artifact can then be <<#sec:importing-published-catalog,imported by other Gradle builds>>.

NOTE: The published artifact is a standard TOML file attached to Maven coordinates (e.g., `com.mycompany:catalog:1.0`).
Consumers reference these coordinates to import the catalog — they do not need access to the original source code or build script.

For example, a consumer imports the published catalog in their `settings.gradle(.kts)` file:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-javaPlatformCatalog/kotlin/consumer",files="settings.gradle.kts[tags=consume_catalog]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-javaPlatformCatalog/groovy/consumer",files="settings.gradle[tags=consume_catalog]"]
====

TIP: For the full plugin reference — apply syntax, tasks, dependency configurations, extension and publishing component — see the <<version_catalog_plugin.adoc#version_catalog_plugin,Version Catalog Plugin>> page.

[[sec:changing-catalog-name]]
== Changing the catalog name

By default, the `libs.versions.toml` file is used as input for the `libs` catalog.
However, you can rename the default catalog if an extension with the same name already exists:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-toml/kotlin",files="settings.gradle.kts[tags=change_default_extension_name]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-toml/groovy",files="settings.gradle[tags=change_default_extension_name]"]
====

[[sec:overwriting-catalog-versions]]
== Overwriting catalog versions

You can overwrite versions when importing a catalog:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-javaPlatformCatalog/kotlin/consumer",files="settings.gradle.kts[tags=overwrite_version]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-javaPlatformCatalog/groovy/consumer",files="settings.gradle[tags=overwrite_version]"]
====

In the examples above, any dependency referencing the `groovy` version will automatically be updated to use `3.0.6`.
You can see how this is used in <<#sec:working-multiple-version-catalogs,Working with multiple version catalogs>>.

NOTE: Overwriting a version only affects what is imported and used when declaring dependencies.
The actual resolved dependency version may differ due to conflict resolution.

[[sec:buildsrc-version-catalog]]
== Using a catalog in `buildSrc`

Version catalogs provide a centralized way to manage dependencies in a  project.
However, **`buildSrc` does not automatically inherit the version catalog from the main project**, so additional configuration is required.

To access a version catalog inside `buildSrc`, you need to explicitly import it in `buildSrc/settings.gradle(.kts)`:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-toml-buildSrc/kotlin",files="buildSrc/settings.gradle.kts[]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-toml-buildSrc/groovy",files="buildSrc/settings.gradle[]"]
====

Once the version catalog is imported, dependencies can be referenced using a few tricks:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-toml-buildSrc/kotlin",files="buildSrc/build.gradle.kts[]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-toml-buildSrc/groovy",files="buildSrc/build.gradle[]"]
====

In **precompiled script plugins** inside `buildSrc`, the version catalog can be accessed using `extensions.getByType(VersionCatalogsExtension)` as demonstrated in the dependencies block of this convention plugin:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-toml-buildSrc/kotlin",files="buildSrc/src/main/kotlin/java-commons-convention.gradle.kts[]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-toml-buildSrc/groovy",files="buildSrc/src/main/groovy/java-commons-convention.gradle[]"]
====

However, the plugins block in the **precompiled script plugin** cannot access the version catalog.

[[sec:working-multiple-version-catalogs]]
== Working with multiple version catalogs

Most builds should use a **single `libs.versions.toml` file**.
A single catalog centralizes all dependency coordinates, avoids version duplication, and lets every subproject share the same type-safe accessors.
Use naming conventions, such as alias prefixes, to logically separate groups of dependencies within that file:

[source,toml]
.libs.versions.toml
----
[versions]
kotlin = "2.4.10"
junit = "5.12.0"

[libraries]
# ── Production ───────────────────────────────
guava = { module = "com.google.guava:guava", version = "33.4.0-jre" }
commons-lang3 = { module = "org.apache.commons:commons-lang3", version = "3.17.0" }

# ── Testing ──────────────────────────────────
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
mockito-core = { module = "org.mockito:mockito-core", version = "5.14.0" }
----

Consider splitting into **multiple catalogs** only when you have a concrete need to enforce boundaries between dependency scopes.
Typical reasons include:

- **Auditing shipped artifacts.**
When you must clearly distinguish which dependencies end up in a published distribution from those used only for testing or code generation, separate catalogs make accidental cross-contamination visible at the declaration site.

- **Independent build-logic dependencies.**
Plugins applied inside `build-logic` or `buildSrc` may need their own catalog that is resolved in the settings classpath — before the main build's catalog is available.

- **Organizational sharing.**
An organization-wide "platform" catalog is published as a Maven artifact and imported by many repositories, while each repository maintains a local catalog for project-specific dependencies.

If none of these situations apply, a single catalog with clear naming conventions is simpler and avoids the version-sharing challenges described below.

[[sec:sharing_versions_across_multiple_catalogs]]
=== Sharing Versions Across Multiple Catalogs

Each version catalog TOML file is **self-contained**.
There is no built-in syntax, such as an `include` directive or cross-file `version.ref`, that lets one TOML file reference a version declared in another.
If the same library version must appear in two catalogs, you must arrange for it to reach both catalogs yourself.

The `from()` method, which loads a catalog from a TOML file or a published artifact, may only be called **once per catalog**.
Attempting to call it twice produces an error:

NOTE: In version catalog libs, you can only call the `from` method a single time.

This means you cannot merge two TOML files into a single catalog.

Below are three concrete workarounds, ordered from simplest to most flexible.

[[sec:workaround_1_duplicate_and_verify]]
==== Workaround 1 — Duplicate and verify

Declare the shared version in every TOML file that needs it, and add a lightweight check that the values stay in sync:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-duplicateAndVerify/kotlin/gradle",files="distribution.versions.toml[tags=versions]"]
====

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-duplicateAndVerify/kotlin/gradle",files="test.versions.toml[tags=versions]"]
====

Add a small verification task (or a CI script) that parses both files and fails the build if the values diverge:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-duplicateAndVerify/kotlin",files="build.gradle.kts[tags=verify_shared_versions]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-duplicateAndVerify/groovy",files="build.gradle[tags=verify_shared_versions]"]
====

This approach is straightforward and keeps each TOML file independently readable, but it requires discipline and will not scale well beyond a handful of shared versions.

[[sec:workaround_2_external_properties_file]]
==== Workaround 2 — External properties file injected programmatically

Extract shared versions into a plain properties file and inject them into each catalog in `settings.gradle(.kts)`.

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-externalProperties/kotlin/gradle",files="shared-versions.properties[tags=shared_versions]"]
====

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-externalProperties/kotlin",files="settings.gradle.kts[tags=inject_versions]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-externalProperties/groovy",files="settings.gradle[tags=inject_versions]"]
====

The TOML files use `version.ref` to reference these versions as if they were declared locally:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-externalProperties/kotlin/gradle",files="distribution.versions.toml[tags=catalog]"]
====

When you call `version("errorProne", "2.28.0")` on the catalog builder *after* `from(files(...))`, the programmatic call adds or overrides the version in the catalog that was loaded from the TOML file.
Libraries in the TOML file that reference `version.ref = "errorProne"` will pick up the injected value.

This is the pattern the Gradle Build Tool team uses in the `gradle/gradle` repository, where a `shared-versions.properties` file feeds versions into four separate catalogs (`distribution`, `provided`, `test`, `build`).

[[sec:workaround_3_published_base_catalog]]
==== Workaround 3 — Published base catalog with local overrides

For organizations that share a common set of dependency versions across many repositories, publish a base catalog as a Maven artifact and let each repository layer project-specific versions on top.

Publishing project (`build.gradle(.kts)`):

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-publishedCatalogOverrides/kotlin/catalog",files="build.gradle.kts[tags=publish_catalog]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-publishedCatalogOverrides/groovy/catalog",files="build.gradle[tags=publish_catalog]"]
====

Consuming project (`settings.gradle(.kts)`):

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-publishedCatalogOverrides/kotlin/consumer",files="settings.gradle.kts[tags=consume_with_overrides]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-publishedCatalogOverrides/groovy/consumer",files="settings.gradle[tags=consume_with_overrides]"]
====

This pattern cleanly separates organizational standards from project-level concerns, but it introduces a publishing and versioning lifecycle for the catalog artifact itself.

[[sec:combining_from_with_programmatic_version_calls]]
=== Combining `from()` with Programmatic `version()` Calls

The version catalog builder API allows you to **mix** a TOML file import with programmatic declarations in the same catalog.
The `from()` call loads the base content, and subsequent `version()`, `library()`, `bundle()`, or `plugin()` calls add to or override that content.

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-combineFromWithVersion/kotlin",files="settings.gradle.kts[tags=combine_from_with_version]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-combineFromWithVersion/groovy",files="settings.gradle[tags=combine_from_with_version]"]
====

This works identically when importing from a published artifact:

====
[.multi-language-sample]
=====
[source,kotlin]
----
create("libs") {
    from("com.mycompany:catalog:1.0")
    version("guava", "33.5.0-jre")  // override the published version
}
----
=====
[.multi-language-sample]
=====
[source,groovy]
----
libs {
    from("com.mycompany:catalog:1.0")
    version("guava", "33.5.0-jre")  // override the published version
}
----
=====
====

A common scenario is needing the same Kotlin version for both the `kotlin("jvm")` plugin and the `kotlin-stdlib` library dependency.
Plugins are resolved from the `[plugins]` section, while libraries come from `[libraries]` — and both need the same version.

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-kotlinVersionSharing/common",files="gradle/catalog.versions.toml[tags=kotlin_catalog]"]
====

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-kotlinVersionSharing/kotlin",files="settings.gradle.kts[tags=kotlin_version_sharing]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-kotlinVersionSharing/groovy",files="settings.gradle[tags=kotlin_version_sharing]"]
====

Both the plugin alias and the library aliases resolve to `2.4.10`, and updating requires changing only one line in `settings.gradle(.kts)`.

[[sec:using_catalog_entries_in_gradle_apis]]
== Using catalog entries in Gradle APIs

A version catalog accessor such as `libs.groovy.core` returns a `Provider<MinimalExternalModuleDependency>`.
Calling `.get()` on it unwraps the provider and gives you the `MinimalExternalModuleDependency` directly.

In dependency declarations, both forms work identically:

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-gradleApis/kotlin",files="build.gradle.kts[tags=use_catalog_entries]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-gradleApis/groovy",files="build.gradle[tags=use_catalog_entries]"]
====

However, in other Gradle APIs, such as dependency substitution rules, dependency constraints, or any API that accepts a dependency notation, **try to pass the provider** (`libs.groovy.core`) rather than the unwrapped value (`libs.groovy.core.get()`):

====
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-gradleApis/kotlin",files="build.gradle.kts[tags=use_provider_in_apis]"]
include::sample[dir="snippets/reference/dependency-management/centralizing-dependencies/catalogs-gradleApis/groovy",files="build.gradle[tags=use_provider_in_apis]"]
====

When you pass the provider, Gradle handles any necessary type conversions internally.
Unwrapping with `.get()` gives you a `MinimalExternalModuleDependency`, which implements `ExternalDependency` and `ModuleVersionSelector` — but some resolution APIs expect `ModuleComponentSelector`, a different type.
Passing the provider avoids mismatches between these types.
