Lesson 02 beginner

Installing Terraform

Install Terraform 1.17 on Windows, macOS and Linux, manage several versions per project with tenv, set up your editor and run a first configuration that needs no cloud account.

Terraform is a single binary with no runtime to install. You can download it, put it on your PATH and be done. In practice it is worth spending ten more minutes on two things: a package manager so updates are one command, and a version manager so every project runs the Terraform version it was written for.

Install on Windows

The simplest route is WinGet, which ships with Windows 10 and 11:

$ winget install --id Hashicorp.Terraform -e
$ terraform version
Terraform v1.17.1
on windows_amd64

Open a new terminal after installing so it picks up the updated PATH. On a Windows ARM laptop, Terraform 1.15 and later ship native windows_arm64 builds, so there is no emulation slowdown.

Chocolatey (choco install terraform) and Scoop (scoop install terraform) also work if your team already uses them.

Install on macOS

Use HashiCorp’s own Homebrew tap. The terraform formula in Homebrew’s default catalogue stopped at 1.5.7 when the licence changed, so the tap is the only way to get current versions:

$ brew tap hashicorp/tap
$ brew install hashicorp/tap/terraform
$ terraform version
Terraform v1.17.1
on darwin_arm64

Update later with brew upgrade hashicorp/tap/terraform.

Install on Linux

On Ubuntu and Debian, add HashiCorp’s signed APT repository once, then install and update through apt:

$ sudo apt-get update && sudo apt-get install -y gnupg curl
$ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
$ echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
$ sudo apt-get update && sudo apt-get install -y terraform
$ terraform version
Terraform v1.17.1
on linux_amd64

For Fedora, RHEL and Amazon Linux, HashiCorp publishes an RPM repository at rpm.releases.hashicorp.com; the steps are on the official install page. Inside a container or CI image, downloading the zip from releases.hashicorp.com and checking its SHA256 sum is fine too.

One version per project with tenv

Terraform is backward compatible within 1.x, but a state file written by a newer version cannot be read by an older one. If one teammate applies with 1.17 and another still runs 1.14, the second one gets an error. Pinning the version per project avoids that.

tenv is a small version manager that handles Terraform, OpenTofu and Terragrunt. It has replaced the older tfenv in most teams.

$ tenv tf install 1.17.1
$ tenv tf use 1.17.1
$ echo "1.17.1" > .terraform-version
$ terraform version
Terraform v1.17.1

Commit .terraform-version with your code. When anyone runs terraform inside that folder, tenv picks (and if needed downloads) that exact version.

Also state the minimum version in the code itself, so Terraform refuses to run with something too old:

terraform {
  required_version = ">= 1.17.0, < 2.0.0"
}

Set up your editor

A good editor setup catches most typos before you even run terraform validate:

  • VS Code: install the official HashiCorp Terraform extension. It gives syntax highlighting, completion of resource arguments from the provider schema, go to definition and format on save.
  • JetBrains IDEs: the Terraform and HCL plugin from JetBrains does the same.
  • Shell completion: terraform -install-autocomplete adds tab completion for subcommands to bash or zsh. Restart the shell afterwards.

Format on save. Turn it on. terraform fmt is the one style everyone agrees on, and unformatted files make pull request diffs noisy.

Your first configuration (no cloud needed)

Create an empty folder called orbit-hello with one file, main.tf. It uses two small official providers that work entirely on your machine: random generates a value and local writes a file.

terraform {
  required_version = ">= 1.17.0"

  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "~> 3.7"
    }
    local = {
      source  = "hashicorp/local"
      version = "~> 2.5"
    }
  }
}

resource "random_pet" "release" {
  length = 2
}

resource "local_file" "welcome" {
  filename = "${path.module}/welcome.txt"
  content  = "Orbit release name: ${random_pet.release.id}\n"
}

output "release_name" {
  value = random_pet.release.id
}

Run it:

$ terraform init
Initializing provider plugins...
- Installing hashicorp/random v3.7.2...
- Installing hashicorp/local v2.5.3...
Terraform has been successfully initialized!
$ terraform apply -auto-approve
random_pet.release: Creating...
random_pet.release: Creation complete after 0s [id=quiet-falcon]
local_file.welcome: Creating...
local_file.welcome: Creation complete after 0s
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

release_name = "quiet-falcon"

Your release name will differ. Open welcome.txt and you will see it. Run terraform apply a second time: Terraform reports No changes, because the state says both resources already exist and match the code. Then clean up with terraform destroy.

About -auto-approve. It skips the “type yes” prompt. That is fine for a throwaway folder on your laptop. Never use it against shared infrastructure unless the plan was reviewed first; lesson 14 shows the safe way to do that in CI.

What init left behind

After terraform init, the folder has new files. Know what each one is before your first commit:

PathWhat it isCommit it?
.terraform/Downloaded providers and modulesNo, add to .gitignore
.terraform.lock.hclExact provider versions and checksumsYes
terraform.tfstateThe state (after apply)No, it can hold secrets
terraform.tfstate.backupThe previous stateNo
*.tfvarsVariable valuesOnly if they hold no secrets

A starter .gitignore for every Terraform repository:

.terraform/
*.tfstate
*.tfstate.*
crash.log
*.tfplan

Quick reference

TaskCommand
Install on Windowswinget install --id Hashicorp.Terraform -e
Install on macOSbrew install hashicorp/tap/terraform
Install on Ubuntu/Debiansudo apt-get install terraform (after adding the repo)
Show version and platformterraform version
Install a specific versiontenv tf install 1.17.1
Pin the version for a folderecho "1.17.1" > .terraform-version
Enable shell completionterraform -install-autocomplete
See all subcommandsterraform -help

Exercise

You run brew install terraform on a Mac and get version 1.5.7. Why?

  1. Your Mac is too old for newer versions
  2. The default Homebrew formula stopped at the last open-source release; current versions come from the hashicorp/tap tap
  3. Homebrew installs the long-term support version by default
  4. You need to run brew update twice
Show answer

Answer: B. After the licence change, Homebrew’s default catalogue kept only the last MPL-licensed version. Install hashicorp/tap/terraform to get current releases.

Exercise

Which file from terraform init should be committed to Git?

  1. .terraform/
  2. terraform.tfstate
  3. .terraform.lock.hcl
  4. terraform.tfstate.backup
Show answer

Answer: C. The lock file records the exact provider versions and checksums so every teammate and pipeline installs the same providers. The .terraform folder is a download cache, and state files must never be in Git.

Key takeaways

  • Terraform is one binary; use a package manager so updates are one command.
  • On macOS, install from hashicorp/tap; the default Homebrew formula is stuck at 1.5.7.
  • Pin the Terraform version per project with tenv and .terraform-version, and set required_version in code.
  • Install the HashiCorp Terraform extension and turn on format on save.
  • Commit .terraform.lock.hcl; ignore .terraform/ and every state file.

FAQ

Do I need administrator rights to install Terraform?

No. You can unzip the binary into any folder in your user profile and add that folder to your PATH. Package managers just automate this.

Can Terraform and OpenTofu be installed side by side?

Yes. They are separate binaries (terraform and tofu), and tenv manages both. Do not point both at the same state at the same time: the state formats have started to diverge.

How often should I upgrade Terraform?

A new minor version arrives roughly every few months. Read the upgrade notes, upgrade one project at a time, run a plan and expect “No changes”. Staying more than a couple of minor versions behind makes later upgrades harder.

Does Terraform run on Windows natively, or do I need WSL?

It runs natively. WSL is only useful if your team’s scripts around Terraform are written in bash.

↑ ↓ navigate Enter open Esc close