Skip to main content
Let’s walk through terraform init — the first command you run in any new Terraform project. It prepares your working directory so Terraform can download required providers, fetch modules, and configure the backend. After terraform init you can run terraform plan and terraform apply reliably. In this article you’ll learn what terraform init does, when to run it, and the files and directories it creates and manages.

​
What terraform init does

terraform init sets up the working environment by:
  • Downloading provider plugins referenced in your configuration (for example, AWS, Azure, GCP).
  • Fetching referenced modules from the Terraform Registry, Git, or other sources.
  • Configuring the backend where the Terraform state is stored (local or remote backends such as S3, Azure Storage, etc.).
  • Creating or updating the dependency lock file .terraform.lock.hcl to pin provider versions and checksums.
Think of terraform init as the foundation step — Terraform ensures all dependencies are available locally before any planning or applying occurs. The command is incremental: if you update a single provider, Terraform downloads only the changed provider and leaves other cached providers intact. When to run terraform init:
  • At the start of a new Terraform project.
  • After adding, removing, or upgrading providers or modules.
  • After changing backend settings.
  • Any time you want to refresh locally cached dependencies.
The image explains the Terraform lock file, highlighting its creation during terraform init, its purpose for locking dependency versions, its storage location, and best practices for version control.
Commit .terraform.lock.hcl to version control. It pins provider versions and checksums so every team member and CI run uses the same provider binaries, preventing “works on my machine” issues.

​
The lock file: .terraform.lock.hcl

Each run of terraform init will create or update a .terraform.lock.hcl file in your working directory (the same folder as your *.tf files). This lock file:
  • Records provider versions and checksums selected during initialization.
  • Ensures consistent provider selection across machines and CI runs.
  • Is managed automatically by Terraform — do not edit it manually.
Best practice: include .terraform.lock.hcl in your repository so provider selection changes are visible in code reviews.

​
Example output from terraform init

Typical output from terraform init shows backend initialization, provider discovery and installation, and confirmation of the lock file creation. Example:
This output highlights:
  • Backend initialization (where Terraform state will be stored).
  • Provider discovery and installation (including versions and signatures).
  • Creation of .terraform.lock.hcl and successful initialization.

​
When to re-run terraform init (quick reference)

​
The .terraform directory

Running terraform init creates a local .terraform directory in your working directory. This is Terraform’s local cache and contains provider binaries and downloaded modules. Common contents of .terraform:
The image explains the structure of the .terraform directory used by Terraform, highlighting the organization of providers and modules within a working directory.
Terraform manages everything inside .terraform. Do not manually edit these files; Terraform will recreate or update them when needed.

​
Version control and .terraform

Should you commit the .terraform directory to version control? No — add it to .gitignore instead. Reasons to ignore .terraform:
  • The directory is a cache of files that can be recreated by running terraform init.
  • Provider binaries are large and platform-specific (different OS/architecture).
  • Committing it introduces noise and potential merge conflicts.
If cached providers or modules become corrupted or inconsistent, delete the .terraform directory and run terraform init again to rebuild the cache.
The image provides guidance on handling the .terraform directory, advising not to include it in version control and noting it can be deleted and recreated with terraform init.
Do not commit the .terraform directory. Treat it as a local cache that can be deleted and recreated with terraform init.

​
Summary

  • Run terraform init at the start of a project and whenever providers, modules, or backend configuration change.
  • terraform init downloads providers and modules, configures the backend, creates/updates .terraform.lock.hcl, and populates the .terraform directory.
  • Commit .terraform.lock.hcl to version control to ensure consistent provider versions across environments.
  • Do not commit .terraform; add it to .gitignore and recreate it with terraform init if needed.

Watch Video