Terraform Tutorial — terraform init

terraform init is the first command you run in any Terraform project. It initializes the working directory by downloading providers, configuring the backend, and installing modules.

---

What init Does

$ terraform init
Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/aws versions matching "~> 5.0"...
- Installing hashicorp/aws v5.31.0...
- Installed hashicorp/aws v5.31.0 (signed by HashiCorp)

Terraform has been successfully initialized!

Step	What Happens
Backend initialization	Configures where state is stored (local, S3, etc.)
Provider download	Downloads provider plugins to .terraform/providers/
Module installation	Downloads modules to .terraform/modules/
Lock file creation	Creates .terraform.lock.hcl with provider checksums

---

The .terraform Directory

After init, a .terraform/ directory is created:

.terraform/
├── providers/
│   └── registry.terraform.io/
│       └── hashicorp/
│           └── aws/
│               └── 5.31.0/
│                   └── darwin_arm64/
│                       └── terraform-provider-aws_v5.31.0
└── modules/
    └── modules.json

💡 Tip: Add .terraform/ to .gitignore. It’s local to your machine and can be regenerated with terraform init.

---

The Lock File

.terraform.lock.hcl records exact provider versions and checksums:

provider "registry.terraform.io/hashicorp/aws" {
  version     = "5.31.0"
  constraints = "~> 5.0"
  hashes = [
    "h1:abc123...",
  ]
}

Commit this file to Git. It ensures everyone uses the same provider versions.

---

Common init Flags

# Reconfigure backend (e.g., switching from local to S3)
$ terraform init -reconfigure

# Migrate state to a new backend
$ terraform init -migrate-state

# Upgrade providers to latest matching version
$ terraform init -upgrade

# Don't download providers (use cached)
$ terraform init -plugin-dir=/path/to/plugins

---

When to Re-run init

Scenario	Run init?
First time in a project	✅ Yes
Added a new provider	✅ Yes
Added a new module	✅ Yes
Changed backend configuration	✅ Yes (with -reconfigure)
Changed a variable value	❌ No
Modified a resource	❌ No

---

What’s Next?

You’ve initialized your project. Let’s preview changes with terraform plan.

---

← Workflow Hub terraform plan →