Terraform Dependency Lock File — Complete Guide (.terraform.lock.hcl)
If you're managing infrastructure as code, the .terraform.lock.hcl file is your single source of truth for provider versions. Learn how to generate, update, commit, and troubleshoot lock files to keep your pipeline secure and deterministic.
The Terraform dependency lock file (.terraform.lock.hcl) records the exact versions and checksums of Terraform providers used in your project. You should always commit this file to Git. To update it, run terraform init -upgrade. To fix an "inconsistent dependency lock file" error, delete the file and re-run terraform init.
Table of Contents
- What is the Terraform Dependency Lock File?
- Should You Commit .terraform.lock.hcl to Git?
- Update Terraform Lock File — Step-by-Step
- Fix Terraform Inconsistent Dependency Lock File
- Terraform State Lock vs Dependency Lock File
- Why We Recommend Folder Lock for Devs
- Digital Privacy & OS History Cleaning
- Troubleshooting Git Config Lock Errors
- Frequently Asked Questions
What is .terraform.lock.hcl and Why Does It Matter?
When you run terraform init, Terraform downloads the plugins (providers like AWS, Azure, Google) required by your configuration. To ensure that everyone on your team—and your CI/CD pipeline—uses the exact same provider versions, Terraform generates a Terraform dependency lock file named .terraform.lock.hcl.
This file works exactly like node_modules/.package-lock.json in npm or a poetry.lock file in Python. It locks down the specific versions and cryptographic checksums of your providers.
By default, Terraform will refuse to apply changes if the downloaded provider checksums do not match the hashes recorded in the lock file. This prevents supply chain attacks and guarantees reproducible builds.
Common Lock File Scenarios
Starting a New Project
When you add your first terraform {} block and run init, Terraform creates the lock file from scratch. It calculates the hashes for your current OS platform.
Upgrading a Provider
When an AWS or Azure provider releases a new feature, you must explicitly tell the lock file to upgrade using the -upgrade flag.
Multi-Platform CI/CD
If you develop on macOS but deploy via Linux CI runners, you must populate the lock file with checksums for both platforms.
Corrupted Dependencies
When a developer manually edits the lock file or merges conflicts poorly, Terraform throws an inconsistent dependency error requiring regeneration.
Update Terraform Lock File — Step-by-Step
Managing the lock file correctly is critical. Here are the primary commands every DevOps engineer needs.
1. How to Generate the Terraform Lock File
If the file does not exist, simply initialize the working directory. Terraform will read your `.tf` files, find the required providers, download them, and generate the lock file.
terraform init2. How to Update the Lock File
If you want to update your providers to the newest versions allowed by your version constraints (e.g., ~> 4.0), you must force Terraform to ignore the existing lock.
terraform init -upgrade3. Terraform Lock File for Multi-Platform Environments
By default, terraform init only captures the checksum for your local operating system (e.g., `darwin_arm64` for Mac M1). If your CI/CD pipeline runs on Linux, it will fail. You must generate platform-specific checksums.
terraform providers lock -platform=darwin_arm64 -platform=linux_amd64 -platform=windows_amd64
Should You Commit .terraform.lock.hcl to Git?
Yes. You should always commit the .terraform.lock.hcl file to your version control system (Git).
Committing the lock file ensures that your CI/CD runners, your co-workers, and your future self are all executing Terraform plans against the exact same provider binaries. Ignoring the lock file in your .gitignore defeats its entire purpose.
Terraform State Lock vs Dependency Lock File
It is incredibly common to confuse the dependency lock file with the state lock. They serve two entirely different security and stability purposes in Terraform.
| Feature | Dependency Lock (.terraform.lock.hcl) | State Lock (DynamoDB / Local) |
|---|---|---|
| What does it lock? | Provider versions (AWS, Azure plugins) | The actual `.tfstate` file during execution |
| Why is it needed? | Ensures reproducible environments | Prevents two people from deploying at the same time and corrupting state |
| Where does it live? | In your local repo, committed to Git | In a remote backend (e.g., AWS DynamoDB) or locally on disk via `.terraform.tfstate.lock.info` |
| How to resolve errors? | terraform init -upgrade or delete file |
terraform force-unlock [ID] |
Securing Your Local Dev Environment
While .terraform.lock.hcl secures your provider dependencies, your local workspace contains something much more dangerous: the local Terraform state file (.tfstate) and environment variable files (.env).
Even if you utilize remote state management, developers frequently pull states down locally to debug, leaving AWS access keys, database credentials, and infrastructure schematics sitting in plain text. If a machine is compromised, or a malicious script runs, that entire infrastructure is at risk.
For local configuration protection, we recommend Folder Lock. Available across Windows, macOS, Android, and iOS, it allows developers to instantly encrypt and conceal specific project repositories. It ensures that local state files, API tokens, and `.git` config data remain completely inaccessible to unauthorized processes.
Folder Lock: Developer Toolkit
Powerful local security mechanisms designed for technical environments.
AES-256 On-the-Fly
Files are decrypted in memory, creating a virtual drive. Work seamlessly in VS Code without leaving decrypted footprints on your disk.
Kernel-Level Hiding
Conceal entire `.env` directories. The protection integrates at the OS level, meaning hidden configs stay invisible even if the system is booted into Safe Mode.
DOD-Standard Shredding
Deleting old `.tfvars` or `.pem` keys normally leaves them recoverable. Folder Lock overwrites the empty disk space to prevent forensic recovery.
Encrypted Cloud Sync
Safely back up your protected configuration vaults directly to Dropbox, Google Drive, or OneDrive while maintaining strict client-side encryption.
Fix Terraform Inconsistent Dependency Lock File Error
The most common error developers face is:
Error: Inconsistent dependency lock fileThis happens when the checksums in your `.terraform.lock.hcl` file do not match the checksums of the provider being downloaded. This usually occurs after a git merge conflict, or when someone manually modifies the lock file.
How to Remove and Regenerate the Lock File
The safest and most officially supported recovery path is to delete the lock file and regenerate it.
# Step 1: Remove the existing lock file
rm .terraform.lock.hcl
# Step 2: Clear local cached providers
rm -rf .terraform/
# Step 3: Re-initialize and generate a fresh lock file
terraform initRelated Error: could not lock config file .git/config
While dealing with lock files, developers frequently encounter Git lock errors, such as:
error: could not lock config file .git/config: Permission deniedOr: cannot lock ref git / a lock file already exists in the repository github desktop.
Cause: Git creates a temporary .lock file (e.g., index.lock or config.lock) when it performs an operation. If Git crashes or is interrupted, the lock file gets left behind, blocking all future operations.
Fix: Manually delete the orphaned lock file.
# Fix for config lock error:
rm .git/config.lock
# Fix for index lock error:
rm .git/index.lock
Advanced Configuration & Troubleshooting
If you are deploying infrastructure into an air-gapped environment (no internet access), you must move your provider binaries manually. Using Folder Lock's Portable Locker feature, you can bundle your `.terraform` directories, provider binaries, and `.flka` executable into an encrypted container on a USB drive. You can then plug the drive into the offline server and enter your password to extract the necessary Terraform dependencies without requiring a background installation of the software.
Similar to Terraform, Node.js uses node_modules/.package-lock.json to lock dependencies. If you need to regenerate it without installing dependencies, use: npm i --package-lock-only. To ignore it in git (not recommended for apps, only some libraries), add package-lock.json to your .gitignore.
This error typically occurs in Rust (Cargo) or Node.js environments when multiple processes try to access the build cache simultaneously. To resolve this, ensure you don't have multiple terminals running build commands concurrently. You can forcefully clear the cache (e.g., cargo clean) to remove the stale lock.
Digital Privacy & OS History Cleaning
As developers, we focus heavily on infrastructure security, but local digital hygiene is often overlooked. When executing commands, terminals and operating systems log extensive histories. A misplaced `terraform apply -var="password=secret"` command can sit in your bash history or Windows Run cache indefinitely.
Wiping the Digital Footprint
Beyond file encryption, robust security requires wiping execution trails. Tools like Folder Lock include a Clean History function that removes traces of computer activity, including Windows Temporary Files, Open/Save directory caches, Clipboard data, and Run/Search histories. Regularly clearing these caches ensures that temporary plaintext leaks of API tokens or infrastructure IDs cannot be recovered by forensic analysis or local malware.
Managing Credentials Securely
Rather than leaving database passwords or AWS keys scattered in unencrypted `.txt` notes on your desktop, leverage dedicated encrypted wallets. Folder Lock provides a specific Secrets management interface to securely store and categorize confidential text, bank details, and identity numbers using the same rigorous AES-256 encryption applied to your file system.
Folder Lock: Plans & Limitations
Folder Lock offers transparent, one-time pricing without ongoing subscriptions. Here is how the capabilities break down for technical users securing their local environments.
Free Trial
Essential local protection to test the workflow.
- 1 GB Max Locker Size
- Sync Across 2 Devices
- Mobile App Access
- Basic Secrets & Wallets
- No File Shredding
- No Portable Lockers
Full Version
Unrestricted encryption and data destruction tools.
- Unlimited Locker Size
- Sync Across 5 Devices
- Create Portable Executable Lockers
- Secure File & Drive Shredding
- Secure User File Sharing
- Clean OS History Footprints
Frequently Asked Questions
What is the .terraform.lock.hcl file?
It is a dependency lock file that records the exact versions and checksums of the providers (plugins) your Terraform configuration relies on, ensuring consistent runs across different machines.
How does Terraform use the lock file for provider versioning?
When you run terraform init, Terraform checks this file. If the downloaded provider binary's hash doesn't match the hash in the lock file, Terraform aborts the operation to prevent malicious or incompatible code from running.
How to handle .terraform.lock.hcl in CI/CD?
Always commit the lock file to source control. In your CI/CD pipeline, run a standard terraform init. If your CI runner uses a different OS than your dev machine, ensure you pre-populate the lock file with terraform providers lock -platform=....
What is the difference between Terraform state lock and dependency lock?
The dependency lock (.terraform.lock.hcl) tracks the versions of the plugins downloaded to run your code. The state lock is a mechanism (often via DynamoDB) that prevents two developers from running terraform apply simultaneously and corrupting the remote .tfstate file.
How to fix card locked on digital camera?
This physical "lock" is a small switch on the side of the SD card. Simply remove the SD card from the camera, slide the small toggle switch on the left edge up (towards the metal contacts) to unlock it, and reinsert it.
How to block digital purchases on amazon?
To prevent accidental digital purchases (like Kindle books or movies), log into Amazon, navigate to Account Settings > Voice Purchasing (to disable Alexa purchases) or set up Amazon Kids/Parental Controls to require a PIN for digital storefront transactions.
How to add a digital signature block in pdf for someone else to sign?
In Adobe Acrobat, go to Tools > Prepare Form. Select the "Digital Signature" tool from the toolbar and drag a box where you want the signature to go. Save the PDF and send it to the recipient; they will be able to click that block to apply their certificate.