Q: What is the `.terraform.lock.hcl` file and should you commit it?
The .terraform.lock.hcl file is Terraform's dependency lock file: it records the exact provider versions and package checksums selected by terraform init, and yes, you should commit it to version control.
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: The <code>.terraform.lock.hcl</code> file is Terraform's dependency lock file: it records the exact provider versions and package checksums selected by <code>terraform init</code>, and yes, you should commit it to version control. Interviewers ask because an uncommitted lock file means every laptop and CI runner can resolve a different provider version inside the same <code>version</code> constraint, which turns a routine plan into a surprise diff. A strong answer explains what the file contains, what it does not cover (modules), how hashes interact with multiple platforms, and how to upgrade deliberately through a reviewed pull request.
What the .terraform.lock.hcl file records
Think of it as a package-lock for providers: constraints say what is allowed, the lock file says what was chosen.
# .terraform.lock.hcl (generated, do not hand-edit)
provider "registry.terraform.io/hashicorp/aws" {
version = "5.31.0"
constraints = "~> 5.0"
hashes = [
"h1:...",
"zh:...",
]
}
- Contents: one
providerblock per provider with the selectedversion, the originalconstraints, and a set ofhashes(h1:andzh:entries) used to verify the downloaded package. - Created by:
terraform initwhen no entry exists for a provider. Later runs reuse the recorded version as long as it still satisfies the configuration. - Constraints vs lock:
version = "~> 5.0"inrequired_providerspermits many releases; the lock file pins exactly one of them until you ask for an upgrade. - Not covered: modules are not locked by this file. Pin them with an explicit
versionargument for registry modules or a git ref for git sources.
Hands-on: should you commit the .terraform.lock.hcl file
Commit it to the root module directory alongside your .tf files, and keep the .terraform/ directory ignored.
# first-time setup
terraform init
git add .terraform.lock.hcl
git commit -m "Pin provider selections"
# confirm it is tracked and not ignored
git check-ignore -v .terraform.lock.hcl || echo "not ignored: good"
git ls-files .terraform.lock.hcl
- Commit: check that
.gitignorecontains.terraform/but not.terraform.lock.hcl. Many generic Terraform gitignore templates were historically wrong about this. - Why: it gives reproducible provider selection across developers, CI and production applies, and it detects a tampered or substituted provider package through checksum mismatch.
- Review it: a lock file change in a pull request is a provider upgrade. Reviewers should read the release notes, not just the hash noise.
- Reusable modules: a child module that is never run on its own does not need its own lock file; the root module that runs
initowns it.
Upgrading providers and covering every platform
Upgrades are explicit, and the file must carry hashes for every OS and architecture that runs Terraform.
terraform init -upgrade
terraform providers lock \
-platform=linux_amd64 \
-platform=linux_arm64 \
-platform=darwin_arm64
# CI: refuse to modify the lock file
terraform init -lockfile=readonly
- Upgrade deliberately:
terraform init -upgradere-resolves versions within your constraints and rewrites the lock file; commit the result in its own PR. - Multi-platform hashes: if developers use macOS arm64 and CI uses Linux amd64, run
terraform providers lockwith every-platformso the file holds hashes for all of them. - Read-only in CI:
terraform init -lockfile=readonlyfails if init would need to change the lock file, which catches a forgotten commit. - Inspect:
terraform providersshows which providers each module requires andterraform versionlists the selected versions.
Failure modes and how to fix them
Most lock file incidents are checksum mismatches or constraints that no longer match the recorded version.
- Checksum mismatch: the error says the package "doesn't match any of the checksums previously recorded in the dependency lock file". It usually means the file only holds hashes for another platform; regenerate with
terraform providers lockfor all platforms. - Constraint conflict: if you raise the constraint above the locked version,
initreports that the locked version does not match; runterraform init -upgrade. - Merge conflicts: resolve by picking one side, then re-running
init(orproviders lock) so the file is regenerated rather than hand-merged. - Mirrors: when using a provider mirror or private registry, hashes can differ from the public registry. Generate the lock file using the same installation source your CI uses.
- Hash types:
zh:hashes cover the zipped release package as published, whileh1:hashes cover the unpacked contents and work across mirrors, which is why both appear.
Automating lock file hygiene
Treat provider upgrades as a routine, reviewed dependency update.
- Automated PRs: Renovate and Dependabot can open pull requests that bump providers and refresh
.terraform.lock.hcl; confirm your tool regenerates hashes for all platforms you use. - Plan on the PR: run
terraform planin CI for the upgrade PR so provider behavior changes appear as a visible diff before merge. - Supply chain: checksum verification plus pinned versions reduces the risk of a different package being installed than the one you reviewed.
- The .terraform.lock.hcl file pins the exact provider versions and checksums chosen by terraform init, so it belongs in version control.
- I verify with git diff on the file and terraform providers, and run init with -lockfile=readonly in CI.
- I automate upgrades with Renovate or Dependabot PRs and refresh hashes for linux and darwin platforms.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Adding .terraform.lock.hcl to .gitignore Each machine then resolves its own provider version, and plan results differ between laptops and CI.
- Generating the lock file only on macOS It will lack hashes for linux_amd64, so the CI runner fails with a checksum mismatch.
- Deleting the lock file to clear an error Terraform will select the newest allowed provider and may introduce unreviewed behavior changes.
- Assuming the lock file pins modules It only covers providers; modules need their own version or git ref pinning.