How do you lock Android SDK versions with Gradle lockfiles?

Enable Gradle dependency locking, run the write-locks task to create gradle.lockfile, commit that file, and update individual modules only when you decide to. Locked versions become strict constraints, so builds stop drifting even if a library uses a dynamic version.

What dependency locking does

Gradle's documentation says locking saves the resolved versions of dependencies to a lock file so later builds reuse them. The file is called gradle.lockfile and sits in each project directory. Buildscript dependencies use a separate buildscript-gradle.lockfile. Each line holds group, artifact and version, plus the configurations that include it. Gradle says the file is expected to be part of source control.

Android's own guidance says you should not use dynamic version numbers such as a plus sign in a version, because it can cause unexpected updates and hard to resolve differences. Locking is one defence if you inherit builds that already use them. Removing the dynamic versions is the better fix, as covered in why to avoid dynamic versions in mobile releases.

Steps

1. Turn locking on for all configurations in your build script:

dependencyLocking {
    lockAllConfigurations()
}

2. Generate the lock state:

./gradlew dependencies --write-locks

3. Commit every gradle.lockfile that appears.
4. Build as usual. Gradle checks that resolution matches the lock state.
5. To move one library, update only that module:

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

6. Review the lockfile diff in the pull request like any code change.

How it behaves

Gradle adds the locked versions as strict constraints. For transitive dependencies this pins the version. For direct dependencies, the declared version acts as a requirement, so if you declare a version higher than the locked one, resolution fails until you update the lock state. That failure is useful: it tells you the lock and the build file disagree.

Gradle also will not write lock state if the build fails, so a broken build cannot silently rewrite your pins.

Caveats

• Locking should not be used with changing versions such as snapshots, because their content can change while the coordinates stay the same.
• A lock file records versions, not trust. Pair it with dependency verification, covered in our post on checksums and signatures.
• Version catalogs and locking solve different problems. Android recommends version catalogs for managing versions in one place. Locking records what actually resolved, including transitive libraries a catalog does not list.

Connect it to approval

Treat a lockfile change as an SDK change. If the diff adds a new group and artifact, that is a new dependency and needs a request. If it only bumps a patch version of an approved SDK, a lighter review fits. The SDK risk tiers help decide which.

Safeguard reads Gradle manifests and lock files during SBOM and dependency scanning, so the resolved set you commit is also the set that gets checked. A free scan is at gold.safeguard.sh/scan.

Quick check

Sources

• Gradle: Locking dependency versions
• Android Developers: Add build dependencies

Last reviewed: 19 October 2026.