terraform init: the first command in any project

What terraform init does

When you write provider "aws" { ... } in a file, Terraform cannot talk to AWS on its own. It needs a provider plugin, a separate program that knows how to speak to the AWS API.

terraform init does three things:

1. Reads the required_providers block in your code and checks which plugins are needed.
2. Downloads them from the Terraform Registry into a .terraform/ folder next to your code.
3. Creates a .terraform.lock.hcl file that pins the exact versions of the downloaded plugins along with their hashes. See tf-lockfile.

After init the directory is ready, and you can run plan and apply.

When to run it

You need to run init the first time after git clone of someone else's repository, or after creating a new project. Run it again if:

• required_providers changed in the code (a different provider or a different version).
• A backend block was added or changed (where state is stored, see tf-init-backends).
• A new module "..." block appeared.

If none of these changed, you do not need to run init again.

What shows up in the directory

After the first init:

your-project/

├── main.tf                      # your code

├── .terraform/                  # appeared after init

│   └── providers/

│       └── registry.terraform.io/

│           └── hashicorp/

│               └── aws/

│                   └── 5.60.0/

│                       └── linux_amd64/

│                           └── terraform-provider-aws_v5.60.0_x5

└── .terraform.lock.hcl          # also appeared

Important:

• .terraform/ is a cache. Add it to .gitignore and do not commit it.
• .terraform.lock.hcl is the opposite: always commit it. It guarantees that your teammates download the same provider versions.

Useful flags

• terraform init -upgrade updates providers to the latest versions within the version constraint. If the code says version = "~> 5.0", then -upgrade moves you from 5.50 to 5.60, but not to 6.x.
• terraform init -reconfigure reinitializes from scratch. You need it when you have changed the backend settings and Terraform asks whether to migrate state.
• terraform init -input=false skips interactive questions. This is the mode for CI/CD.

Pitfalls

• init does not work offline. Plugins are downloaded from registry.terraform.io. Corporate networks sometimes set up a mirror through terraform { provider_installation { ... } } in ~/.terraformrc, see tf-cli-config.
• Corporate proxy. If your backend is in the office and the internet is reachable only through a proxy, you need to set the HTTPS_PROXY and HTTP_PROXY variables before running.
• The lockfile blocks the upgrade. If init complains "requested version is not the locked version", it means the lockfile holds one version while you want another. The fix is either init -upgrade or an explicit change to the constraint.
• The cache in .terraform/ depends on the OS. If a teammate works on macOS and you work on Linux, you cannot just copy .terraform/ over; each person runs init locally.

What is inside .terraform.lock.hcl

A small file that looks roughly like this:

provider "registry.terraform.io/hashicorp/aws" {

  version     = "5.60.0"

  constraints = "~> 5.60"

  hashes = [

    "h1:abc123...",

    "h1:def456...",

  ]

}

This is what makes runs reproducible: the next init installs exactly version 5.60.0 with exactly these hashes. If the hashes do not match, init fails. This protects you against tampered packages.