The terraform providers lock command adds provider version and checksum entries to your dependency lock file without installing the providers. Run it when your team uses mixed operating systems, or when providers come from a mirror, so that every platform verifies against the official checksums.
What problem it solves
The lock file, .terraform.lock.hcl, normally updates as a side effect of terraform init. That works if everyone runs the same platform and installs straight from the origin registry. It breaks down in two cases.
First, a mirror. When Terraform installs a provider from a filesystem or network mirror, it cannot see the official checksums for other platforms, so it records only what it can verify locally. Second, mixed platforms. If a laptop on one operating system creates the lock file and CI runs on another, the CI run may add new checksums and show a lock file change you did not expect.
The command
terraform providers lock -platform=linux_amd64 -platform=darwin_arm64
Terraform reads your configuration, finds the providers it needs, fetches information from each origin registry, and writes the selected versions plus the checksums covered by the provider developer's signature. Commit the result.
Before and after
| Situation | Without the command | With the command |
|---|---|---|
| Provider from a mirror | Only the local platform is recorded | Official checksums for each listed platform are recorded |
| Laptop and CI differ | CI may add hashes and dirty the file | Hashes are already present |
| Mirror serves a tampered package | May go unnoticed on first install | Init compares the package to official checksums and fails on mismatch |
The third row follows the HashiCorp description: after the official checksums are recorded, later terraform init runs verify that the packages in your mirror match the official ones.
What it does not do
HashiCorp's own page warns that the command prints whether each package was signed, but it cannot decide whether a provider is trustworthy or compliant with your requirements. You still choose which providers to adopt. The lock file records that choice and protects it from silent change.
Steps
- Run
terraform initnormally on a clean checkout. - List every platform that runs Terraform in your team and pipelines.
- Run
terraform providers lockwith a-platformflag for each. - Review the diff in the lock file like any other code change.
- Commit it, and repeat whenever you upgrade a provider.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how each dependency is listed with its version, which is the same kind of record a lock file keeps for providers.
Quick check
Does this command install providers?
No. It updates the lock file without initializing the referenced providers.
Do I need it if I only use the public registry on one platform?
Usually not, since terraform init records what you installed. It becomes useful when you add platforms or a mirror.
Does the lock file cover modules?
No. At present the lock file tracks provider dependencies only, so pin remote module versions separately.
Safeguard offers SBOM and dependency scanning and policy gates that can block a pull request on findings, and you can try a free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
