The Version Catalog Plugin (plugin id: version-catalog) lets you publish a version catalog as a Maven or Ivy artifact, so it can be consumed like any other dependency by independent Gradle builds. It works with both an existing libs.versions.toml file and programmatic catalog declarations.

For an introduction to version catalogs themselves — the TOML format, aliases, bundles, and how to consume them — see Version Catalogs.

Usage

To use the Version Catalog Plugin, include the following in your build script:

build.gradle.kts
plugins {
    `version-catalog`
    `maven-publish`
}
build.gradle
plugins {
    id 'version-catalog'
    id 'maven-publish'
}

Applying the plugin adds a catalog extension, a generateCatalogAsToml task, and registers a versionCatalog software component for publishing.

Tasks

generateCatalogAsToml (type TomlFileGenerator)

Generates the version catalog TOML file from the configured catalog. The default output location is layout.buildDirectory.file("version-catalog/libs.versions.toml"). When the Base Plugin is applied — for example, transitively by a publishing plugin — this task is wired into the assemble lifecycle task.

Dependency management

The Version Catalog Plugin adds the following dependency configurations:

versionCatalog

Declarable. Used to declare the platforms and dependencies whose coordinates and versions make up the generated catalog.

versionCatalogElements

Consumable. Exposes the generated TOML catalog as an artifact for publishing and consumption, with the org.gradle.category=platform and org.gradle.usage=version-catalog attributes. This configuration backs the versionCatalog component.

Contributed extension

The plugin adds the catalog extension to the project. Configure the catalog contents through its nested versionCatalog { } block, which exposes a VersionCatalogBuilder.

If you already have a gradle/libs.versions.toml file, you can publish it directly by importing it — keeping the TOML file as the single source of truth:

build.gradle.kts
plugins {
    `version-catalog`
    `maven-publish`
}

catalog {
    versionCatalog {
        from(files("gradle/libs.versions.toml"))
    }
}

group = "com.mycompany"
version = "1.0"

publishing {
    publications {
        create<MavenPublication>("maven") {
            from(components["versionCatalog"])
        }
    }
}
build.gradle
plugins {
    id 'version-catalog'
    id 'maven-publish'
}

catalog {
    versionCatalog {
        from(files("gradle/libs.versions.toml"))
    }
}

group = 'com.mycompany'
version = '1.0'

publishing {
    publications {
        maven(MavenPublication) {
            from components.versionCatalog
        }
    }
}

Alternatively, declare the catalog entries programmatically:

build.gradle.kts
catalog {
    // declare the aliases, bundles and versions in this block
    versionCatalog {
        library("my-lib", "com.mycompany:mylib:1.2")
    }
}
build.gradle
catalog {
    // declare the aliases, bundles and versions in this block
    versionCatalog {
        library('my-lib', 'com.mycompany:mylib:1.2')
    }
}

Publishing

The plugin registers a versionCatalog software component. Attach it to a Maven or Ivy publication to publish the catalog:

build.gradle.kts
publishing {
    publications {
        create<MavenPublication>("maven") {
            from(components["versionCatalog"])
        }
    }
}
build.gradle
publishing {
    publications {
        maven(MavenPublication) {
            from components.versionCatalog
        }
    }
}

Running ./gradlew publish uploads the catalog as an artifact (with the .toml extension). Consumers then import it in their settings.gradle(.kts) file using standard dependency notation.