A beginner's guide to the terraform init command

The terraform init command is the first thing you run on a new or changed Terraform configuration, and nothing else works until it has. This post walks through what it actually does and how to use it well.

All of the commands below for Terraform also apply to OpenTofu. When using the command, replace terraform with tofu.

What is terraform init?

You run terraform init after writing new Terraform configuration files. It sets up a working directory that holds your configuration and gets it ready for Terraform to use.

After you run terraform init, the working directory will contain at least the following:

• A .terraform directory that contains the cached modules and providers that were initiated during terraform init.
• The Terraform state file, named terraform.tfstate. This only applies if Terraform is used without a remote backend. If a remote backend is used, like Scalr or HCP Terraform, the state file will be located in that backend.

Terraform init in the Terraform core pipeline

Every other Terraform command assumes init has already run. The usual sequence looks like this:

1. terraform init: Initialize the working directory
2. terraform plan: Preview changes before applying
3. terraform apply: Apply the proposed changes
4. terraform destroy: Tear down the created infrastructure

It is the first step, and the rest of the workflow depends on it.

What Does terraform init Do?

Terraform Providers

Providers are plugins that Terraform uses to manage resources. Running terraform init makes sure the right provider plugins get downloaded and installed. It checks the provider version in your configuration and pulls that version from the Terraform Registry or a custom provider source you point it at.

Example provider version specification:

Module Installation

If your Terraform configuration uses modules, considered a best practice, terraform init will download these modules and set them up in your working directory.

When you run terraform init, it will download the specified VPC module from the Terraform Registry for use in the run.

Backend Configuration

One of the main jobs of terraform init is to configure the backend. The backend decides where Terraform stores its state data files. By default, Terraform uses a local backend, which keeps the state on the local filesystem. But you can set up remote backends like Scalr, Terraform Cloud, Amazon S3, or Google Cloud Storage for better collaboration and security.

Example backend configuration in your Terraform code:

When you run terraform init, it performs backend initialization, setting up the specified backend and preparing it to store the state file.

State File

While terraform init doesn't create the state file (that happens when you first run terraform apply), it does set up the infrastructure for managing the state file. This includes configuring state locking mechanisms to prevent concurrent modifications when using a remote backend.

Verifying Configuration

The terraform init command also performs a basic check of your configuration files for syntax errors. While it doesn't catch all possible issues, it can identify obvious syntax problems, helping you catch errors early in the development process.

Advanced Commands

The terraform init command comes with a few advanced options. You might want to change backends, upgrade modules, or make changes to an existing backend:

• terraform init -reconfigure: The reconfigure command essentially starts the configuration from scratch by ignoring the working directory configuration and re-initializing the backend block.
• terraform init -migrate-state: The migrate-state command will migrate your state from one backend to another. For example, your state file might be local and you can use the migrate-state command to migrate it to a backend such as Scalr or Terraform Cloud.
• terraform init -upgrade: The upgrade command will ignore provider versions that are located in your lock file and upgrade your providers to the latest version depending on the constraints defined in your provider blocks.

Best Practices for Using terraform init

To use the terraform init command properly, consider these best practices:

1. Run terraform init after changes: Whenever you modify your backend configuration, add new providers, or update provider versions, re-run terraform init to ensure the changes take.
2. Version control your configuration: Store your Terraform configuration in version control, but exclude the .terraform directory created by terraform init.
3. Use consistent provider versions: Specify provider versions in your configuration to ensure consistency across different environments and team members. If versions are not pinned, terraform init will pull the latest.
4. Use remote backends: For teams, a remote backend such as Scalr or Terraform Cloud enables collaboration and maintains a single source of truth for your terraform infrastructure. If you are weighing where to point your backend, our guide to selecting a Terraform Cloud alternative compares the main managed options.

Where init fits in your workflow

The terraform init command sets up your working directory before any plan or apply can run. It downloads providers and modules, configures the backend, and does a basic check of your configuration.

Knowing what happens during init makes the rest of Terraform easier to reason about. When a backend won't initialize or a provider version won't update, you'll have a much better idea of where to look.