Yes, commit .terraform.lock.hcl. It records the exact provider version Terraform selected, plus checksums of valid packages, so every machine and pipeline installs the same provider and any change appears in a pull request. It tracks providers only, not modules, so pin those separately.
What is inside
For each provider, the lock file records the selected version, the version constraints Terraform considered and a set of hashes for valid packages of that version. Terraform creates and updates it during terraform init.
HashiCorp's documentation advises including the file in version control. The stated benefit is that you can discuss changes to external dependencies through code review, as you would any configuration change.
What it protects against
Without a lock file, a constraint like ~> 5.0 lets each run pick the newest matching provider. Two runs a day apart can use different code. With the lock file, terraform init reselects the recorded version even when a newer one exists.
The hashes add a second check. If the package Terraform downloads does not match a recorded hash, installation fails. That catches a tampered or swapped package for that version, assuming your recorded hash was good when it was added.
Upgrades become visible
The only normal way the version moves is terraform init -upgrade, which ignores existing selections and picks the newest version allowed by your constraints, then updates the file. That diff is the review point. A reviewer can see which provider moved and look at its release notes before merge.
Multiple platforms
The h1: hash is the current scheme and can be calculated from an official zip, an unpacked directory or a recompressed zip. The older zh: hash covers the official zip packages indexed in the registry. Terraform adds h1: hashes over time as it verifies packages on new platforms, which can cause lock file churn when a teammate on a different operating system runs init.
To avoid that, run terraform providers lock with several -platform flags, for example linux_amd64, darwin_amd64 and windows_amd64. It records checksums for each, so CI and laptops agree. This is also useful with a mirror, which cannot supply the official signed checksums.
Limits worth knowing
- Providers only. The documentation says the lock file tracks only provider dependencies. Modules are not recorded, so pin those separately.
- First trust. The hash proves you got the same package as before, not that the first package was safe.
- A lock file nobody reviews. If the file is committed but approvals skip it, the protection is decorative.
A short policy
- Commit the lock file in every root module.
- Run init with upgrade only in a dedicated pull request.
- Require a reviewer on changes to the lock file.
- Pin module sources separately.
If you want a record of which providers and modules each deployment pulls in, Safeguard's SBOM and dependency scanning can inventory them.
Click through it at your own pace, or open it full screen.
Quick check
Does the lock file pin my modules too?
No. HashiCorp's documentation says it currently tracks only provider dependencies. Pin module versions or git refs in the module source.
Why does the lock file change when a teammate runs init?
Terraform adds h1: checksums as it verifies packages on new platforms. Run terraform providers lock with all your platforms to stop the churn.
Sources
Last reviewed: 19 October 2026.
