What Is Terraform Init?
Terraform init is the setup command. Before Terraform can do anything — plan, apply, or even validate — it needs to download the provider plugins your configuration requires and set up the backend where state will be stored. Init does all of this in one command.
Think of it like npm install. Your package.json declares dependencies; npm install downloads them. Your required_providers block declares providers; terraform init downloads them.
Running Terraform Init
# Basic init — downloads providers, configures backend, installs modulesterraform init # Upgrade providers to latest allowed version (respects version constraints)terraform init -upgrade # Reinitialise without migrating state (when backend config changes)terraform init -reconfigure # Migrate state from old backend to new backendterraform init -migrate-stateWhat Init Does — Step by Step
+------------------------------------------+| 1. Read required_providers block || Finds: hashicorp/aws ~> 5.0 |+------------------------------------------+ | v+------------------------------------------+| 2. Download provider plugins || From: registry.terraform.io || To: .terraform/providers/ |+------------------------------------------+ | v+------------------------------------------+| 3. Configure backend || Sets up S3 remote state connection |+------------------------------------------+ | v+------------------------------------------+| 4. Install modules || Downloads any modules from source |+------------------------------------------+ | v+------------------------------------------+| 5. Write .terraform.lock.hcl || Locks exact provider versions + hashes |+------------------------------------------+The .terraform Directory
.terraform/ providers/ registry.terraform.io/ hashicorp/ aws/ 5.31.0/ linux_amd64/ terraform-provider-aws_v5.31.0_x5 # binary plugin modules/ vpc/ # downloaded module source terraform.tfstate # backend config cache# This directory should ALWAYS be in .gitignoreecho ".terraform/" >> .gitignoreThe Lock File
# .terraform.lock.hcl — commit this to Git# Records the exact provider version and platform hashesprovider "registry.terraform.io/hashicorp/aws" { version = "5.31.0" constraints = "~> 5.0" hashes = [ "h1:abc123...", # hash for linux_amd64 "h1:def456...", # hash for darwin_arm64 ]}REMEMBER THIS**Remember:** Commit `.terraform.lock.hcl` to Git. This file ensures every engineer and CI/CD pipeline downloads the exact same provider version with verified hashes. Without it, a provider upgrade could silently change behaviour for one engineer but not another.
When to Re-run Init
# Always re-run init after:# 1. Adding or changing a provider# 2. Adding or changing a module source# 3. Changing the backend configuration# 4. Cloning the repo fresh on a new machine# 5. Changing the required Terraform versionInit in CI/CD
# GitHub Actions example- name: Terraform Init run: terraform init env: AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} # Or with OIDC (preferred — no long-lived keys)- name: Configure AWS credentials uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: arn:aws:iam::123456789012:role/terraform-ci aws-region: ap-south-1 - name: Terraform Init run: terraform initTroubleshooting Init
| Error | Cause | Fix |
|---|---|---|
Failed to query available provider packages |
Network issue or registry down | Check internet connection; use -plugin-dir offline |
Error: Failed to install provider |
Disk full or permissions issue | Check df -h and directory write permissions |
The argument -reconfigure is deprecated |
Old Terraform version | Upgrade Terraform |
Inconsistent dependency lock file |
Lock file out of sync with providers block | Run terraform init -upgrade |
Backend configuration changed |
Modified backend block | Run terraform init -reconfigure |
COMMON MISTAKE / WARNING**Common Mistake:** Running `terraform plan` or `terraform apply` in a freshly cloned repo without running `terraform init` first. Terraform will error immediately: `Error: Required plugins are not installed`. Always run `terraform init` first in any new directory or after any CI/CD clone.