terraform init: Usage, Options & Common CI Errors

The first command every Terraform run needs - initialize providers, modules, and the backend.

terraform init prepares a working directory: it downloads providers, installs modules, and configures the backend. It is the first command you run, and the one CI fails on most.

What it does

terraform init initializes a working directory containing Terraform configuration. It installs the providers listed in required_providers, downloads child modules, configures the backend for state storage, and writes a dependency lock file (.terraform.lock.hcl). It is safe to run multiple times and is required before plan or apply.

Common usage

# Standard init
terraform init

# Reconfigure the backend (e.g. new bucket) without migrating state
terraform init -reconfigure

# Pass backend settings from CI instead of hardcoding them
terraform init -backend-config="bucket=my-tfstate" -backend-config="key=prod/terraform.tfstate"

# Upgrade providers/modules to newest allowed versions and refresh the lock file
terraform init -upgrade

# CI: fail instead of prompting, and lock provider checksums for linux
terraform init -input=false -lockfile=readonly

Common error in CI: missing provider hash for linux

On macOS-developed configs run in Linux CI you often hit: "Error: Inconsistent dependency lock file ... the cached package ... does not match any of the checksums recorded in the dependency lock file". The lock file only recorded checksums for your local platform. Fix: regenerate the lock for all CI platforms with terraform providers lock -platform=linux_amd64 -platform=darwin_arm64, commit .terraform.lock.hcl, then run terraform init. Avoid -upgrade in CI unless you intend to bump versions.

Key options

Related guides