Skip to main content
terraform init is the first command you run in any new Terraform project. It initializes your working directory by downloading providers and modules, configuring your backend, and creating local caches so subsequent commands such as terraform plan and terraform apply can run. In this guide you’ll learn:
  • What terraform init does under the hood
  • When to run it
  • Which files and directories it creates and how you should manage them
For the official reference, see the Terraform docs: https://developer.hashicorp.com/terraform/cli/commands/init

​
What terraform init does

The main responsibilities of terraform init can be summarized as:

​
When to run terraform init

Run terraform init:
  • At the start of any new project — it’s the first Terraform command to run.
  • After changing providers, modules, or backend configuration.
  • After upgrading provider versions in your configuration.
Example: initialize the directory
If you update a provider version (for example from v6.0 to v6.5), rerun terraform init to download and install the updated provider; unaffected providers will be left in place.

​
The dependency lock file

Every time you run terraform init, Terraform creates or updates the .terraform.lock.hcl file in your working directory. This lock file stabilizes provider selections so every contributor uses consistent provider binaries and versions.
  • File name: .terraform.lock.hcl
  • Location: the working directory (next to your .tf files)
  • Best practice: commit the lock file to version control
Commit .terraform.lock.hcl to version control so your team can review provider version changes during code review. Terraform manages this file automatically; you do not need to edit it manually.
Sample terminal output from terraform init

​
What happens with providers

  • Terraform downloads each provider referenced in your configuration and installs the provider binaries into the local .terraform directory.
  • Provider versions are recorded in .terraform.lock.hcl so builds are reproducible across machines and CI.
  • Binaries are platform-specific; Terraform stores the appropriate binary for your OS and architecture.

​
The .terraform directory

Running terraform init creates a .terraform directory in your working directory. It is a local cache that contains everything Terraform needs to run locally. Common contents:
  • .terraform/providers — cached provider binaries and metadata
  • .terraform/modules — downloaded module source code referenced by your configuration
A purple infographic slide titled "The .terraform Directory" showing a folder tree (Working Directory → .terraform → providers and modules) and brief notes explaining that .terraform stores cached providers and downloaded modules. The left side has simple folder icons and the right side lists descriptions of the providers and modules directories.

​
Important questions about the .terraform directory

  1. Should the .terraform directory be committed to version control?
  • No — add .terraform to .gitignore.
  • It’s a local cache of reproducible files that terraform init can rebuild.
  • Provider binaries can be large and are platform-specific; committing them offers no advantage.
Do not commit the .terraform directory. Instead, commit .terraform.lock.hcl and your Terraform configuration files.
  1. Can you delete the .terraform directory?
  • Yes. It’s safe to delete.
  • After deletion, rerun terraform init to re-download providers and modules.
  • Deleting the directory is a common troubleshooting step when caches are corrupted or you need a clean rebuild.

​
Quick reference: commit vs ignore

​
Summary

  • Run terraform init at the start of a project and whenever providers, modules, or backend settings change.
  • terraform init downloads providers and modules, sets up the backend, creates the .terraform directory, and writes .terraform.lock.hcl.
  • Commit .terraform.lock.hcl to version control; do not commit the .terraform directory.
  • If cached files look corrupted or you want a clean start, delete .terraform and re-run terraform init.
If you want to dive deeper into terraform init internals and workflows, continue reading for a more detailed exploration.
A purple slide titled "Working with the .terraform Directory" showing two panels numbered 01 and 02. The left panel advises not to put the .terraform directory in version control, and the right panel says you can delete it and recreate it (e.g., with terraform init).

Watch Video