Should .terraform.lock.hcl be included in the .gitignore file?

Explore what the .terraform.lock.hcl file is and if you should include it in your version control environment.

Should .terraform.lock.hcl be included in the .gitignore file?
Should .terraform.lock.hcl be included in the .gitignore file?

Welcome to this blog post where we delve into the intricacies of Terraform and discuss a crucial aspect of managing Terraform projects: the .terraform.lock.hcl file. 

In this article, we'll explore what exactly the .terraform.lock.hcl file is, its significance in Terraform projects, and the debate surrounding whether or not you should commit it to your version control repository. 

Join us as we unravel the importance of this file and its impact on your Infrastructure as Code(IaC) workflow.

What is the .terraform.lock.hcl file?

According to the official Terraform documentation the .terraform.lock.hcl file is: 

Terraform automatically creates or updates the dependency lock file each time you run the terraform init command. You should include this file in your version control repository so that you can discuss potential changes to your external dependencies via code review, just as you would discuss potential changes to your configuration itself.

So let’s dive into that a bit more and explain it. When you're using Terraform and you run terraform init, it's basically setting up everything you need for your project, like installing different pieces that help make your project work. 

Now, here's where it gets interesting: Terraform wants to make sure it's using the right versions of those pieces, so it checks two things. 

First, it looks at what versions you've said you want to use in your project. 

Then, it checks this file called .terraform.lock.hcl, which keeps track of the specific versions Terraform has used before.

Now, if Terraform hasn't used a specific version of something before, it'll pick the newest version that fits what you've said you need and then remember to use that version in the future by updating the lock file. 

But if Terraform has used a version before and it's recorded in the lock file, it'll stick with that version, even if there's a newer one available. 

You can change this behaviour though if you want by using a special command when you run terraform init.

Should you include .terraform.lock.hcl in your .gitignore file?

Now, it’s important to remember the .gitignore file is a list of things you don’t want to include when you are saving your project into your version control environment. 

So, should you include the .terraform.lock.hcl file in your .gitignore configuration?

Well, it depends. 

Ignoring it means it won't get copied from your computer to your version control environment when you save your project. 

But remember, the .terraform.lock.hcl file is crucial for Terraform to work smoothly and consistently across different computers or environments.

So, here's the deal: If you're working with a team or want to make sure everyone's using the same versions of software, it's best to include the .terraform.lock.hcl file in your version control. It helps keep things consistent and avoids unexpected surprises when someone else tries to use your Terraform project.

But if you're working solo and you're okay with managing the versions yourself, then sure, you can ignore it. 

Just be aware that you might run into compatibility issues down the road.


In conclusion, the .terraform.lock.hcl file plays a crucial role in maintaining consistency and stability within your Terraform projects. 

While including it in your version control repository ensures uniformity, especially in team environments, solo developers may opt to manage versions manually. 

Ultimately, understanding the significance of this file empowers you to make informed decisions that align with your project's needs and workflow.