Skip to main content
This quickstart guide will walk you through installing Terraform and creating your first infrastructure. You’ll learn the basic Terraform workflow: write, initialize, plan, and apply.
This guide uses the local provider to create a file on your local system. This is a simple example to demonstrate Terraform’s workflow without requiring cloud credentials.

​
Prerequisites

Before you begin, make sure you have:
  • A terminal or command prompt
  • Basic familiarity with the command line
  • Approximately 10 minutes

​
Step 1: Install Terraform

First, you’ll need to install Terraform on your system. The easiest way is to download a pre-built binary from the HashiCorp releases website.
Using Homebrew:
brew tap hashicorp/tap
brew install hashicorp/tap/terraform
Verify the installation: 
terraform version
You should see output showing the Terraform version number. For detailed installation instructions, see the Installation guide.

​
Step 2: Create Your First Configuration

Create a new directory for your Terraform project and navigate to it: 
mkdir terraform-demo
cd terraform-demo
Create a file named main.tf with the following content:
main.tf
terraform {
  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.4"
    }
  }
}

provider "local" {}

resource "local_file" "hello" {
  filename = "${path.module}/hello.txt"
  content  = "Hello, Terraform!\n"
}

resource "local_file" "config" {
  filename = "${path.module}/config.json"
  content = jsonencode({
    message     = "Welcome to Terraform"
    environment = "development"
    timestamp   = "2024-03-15"
  })
}

output "hello_file_path" {
  description = "Path to the hello.txt file"
  value       = local_file.hello.filename
}

output "config_content" {
  description = "Content of the config file"
  value       = jsondecode(local_file.config.content)
}
This configuration uses the local provider to create two files on your local filesystem. The terraform block specifies the required provider, and the resource blocks define the infrastructure.

​
Step 3: Initialize Terraform

Before you can use Terraform, you need to initialize the working directory. This downloads the required provider plugins. 
terraform init
You should see output similar to: 
Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/local versions matching "~> 2.4"...
- Installing hashicorp/local v2.4.1...
- Installed hashicorp/local v2.4.1 (signed by HashiCorp)

Terraform has been successfully initialized!
The terraform init command is safe to run multiple times. It will only download providers that aren’t already present.

​
Step 4: Preview Changes with Plan

Before creating any infrastructure, it’s a good practice to preview what Terraform will do: 
terraform plan
Terraform will show you the execution plan: 
Terraform will perform the following actions:

  # local_file.config will be created
  + resource "local_file" "config" {
      + content              = jsonencode(
            {
              + environment = "development"
              + message     = "Welcome to Terraform"
              + timestamp   = "2024-03-15"
            }
        )
      + filename             = "./config.json"
      + id                   = (known after apply)
    }

  # local_file.hello will be created
  + resource "local_file" "hello" {
      + content              = "Hello, Terraform!\n"
      + filename             = "./hello.txt"
      + id                   = (known after apply)
    }

Plan: 2 to add, 0 to change, 0 to destroy.
The + symbol indicates that Terraform will create these resources.

​
Step 5: Apply the Configuration

Now, let’s create the infrastructure: 
terraform apply
Terraform will show the plan again and ask for confirmation. Type yes to proceed: 
Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes
After applying, you’ll see: 
local_file.config: Creating...
local_file.hello: Creating...
local_file.hello: Creation complete after 0s [id=abc123...]
local_file.config: Creation complete after 0s [id=def456...]

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

config_content = {
  "environment" = "development"
  "message" = "Welcome to Terraform"
  "timestamp" = "2024-03-15"
}
hello_file_path = "./hello.txt"
Terraform has created two files in your directory: hello.txt and config.json. You can verify this by running ls or cat hello.txt.

​
Step 6: Modify Infrastructure

Let’s modify the configuration to see how Terraform handles changes. Edit main.tf and update the content of the hello file:
main.tf
resource "local_file" "hello" {
  filename = "${path.module}/hello.txt"
  content  = "Hello, Terraform! Updated at $(date)\n"
}
Run terraform plan again to see what will change: 
terraform plan
You’ll see that Terraform detects the change and plans to update the resource: 
  # local_file.hello must be replaced
-/+ resource "local_file" "hello" {
      ~ content  = "Hello, Terraform!\n" -> "Hello, Terraform! Updated...\n"
      ~ id       = "abc123..." -> (known after apply)
        # (1 unchanged attribute hidden)
    }

Plan: 1 to add, 0 to change, 1 to destroy.
Apply the changes: 
terraform apply

​
Step 7: Inspect State

Terraform keeps track of your infrastructure in a state file. You can inspect the current state: 
terraform show
To see a list of resources in your state: 
terraform state list

​
Step 8: Destroy Infrastructure

When you’re done experimenting, you can destroy the infrastructure: 
terraform destroy
Terraform will show you what it plans to destroy and ask for confirmation. Type yes to proceed: 
Plan: 0 to add, 0 to change, 2 to destroy.

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes
The terraform destroy command permanently deletes all resources managed by your Terraform configuration. Always double-check before confirming.

​
Understanding the Terraform Workflow

You’ve now experienced the core Terraform workflow:
1

Write

Define infrastructure in configuration files using HCL syntax
2

Initialize

Run terraform init to download provider plugins
3

Plan

Run terraform plan to preview changes
4

Apply

Run terraform apply to create or update infrastructure
5

Destroy

Run terraform destroy to clean up resources when done

​
Next Steps

Now that you understand the basics, explore these topics:

Core Concepts

Learn about providers, resources, variables, and state

CLI Reference

Explore all available Terraform commands

Configuration Language

Deep dive into HCL syntax and features

Cloud Providers

Work with AWS, Azure, GCP, and other providers

​
Common Commands Reference

CommandDescription
terraform initInitialize a working directory
terraform validateValidate configuration files
terraform planShow changes required to reach desired state
terraform applyCreate or update infrastructure
terraform destroyDestroy all managed infrastructure
terraform fmtFormat configuration files to canonical style
terraform showDisplay the current state or a saved plan
terraform state listList resources in the state
terraform outputShow output values
Use terraform -help to see all available commands, or terraform <command> -help for help with a specific command.

Build docs developers (and LLMs) love

Get started for freeTalk to us