Gradle Module Metadata is a file published alongside a library's POM that describes variants, capabilities and richer version constraints. Tools that read only the POM still work, in what Gradle calls degraded mode, but they can see a flatter picture. This matters for multiplatform libraries and for any scanner that parses POMs.
Definition
The Gradle docs define Gradle Module Metadata as a format used to serialize the Gradle component model. It supports rich version constraints, dependency constraints, component capabilities and variant-aware resolution. The stated aim is better resolution by making it multi-platform and variant-aware.
It does not replace the POM. The docs say it is published alongside the POM or Ivy file to maximize compatibility with third-party tools. The POM carries a marker comment telling Gradle the richer file exists, which the docs describe as a performance optimization that saves a network request.
What gets lost in translation
According to the docs, Gradle-specific features map imperfectly onto POM and Ivy:
| Feature | In the POM or Ivy file |
|---|---|
| Dependency constraints | Not published for Ivy |
| Component capabilities | Not published for either format |
| Feature variant dependencies | Become optional dependencies in Maven |
Gradle also warns at publication time when a build uses features that only the metadata file can represent.
Why a security reader should care
Multiplatform libraries use variants to point at different artifacts per target. A tool that reads only the POM may list the common artifact and miss the platform artifacts Gradle would actually resolve. The result is an inventory that is correct for the POM and incomplete for the build.
The reverse also happens. A POM can list an optional dependency that Gradle's richer metadata models as a feature variant. A POM-only tool may treat it as present when your build never pulls it in.
How to compare an inventory with reality
- Take the list from your scanner or SBOM for one module.
- Ask the build for its own resolved graph for the same module and configuration.
- Compare the two lists by coordinate and version.
- For any difference, check whether the library publishes a metadata file by looking in the repository next to the POM for the module file.
- Prefer scans that read the build's resolved graph or lockfiles over POM parsing alone.
The mismatch types are the same as in why your SBOM is missing components.
Can a publisher turn it off?
Yes. The docs say publication can be disabled by disabling the GenerateModuleMetadata task, for example when a repository rejects the format. If you consume a library that did this, a POM-only view is all anyone gets.
Try it yourself
Click through it at your own pace, or open it full screen.
Compare the listed components with what you expect from your build, and note anything missing.
Safeguard's SBOM and dependency scanning are built to inventory what a repository resolves, and the free scan at gold.safeguard.sh/scan lets you compare the result with your own graph.
Quick check
Does Gradle Module Metadata replace the POM?
No. The docs say it is published alongside the POM or Ivy file.
Do Maven builds understand it?
Tools that read only the POM still work, in degraded mode according to the Gradle docs, and may not see variant detail.
Sources
Last reviewed: 19 October 2026.
