The Terraform dependency lock file records which provider versions you selected and their checksums, so later runs make the same choice and flag a changed package. It uses trust on first use, and at present it tracks only providers, not modules. Commit it and review changes to it like code.
Definition
The lock file is named .terraform.lock.hcl and belongs to the configuration as a whole. Terraform creates or updates it each time you run terraform init. Version constraints in your configuration say which versions are acceptable, and the lock file remembers the exact choice so it can be repeated.
Providers are plugins. Terraform downloads them and runs them with access to whatever credentials you gave the provider block, so a provider package is high trust code in an infrastructure pipeline.
What the lock file does
| Behavior | Detail |
|---|---|
| Pins selection | Same provider version on later runs, by default |
| Verifies on install | Each installed package must match at least one recorded checksum, or Terraform errors |
| Trust on first use | The first install defines what "expected" means |
| Signed checksums | If the origin registry signs checksums, Terraform treats the signed ones as valid as long as one matches |
| Multi platform | The file can include checksums for packages for other platforms |
The documentation is explicit that the checksum check is a trust on first use approach. If the first install already came from a bad source, the lock file records the bad result faithfully. The signature behavior gives extra assurance on signed providers, and the init output shows the key fingerprint, with a label such as signed by a HashiCorp partner.
What it does not protect
First, modules. The docs say the lock file currently tracks only provider dependencies. Module sources need their own pinning, using exact versions or commit references and review of changes.
Second, the first install. Nothing in the file proves the original download was legitimate. That is why you also care about where providers come from: official namespaces versus community providers.
Third, the provider's behavior. A correctly pinned and signed provider can still have a bug or a vulnerability. The lock file preserves integrity, not safety.
Habits that make it useful
- Commit the lock file. The docs recommend including it in version control so changes go through code review.
- Treat a diff in the lock file as a review item. Ask which provider changed, from which version to which, and why.
- Generate checksums for every platform your team and CI use, so nobody runs init and silently rewrites the file because of a platform mismatch.
- Upgrade providers deliberately with an init upgrade in a branch, not as a side effect.
- Pin module versions explicitly and avoid floating references to a branch name.
- Prefer providers from official or well known publishers. For community providers, read the repository and release process before first use, since first use is the moment the file trusts.
- Run planning with the least privileged credentials that can do the job, because providers run with them.
A quick review prompt
When a pull request touches .terraform.lock.hcl, ask three questions: did a version change on purpose, did the source address stay the same, and did the set of checksums change in a way that matches adding a platform rather than swapping a package?
Try it yourself
Click through it at your own pace, or open it full screen. Watch a dependency change get checked before merge, as a lock file diff should be.
Where Safeguard fits
Safeguard's SBOM and dependency scanning, plus policies and gates, can check infrastructure repositories for changes before merge. The free scan is at gold.safeguard.sh/scan.
Quick check
Does the lock file cover Terraform modules?
Not at present. The documentation says it tracks only provider dependencies, so pin modules separately.
What does trust on first use mean here?
The first download defines the expected checksums. Later installs are checked against them, but the first one is taken on trust unless the provider's signed checksums apply.
Sources
Last reviewed: 19 October 2026.
