Terraform Init – Command Overview with Examples

Terraform init

In this post, I will explain what the terraform init command is used for, what it does, and when to run it. I will explore the options available and give an example of when to use it in automation using Azure DevOps.

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 command you should use to initialize the working directory.

What Does the Terraform Init Command Do?

  • Backend Initialization
  • Child Module Installation
  • Plugin Installation

Quick Usage Examples

Example Configuration Files

The example files I will use in this article will create a specified number of groups in Azure AD. 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.

Backend Initialization

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

Child Module Installation

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

Plugin Installation

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



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 = [

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

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

For more documentation on the terraform init command check out the Hashicorp website.

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