What are Terraform Lock Files

What are the Terraform lock files?

A Terraform lock file is a dependency lock file for Terraform providers. It showed up in Terraform 0.14, and its job is to lock the exact provider versions a configuration uses so they stay consistent across different environments and team members.

Think of it like a package-lock.json file in a Node.js project or a Gemfile.lock in a Ruby project. When you run terraform init, Terraform downloads the providers and modules you need, then records the exact provider versions and checksums in the .terraform.lock.hcl file. Modules aren't recorded, so use an exact version constraint on a module block if you need it fixed.

Terraform creates and updates this file itself. Don't edit it by hand.

Why is it important?

The main thing a Terraform lock file gives you is consistency, and that pays off in three ways:

• Prevents unexpected changes: Without a lock file, Terraform might download a newer, potentially incompatible version of a provider when a teammate runs terraform init. You end up with a configuration that works on one machine and fails on another, the classic "it works on my machine" problem. With the lock file, everyone uses the same tested versions.
• Ensures reproducibility: The lock file makes your infrastructure deployments reproducible. You can always revert to a previous state and know the exact same provider versions will be used, so a new provider release won't surprise you with breaking changes.
• Enhances collaboration: On a team, commit the lock file to version control (like Git). It acts as a contract: every team member and your CI/CD pipeline use the exact same provider versions, so nobody drifts onto a different release.

How to use the Terraform lock file

Terraform handles most of the work for you.

1. Initialize: The first time you run terraform init, Terraform downloads the providers and modules and creates the .terraform.lock.hcl file.
2. Version control: Commit the .terraform.lock.hcl file to your version control system (e.g., Git). This is the most critical step.
3. Collaborate: When another team member clones the repository and runs terraform init, Terraform uses the versions in the lock file, even if newer versions of the providers are available.

The lock file can also cause headaches, especially on a team or across operating systems. These are the problems you're most likely to hit.

Common issues with Terraform lock files

Checksum mismatch errors

This is arguably the most frequent problem. The error message typically says something like: "the current package… doesn't match any of the checksums previously recorded in the dependency lock file."

• Cause: This usually happens when the lock file was created on one operating system (e.g., macOS) and then used on a different one (e.g., Linux in a CI/CD pipeline). Provider binaries have different checksums on different platforms, and your lock file might only have the checksum for the platform it was first generated on.
• Resolution: Update the lock file so it includes checksums for every platform you'll use. The easiest way is to run terraform providers lock and name the platforms. For example, terraform providers lock -platform=linux_amd64 -platform=darwin_amd64. Then commit the updated lock file to your repository.

Stale lock files

A stale lock file occurs when you've updated the version constraints for a provider in your code (e.g., from ~> 3.0 to ~> 4.0), but the lock file hasn't been updated to reflect the new version.

• Cause: This happens if you change your provider version constraints but don't run terraform init -upgrade, or you forget to commit the changes to the lock file. Your CI/CD pipeline can then fail because it's trying to use an outdated lock file with a new configuration.
• Resolution: Run terraform init -upgrade. This command tells Terraform to ignore the existing lock file, find the newest provider versions that match your constraints, and write the new selections and checksums into the lock file. Then commit the updated .terraform.lock.hcl file.

Merge conflicts

In a team setting, two developers might independently update provider versions and create a merge conflict in the .terraform.lock.hcl file.

• Cause: Developer A updates a provider and commits the new lock file. At the same time, Developer B updates a different provider and also commits their changes. When they try to merge, Git detects a conflict because the lock file has been modified in both branches.
• Resolution: You handle this like any other merge conflict, resolving it by hand in the lock file. The safest approach is to accept both sets of changes so all the provider blocks and their checksums are present. Then run terraform init again to confirm every checksum is still valid and the file is in good shape.

You can prevent most of these issues with good team habits: always commit the lock file, and be deliberate about when and how you upgrade provider versions.

Beyond a single repository

Commit .terraform.lock.hcl to version control, and everyone on your team, plus your automation, works with the same tested provider versions.

Lock files pin versions per repository; they don't tell you which provider versions run across your whole estate. At team scale, module and provider reports answer that question. Scalr builds them in, and pricing is free up to 50 runs per month.