---
updatedAt: 2026-10-12T21:00:29.000Z
agentTools:
  projectIndex: https://docs.socket.dev/llms.txt
---

# Gradle setup instructions (for Java, Kotlin, and Scala)

The recommended way to use Socket with a Gradle project is to generate a **Socket facts** file with the Socket CLI. `socket manifest gradle` resolves your full dependency graph locally and writes a single Socket facts file, the preferred SBOM format for Socket. The committed-file options (`gradle.lockfile` and `libs.versions.toml`) remain supported if you prefer not to run the CLI.

## Generate a manifest with the CLI (recommended)

The recommended approach is to generate a Socket facts file from your local Gradle setup. By default `socket manifest gradle` emits a single Socket facts file (such as `gradle.socket.facts.json`) describing the resolved dependency graph of the whole build.

```bash
socket manifest gradle
```

You can use `socket manifest gradle --help` to get more information on how to run Gradle more directly. This will work for Gradle, Kotlin, and Scala projects that use Gradle (not `sbt`, see [Scala setup instructions](https://docs.socket.dev/docs/scala-setup-instructions) for working with Scala's `sbt` files).

`socket manifest gradle` covers the build in the directory you run it from. If your repository contains several independent Gradle builds, run `socket manifest dynamic-sbom-inference` instead to generate a Socket facts file for each of them (see [Multiple builds](https://docs.socket.dev/docs/socket-manifest#multiple-builds)).

After generating the manifest files you can use `socket scan create` to [create a report](https://docs.socket.dev/docs/socket-scan).

> **Reachability:** For [full application reachability](full-application-reachability) scans, we recommend `socket scan create --reach --dynamic-sbom-inference`. Manifests are generated as part of the scan for every Gradle build under the scan target (not just the one at the root), and reachability is analyzed and reported per subproject. It works from the dependency graph `gradle` itself resolves, including where each dependency lives, so the analysis can reliably install the dependencies it needs.

### CycloneDX

Alternatively you can use the open source [CycloneDX Gradle plugin](https://github.com/CycloneDX/cyclonedx-gradle-plugin) to generate and commit an SBOM which Socket will scan. You can run `socket cdxgen --help` for details.

To setup a single CycloneDX file that can be checked in you can run:

```
socket cdxgen -t gradle -o socket-gradle.cdx.json --install-deps --lifecycle build
```

<br />

## `gradle.lockfile`

If you'd rather commit a file to source control than run the CLI, committing a `gradle.lockfile` is the simplest option. If you haven't already, [enable lockfiles in gradle](https://docs.gradle.org/current/userguide/dependency_locking.html) , and then commit the generated `gradle.lockfile` to source control. No extra setup is required!

### Add dependency locking configuration to `build.gradle`.

1. **Add locking configuration to `build.gradle`:**

   ```groovy
   dependencyLocking {
       lockAllConfigurations()
   }
   ```

   This tells Gradle to track locked versions for all configurations (compileClasspath, runtimeClasspath, etc.)

2. **Run the write-locks command:**
   ```bash
   ./gradlew dependencies --write-locks
   ```
   With locking enabled, this resolves all dependencies and writes their exact versions to `gradle.lockfile`.

### What the lockfile does

* Pins every dependency (direct and transitive) to exact versions
* Ensures reproducible builds across machines/CI
* Fails the build if resolved versions differ from locked versions (unless you explicitly update)

### To update locks later

```bash
./gradlew dependencies --write-locks
```

Or update a single dependency:

```bash
./gradlew dependencies --update-locks org.slf4j:slf4j-api
```

<br />

## `libs.versions.toml`

Socket can also build an SBOM from Gradle [version catalog](https://docs.gradle.org/current/userguide/platforms.html#sub:version-catalog) files (`libs.versions.toml`). If your project already uses a version catalog, Socket will automatically detect and parse it — no extra setup is required.

> ⚠️ **Limitations:** The `libs.versions.toml` file is a *declaration* of available dependencies and versions — it does not reflect which dependencies are actually applied in your `build.gradle` files. This means:
>
> * Dependencies added directly in `build.gradle` or `build.gradle.kts` (outside the version catalog) **will not be included** in the generated SBOM.
> * Dependencies declared in `libs.versions.toml` but **not referenced** in any `build.gradle` file **will still appear** in the SBOM.
>
> For the most accurate results, generate a Socket facts file with `socket manifest gradle` (recommended) or commit a `gradle.lockfile`.