The first time you run tofu init, OpenTofu® creates a file called .terraform.lock.hcl. It’s the dependency lock file: a record of the exact version of every provider the project uses, so every run, on every computer, uses the same ones.
This guide creates one, reads it line by line, and shows how OpenTofu uses it.
Prerequisites
- OpenTofu installed: How to Install OpenTofu on macOS.
- A terminal and an empty folder, such as
lock-file.
Step 1: Create the Lock File with tofu init
Create main.tf in the folder with this block, which uses the hashicorp/local provider:
terraform {
required_providers {
local = {
source = "hashicorp/local"
version = "~> 2.9"
}
}
}
Run tofu init:
tofu init
Initializing the backend...
Initializing provider plugins...
- Finding hashicorp/local versions matching "~> 2.9"...
- Installing hashicorp/local v2.9.1...
- Installed hashicorp/local v2.9.1 (signed, key ID 0C0AF313E5FD9F80)
Providers are signed by their developers.
If you'd like to know more about provider signing, you can read about it here:
https://opentofu.org/docs/cli/plugins/signing/
OpenTofu has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that OpenTofu can guarantee to make the same selections by default when
you run "tofu init" in the future.
OpenTofu has been successfully initialized!
The last paragraph says OpenTofu created .terraform.lock.hcl and asks you to keep it in version control.
Step 2: Read the Lock File
Open .terraform.lock.hcl in your editor:
# This file is maintained automatically by "tofu init".
# Manual edits may be lost in future updates.
provider "registry.opentofu.org/hashicorp/local" {
version = "2.9.1"
constraints = "~> 2.9"
hashes = [
"h1:0h5XUt+skYQCSCf+BHzPWHwaqVqo0I+6fasc7/9fP2Y=",
"h1:5Y/Fp+WG8q5OO7fbf832bKjGJtKwrUmo0dK3e87ByVM=",
"h1:9Ad43Ad5VA6HBc0qZVBQcCYZwuIvOAjhGOS+vUUUsKM=",
"h1:MQmy73iXTph9jzxSMXNCeOxKdhNHCnjlQvj19kcJ9UI=",
"h1:O+1x+SbVBhCnXLpYyyDlz1GYO5s22Qk+MZ37h9ofgqA=",
"h1:RJbX/jJDJSp8JnNFIHn2Icx6uE2lbxY77/gaVfLQWOU=",
"h1:XB4LDdYNfOISBFWdsj72LP1Edx6llgVNEArynhnP7Hs=",
"h1:Z2cj+Oz9b51lTth1MRf4p4b4XW9zzfHCrpMqmzfs9yA=",
"h1:aXGJwmTwNAsrEMyNe1DUY5my44zhFH3AQ9uYfx4T61c=",
"h1:ag5Jd1Iw2FlIy7/cvsKp4nZMNZdJc/yhRjfBwAwuOd8=",
"h1:cIB4bW/Jovmy+eslv7jJYXNkMur6NV4grhRCchN0czo=",
"h1:lr9uB3e97aIPJZssfrdPIZnoMw18zCNCBtQhrZuGQu4=",
"h1:thbp4t7UvMKA0AqyHPjTOaa9GmsfN8STUEAT/oxr+Tk=",
"h1:uaEPDxsry2ig8RfUIQY/nSxME8/2WN8LTucLSjSwwX0=",
"h1:zlsFtUpBP+sA7+uRyo5ZB/STOcU2/wwbIQ4ozgoctII=",
"zh:1127941790dbded1031144cd3617ecb44cdac28dbb4fd32b231f9b9f5f3c957c",
"zh:1418b8844bbf5ac941afa1ff2ec3e1c61f923a2777d8aa7ec4a6e6b8e66df57c",
"zh:20b7a42f13342dc542667b71b3fa5314e62eaf5f6a7f0a2750671fae28ad3614",
"zh:5f25e3e5e58d516e3c81ef1ba712bdab3a40e45028bbb62c7ec98659a6dab65f",
"zh:664e4988e9af6a1067081667ea0b8253bf73501fa4dc673be174a11ce30524e5",
"zh:6b1d932d6885898253ff7a9d359830203bb5050fc38347ad80f18ca4eef72b54",
"zh:73e545dec5d7360ae56a16296e7958fd38f41548393ed225c40800859a448f9c",
"zh:7edbfebc8787d096d5f16c478bf1b5648226b09935689547d57a361929522105",
"zh:81b99c2fa5264971769bf8ec45c7e40d64278279c6bac8dd985cd47e5696e77e",
"zh:89f4619b7159cff3b0791630bf71425781cce2eb5729b9bff60627448c66aa7a",
"zh:8f0a539b6887429a259949fc800bf4e9cbb97a2087847fcf551e5ce26095dd06",
"zh:a6b5f492526e3f55a3e2630fc53869617c32ff70cb77e4e41ec1f79bbfd910f4",
"zh:c36e59fd7814d3fcf33bb673149b14f4491bed4d441bd74bb419c82ae429cc6e",
"zh:dba1e69536bf91578b7b7b47cad79ac2cf8f24bf6b3cbff35d72378312eb3f2c",
"zh:e46d5aa5a69ca8a30e1d640f3999444b8ff896d9ab8c1e5ff88f9a430918886f",
]
}
The lock file that tofu init wrote for the hashicorp/local provider.- The comment at the top says
tofu initmaintains the file. Don’t edit it by hand. provider "registry.opentofu.org/hashicorp/local"is the provider’s full address on the OpenTofu Registry.versionis the versiontofu initselected.constraintsrepeats the version constraint frommain.tf.hashesare checksums of the provider’s packages. Theh1:andzh:prefixes are two checksum schemes. OpenTofu checks every package it installs against them and stops with an error if none match.
Step 3: Run tofu init Again
tofu init
Initializing provider plugins...
- Reusing previous version of hashicorp/local from the dependency lock file
- Using previously-installed hashicorp/local v2.9.1
OpenTofu has been successfully initialized!
Reusing previous version of hashicorp/local from the dependency lock file: OpenTofu took the version from the lock file instead of looking for a newer one. That’s what keeps every run the same. To move to a newer version on purpose, upgrade the provider with tofu init -upgrade.
Step 4: Commit It to Git
The OpenTofu docs ask you to include the lock file in version control, so changes to your providers are reviewed like changes to your code. The usual OpenTofu .gitignore leaves out the .terraform folder, but not this file.
Clean Up
Delete the lock-file folder. Nothing outside it was created.
FAQ
Why is it called terraform.lock.hcl in OpenTofu?
OpenTofu started as a fork of Terraform and kept its file names, so existing projects work unchanged.
Why does it end in .hcl instead of .tf?
It uses the same syntax as OpenTofu configuration, but it isn’t configuration. The .hcl ending marks the difference.
Should I delete it to get newer providers?
No. Run tofu init -upgrade instead: it selects the newest versions your constraints allow and updates the file.
Conclusion
.terraform.lock.hcl records which provider versions your project uses and their checksums. tofu init writes it, reuses it on every later run, and you commit it with your code.
Related
- OpenTofu Tutorial — Part 3: Providers: Run the Website in Docker
- OpenTofu Version Constraints Explained
- What Does tofu init Do in OpenTofu?
Additional Resources
- Dependency Lock File (opens in a new tab)
- Command: init (opens in a new tab)
- Version Constraints (opens in a new tab)
OpenTofu® is a registered trademark of LF Projects, LLC. Terraform and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by the OpenTofu project or HashiCorp.
0 comments