A BOM or platform controls resolution, because it adds constraints that Gradle applies. A version catalog does not: the Gradle docs say catalogs centralize coordinates and give type-safe accessors but, unlike platforms, do not affect dependency resolution. Most projects benefit from both, each doing its own job.
Definitions
A version catalog is a file, usually gradle/libs.versions.toml, listing libraries, versions, bundles and plugins under aliases. It tells the build what to request.
A platform is a set of dependency constraints, written with the java-platform plugin or imported from a BOM. It tells the resolver which versions to prefer or require.
Side by side
| Question | Version catalog | Platform or BOM |
|---|---|---|
| What does it hold? | Coordinates and versions under aliases | Constraints |
| Does it change resolution? | No | Yes |
| Can it keep related modules aligned? | Only by sharing a version reference | Yes |
| Where does it help most? | Consistency across subprojects | Families like logging or test libraries |
| Does it cover plugins? | Yes, a plugins section | No |
Android's docs recommend version catalogs for adding and managing build dependencies, and say new projects use them by default. That says nothing about constraints, which is why a catalog alone leaves a gap.
How they work together
Put the BOM in the catalog as a library entry, then import it in the build file with platform(). Use the catalog for names and versions across subprojects, and the platform for alignment inside a family. Our deeper look at the first half is in Gradle version catalogs: versions are requests.
Decision guide
- Need one place to change a version for many subprojects? Use a catalog.
- Need a family of modules to stay on matching versions? Use a platform.
- Need to force a patched transitive version for one module? Use a constraint, see forcing patched versions with constraints.
- Need to pin everything in an application? Consider enforcedPlatform, covered in platform or enforcedPlatform.
- Always confirm the result with dependencyInsight.
A common mistake
Teams update a version in the catalog and assume the build uses it. If another dependency asks for a higher version, conflict resolution can still pick the higher one. The catalog entry was a request. Check what resolved, not what you wrote.
Try it yourself
Click through it at your own pace, or open it full screen.
Follow a finding to the version that is actually present. Resolved versions, not declared ones, decide exposure.
Safeguard's dependency scanning reports on resolved components, and the free scan at gold.safeguard.sh/scan lets you check what your build resolves.
Quick check
If I bump a version in the catalog, is it guaranteed to resolve?
No. Catalog versions are requests, and conflict resolution can select a different version. Confirm with a dependency report.
Can a catalog hold a BOM?
Yes, as a library entry, which you then import with platform() in the build file.
Sources
Last reviewed: 19 October 2026.
