Q: What is `terraform providers lock`?
terraform providers lock is a command that records provider checksums for the platforms you choose in .terraform.lock.hcl, without needing to run on each platform.
Want to master this scenario in a live sandbox? KodeKloud's HashiCorp Certified Terraform Associate (003) Interactive Labs covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: <strong><code>terraform providers lock</code></strong> is a command that records provider checksums for the platforms you choose in <code>.terraform.lock.hcl</code>, without needing to run on each platform. By default <code>terraform init</code> only records hashes for the machine it runs on, so a lock file generated on a Mac can fail on a Linux CI runner. Interviewers ask this to test whether you understand supply-chain integrity, dependency locking and the classic <em>checksum does not match</em> error that appears when a team mixes laptops and pipelines.
Mental model: what the dependency lock file records
The lock file pins the exact provider version and a set of cryptographic hashes that must match any package Terraform installs later.
- Contents: each provider block lists
version, the versionconstraints, and ahasheslist containingh1:andzh:entries. - h1 hashes: computed from the unpacked provider package contents, specific to one platform build. zh hashes: checksums of the release zip archives published by the registry.
- Default behaviour:
terraform initrecords only hashes for the current platform, plus the archive hashes the registry publishes, so other platforms may be unverifiable. - Purpose: a compromised or altered provider build will fail the hash check, giving you a trust-on-first-use guarantee that is then reviewable in a pull request.
- Trust model: the first lock records what the registry served at that moment. It protects against later tampering, but it is not a signature check of the first download, which Terraform verifies separately through the registry's signing keys.
Hands-on: terraform providers lock for every platform
Run the command once, on any machine, and list every platform your team and runners use.
terraform init
terraform providers lock \
-platform=linux_amd64 \
-platform=linux_arm64 \
-platform=darwin_arm64 \
-platform=windows_amd64
git diff .terraform.lock.hcl # expect extra h1:/zh: lines only
git add .terraform.lock.hcl && git commit -m "Lock providers for all platforms"
- Platforms flag: use
-platform=OS_ARCHrepeatedly, for examplelinux_amd64,linux_arm64,darwin_arm64andwindows_amd64. - How it works: it contacts the registry (or a mirror), downloads each requested platform package, computes its hash, and adds it to the lock file.
- Mirrors:
-fs-mirror=DIRand-net-mirror=URLsource packages from a filesystem or network mirror, which matters for air-gapped environments. - Review the diff: a new run should only add hash lines. A changed
versionmeans you also upgraded the provider.
Troubleshooting: checksum does not match the lock file
The most common symptom is an init failure on a runner that differs from the machine that created the lock.
# CI failure
terraform init
# Error: Failed to install provider ... does not match any of the checksums
# Fix: add hashes for the runner platform, commit, re-run
terraform providers lock -platform=linux_amd64
- Error text: messages like the current package for registry.terraform.io/hashicorp/aws doesn't match any of the checksums previously recorded in the dependency lock file.
- Cause 1, missing platform: the lock was generated on
darwin_arm64and CI runslinux_amd64. Fix by runningproviders lockwith all platforms. - Cause 2, tampered or re-published build: investigate before overriding. Compare against the registry and avoid blindly deleting the lock file.
- Cause 3, mirror differences: a corporate mirror can produce different hashes; run the lock command against the same mirror CI uses.
Upgrading providers and enforcing read-only locks
Locking is only half the story; the other half is controlling when versions change.
# Dedicated upgrade PR
terraform init -upgrade
terraform providers lock -platform=linux_amd64 -platform=darwin_arm64
terraform plan
# In CI
terraform init -lockfile=readonly
- Deliberate upgrade:
terraform init -upgradepicks the newest version within your constraints and rewrites the lock file. Do this in a dedicated PR. - Read-only init in CI:
terraform init -lockfile=readonlymakes init fail if the lock file would need changes, preventing the pipeline from silently altering dependencies. - Constraints versus lock:
version = "~> 5.40"defines the allowed range, while the lock file picks the exact version inside it. Both must be committed. - After an upgrade: rerun
providers lockwith every platform so the new version has complete hashes.
Production practice: supply chain and automation
Treat provider updates as dependencies that need review.
- Automated updates: Renovate and Dependabot support Terraform and can open PRs that include lock file changes; ensure a job reruns
providers lockfor all platforms. - Private mirrors: use
provider_installationin the CLI config with a network mirror for restricted networks, then lock against that mirror. - Validation: add a CI step that runs
terraform providersto list requirements and fails if the lock file is absent. - Audit: review hash additions in PRs; unexpected new
versionlines deserve the same scrutiny as any dependency change. - Onboarding: document the supported platforms in the repo README next to the lock command, so a new engineer on a different architecture, such as Apple silicon, does not hit a mismatch.
- <code>terraform providers lock</code> pre-computes provider checksums for chosen platforms and writes them to <code>.terraform.lock.hcl</code>.
- I run it with linux and darwin platforms after upgrades, and diff the lock file to confirm only hashes were added.
- CI uses <code>-lockfile=readonly</code>, and Renovate opens version-bump PRs so provider changes are reviewed, not accidental.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Generating the lock file only with <code>terraform init</code> on a laptop It records hashes for that platform alone, so Linux runners hit checksum mismatch errors.
- Deleting <code>.terraform.lock.hcl</code> to make an error go away It discards the integrity guarantee and may pull a different provider version.
- Adding the lock file to <code>.gitignore</code> Every environment then resolves versions independently, which defeats locking.
- Running <code>init -upgrade</code> casually in CI It changes provider versions mid-pipeline; use <code>-lockfile=readonly</code> and upgrade in reviewed PRs.