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.hclto pin provider versions and checksums.
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.
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.
.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:
- Backend initialization (where Terraform state will be stored).
- Provider discovery and installation (including versions and signatures).
- Creation of
.terraform.lock.hcland successful initialization.
When to re-run terraform init (quick reference)
| Trigger | Why re-run terraform init? | Recommended action |
|---|---|---|
| New project | No provider or module cache exists locally | Run terraform init once in the project directory |
| Added or removed providers | Provider binaries need to be downloaded/removed | Run terraform init to update plugins |
| Changed module source or versions | Terraform must fetch fresh module code | Run terraform init to download new modules |
| Changed backend configuration | Terraform must reconfigure the state backend | Run terraform init to reinitialize the backend |
| CI pipeline run | Ensure deterministic provider selection | Run terraform init -input=false in CI |
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:
| Item | Description | Commit to VCS? |
|---|---|---|
plugins / providers | Cached provider binaries used to communicate with cloud APIs | No |
modules | Downloaded copies of modules referenced by your configuration | No |
| backend/plugin metadata | Internal metadata used by Terraform during operations | No |
.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.
.terraform directory and run terraform init again to rebuild the cache.
Do not commit the
.terraform directory. Treat it as a local cache that can be deleted and recreated with terraform init.Summary
- Run
terraform initat the start of a project and whenever providers, modules, or backend configuration change. terraform initdownloads providers and modules, configures the backend, creates/updates.terraform.lock.hcl, and populates the.terraformdirectory.- Commit
.terraform.lock.hclto version control to ensure consistent provider versions across environments. - Do not commit
.terraform; add it to.gitignoreand recreate it withterraform initif needed.