Terraform Init – Command Overview with Examples

Terraform init

What is Terraform init?

After writing your Terraform code or cloning your existing Terraform code from source control, the terraform init command is the first step you should take to prepare your working directory. This command initializes the environment by installing the necessary provider plugins and modules and setting up the configuration according to your code. Terraform init enables you to run further commands like terraform plan and terraform apply.

What does the Terraform init command do?

  • Backend initialization
  • Child module installation
  • Plugin installation

Terraform init quick usage examples - command flags

Quick usage examples

terraform init — Initialize the working directory, install required provider plugins and modules, and set up the backend.

terraform init -lock=false — Initialize the working directory; don’t hold a state lock during backend migration.

terraform init -input=false — Initialize the working directory and disable interactive prompts.

terraform init -migrate-state — Reconfigure a backend and attempt to migrate any existing state.

terraform init -upgrade – Ensure you’re using the latest compatible versions of your providers

terraform init -reconfigure – Use the -reconfigure flag to force Terraform to forget any previous configuration and reinitialize.

terraform init -get=false – Disable downloading modules for this configuration

terraform init -plugin-dir=/path/to/custom/plugins – Point Terraform to custom or manually downloaded provider plugins

How to initialize a Terraform file - example configuration files

The example files I will use in this article will create a specified number of groups in Azure AD.

1. Set main.tf file

These files are contained in a directory called az-ad-group. Within it, I have my Terraform configuration files, named main.tf, variables.tf and terraform.tfvars, as well as a .gitignorefile, which will specify which file extensions within the folder the git source control should ignore.

I have a subfolder (or module) within this which holds a main.tf and variables.tf file.

Lastly, the azure-pipeline.yml file specifies the pipeline settings to run terraform init and terraform plan.

provider "azurerm" {
  features {}

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">=2.95.0"
    azuread = {
      source  = "hashicorp/azuread"
  backend "azurerm" {
    resource_group_name  = "tf-rg"
    storage_account_name = "jacktfstatesa"
    container_name       = "terraform"
    key                  = "adgroups.tfstate"

module "ad_group" {
  source = "./ad_group"
  ad_group_names = var.ad_group_names

Note that the main.tf file contains the required_providers and backend blocks. I also call a module called ad_group.

Since this article focuses on the terraform init command, and everything relevant to that command is shown in the above code, I will not publish the rest of the files here, but they can be found in the GitHub repository should you wish to try the example out yourself or delve deeper into the setup.

2. Initialize backend

backend "azurerm" {
    resource_group_name  = "tf-rg"
    storage_account_name = "jacktfstatesa"
    container_name       = "terraform"
    key                  = "adgroups.tfstate"

Before that can happen successfully I will need to login to Azure using the Azure CLI. If I run it without first authenticating, Terraform complains that the resource group containing the storage account cannot be found.


To login to Azure, use the following commands. The --tenant flag does not need to be specified if you have only one Azure AD tenant linked to your login. If you have multiple tenants linked to your login, you should specify this to avoid confusion.

az login --tenant <tenant ID>
az account set --subscription <subscription ID>
Backend 2

Any changes to the backend configuration will be detected by Terraform. When terraform init is run, Terraform will throw an error alerting you to the change.

init error
  • migrate-state
  • reconfigure

3. Initialize the Terraform child module

module "ad_group" {
  source = "./ad_group"
  ad_group_names = var.ad_group_names

When terraform init is run we can see it being installed:

Initializing modules

4. Initialize the Terraform plugin

Most Terraform providers are published separately from Terraform as plugins. There are hundreds of available providers which allow Terraform to be used with different services. Common providers include azurerm for Microsoft Azure, azuread for Azure Active Directory, and aws for Amazon Web Services. A full list of available providers can be browsed using the Terraform registry.

Init provider plugins

5. Create dependency lock file – terraform.lock.hcl


The contents of the .terraform.lock.hcl file will look like this:

# This file is maintained automatically by "terraform init".
# Manual edits may be lost in future updates.

provider "registry.terraform.io/hashicorp/azuread" {
  version = "2.18.0"
  hashes = [

provider "registry.terraform.io/hashicorp/azurerm" {
  version     = "2.98.0"
  constraints = ">= 2.95.0"
  hashes = [

What is the difference between Terraform init and plan?

Both terraform init and terraform plan are among Terraform’s foundational commands.

The init command prepares the Terraform working directory by installing all the necessary provider plugins, downloading modules, and setting up state storage. In contrast, the plan command generates an execution plan showing infrastructure changes without implementing them.

While init prepares the environment for Terraform, plan previews potential adjustments based on the defined configuration against the current state.

Do you need to run Terraform init before every Terraform plan?

terraform init is the first command you should run in the workflow, however, if you know that no changes have been made to the modules, backend, or provider installations, you can go ahead and run terraform plan without running terraform init first. In automation, it is always best practice to put in a terraform init stage first to make sure the modules, providers, and backend are always up-to-date as specified in your configuration files.

Is it safe to run Terraform init multiple times?

It is always safe to run terraform init. It will never modify the configuration or destroy any resources. If it is run multiple times, it will simply update the working directory with the changes in the configuration. This will be required if the configuration changes include the addition of a new provider block or a change to the backend storage location, for example.

Running Terraform init in automation

terraform init will be the first step in configuring your Terraform workflow in an automation pipeline. In order to set this up in using Azure DevOps pipelines, we will use the azure-pipelines.yml file contained in the example code repository.

- stage: Build
  displayName: Terraform-Plan  
  - job: TerraformPlan
    displayName: Terraform-Plan
      name: Private-Build-Agents
    - checkout: self
    - script: ls $(System.DefaultWorkingDirectory)
    - task: TerraformInstaller@0
      displayName: 'Use Terraform latest'

    - task: TerraformCLI@0
      displayName: Terraform-Init
        command: 'init'
        workingDirectory: '$(System.DefaultWorkingDirectory)'
        backendType: 'azurerm'
        backendServiceArm: 'IAC Service Connection-Azure'
        backendAzureRmResourceGroupName: 'tf-rg'
        backendAzureRmStorageAccountName: 'jacktfstatesa'
        backendAzureRmContainerName: 'terraform'
        backendAzureRmKey: 'adgroups.tfstate'

    - task: TerraformCLI@0
      displayName: Terraform-Plan
        command: 'plan'
        workingDirectory: '$(System.DefaultWorkingDirectory)'
        environmentServiceName: 'RG Service Connection'
Downloading task

In some cases where you have lots of providers specified and want to avoid them being installed repeatedly on each pipeline run by terraform init, you may wish to make the providers available locally. This is possible and is covered in this advanced ‘Terraform in automation’ tutorial.

Terraform init options

  • backend=false
  • backend-config=path
  • force-copy
  • from-module=SOURCE
  • get=false
  • input=false
  • lock=false
state blob is already locked
Break lease
az storage blob lease break -b terraform.tfstate -c myAzureStorageAccountContainerName --account-name "myAzureStorageAccountName" --account-key "myAzureStorageAccountAccessKey"

Or using Terraform you can force the unlock, (get the LockID from the error) e.g.

terraform force-unlock <LockId>
  • lock-timeout=<duration>
  • no-color
  • plugin-dir
  • upgrade
azuread = {
   source  = "hashicorp/azuread"
   version = "=2.17.0"

If I then proceed to remove the version constraint from the azuread provider:

azuread = {
   source  = "hashicorp/azuread"
init upgrade

When re-run with the upgrade flag, you will notice that Terraform searches for the latest version of the azuread provider (v2.18.0 at the time of writing). Also, notice that any modules in the configuration are also upgraded.

init upgrade 2
  • migrate-state
  • reconfigure
  • lockfile=MODE
  • ignore-remote-version

Terraform init errors and troubleshooting

In the table below are the common terraform init errors and their solutions.

Error Troubleshooting
Provider/Modules Plugins Not Found / Download failures Ensure the required providers are correctly specified in your configuration

– If you are using a private network ensure a proxy is in place

– If you are using a private registry, ensure you have logged in successfully to it, or if it has the required provider

Unsupported Terraform Version – Review the “required_version” setting in your Terraform configuration

– Upgrade or downgrade your Terraform binary to a supported version 

Backend Initialization failure Ensure the backend configuration details are correct
– Check permissions and authentication
State Locking Errors Ensure the DynamoDB table is correctly set up if you are using it for locking
– Manually solve dangling locks
Initialization conflicts – A previous “.terraform” directory may cause conflicts – deleting it and rerunning init may fix the issue

Key Points

The terraform init command is the first command you should use to prepare the working directory. terraform init specifically performs the following actions:

  • Backend Initialization
  • Child Module Installation
  • Plugin Installation

Note: New versions of Terraform will be placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that will expand on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6. OpenTofu retained all the features and functionalities that had made Terraform popular among developers while also introducing improvements and enhancements. OpenTofu works with your existing Terraform state file, so you won’t have any issues when you are migrating to it. 

Don’t forget to take a look at how Spacelift helps you manage the complexities and compliance challenges of using Terraform. It brings with it a GitOps flow, so your infrastructure repository is synced with your Terraform Stacks, and pull requests show you a preview of what they’re planning to change. It also has an extensive selection of policies, which lets you automate compliance checks and build complex multi-stack workflows. You may also check how initialization policies work with Spacelift.

Terraform Management Made Easy

Spacelift effectively manages Terraform state, more complex workflows, supports policy as code, programmatic configuration, context sharing, drift detection, resource visualization and includes many more features.

Start free trial
Terraform CLI Commands Cheatsheet

Initialize/ plan/ apply your IaC, manage modules, state, and more.

Share your data and download the cheatsheet