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-autocompleteadds 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:
| Path | What it is | Commit it? |
|---|---|---|
.terraform/ | Downloaded providers and modules | No, add to .gitignore |
.terraform.lock.hcl | Exact provider versions and checksums | Yes |
terraform.tfstate | The state (after apply) | No, it can hold secrets |
terraform.tfstate.backup | The previous state | No |
*.tfvars | Variable values | Only if they hold no secrets |
A starter .gitignore for every Terraform repository:
.terraform/
*.tfstate
*.tfstate.*
crash.log
*.tfplan
Quick reference
| Task | Command |
|---|---|
| Install on Windows | winget install --id Hashicorp.Terraform -e |
| Install on macOS | brew install hashicorp/tap/terraform |
| Install on Ubuntu/Debian | sudo apt-get install terraform (after adding the repo) |
| Show version and platform | terraform version |
| Install a specific version | tenv tf install 1.17.1 |
| Pin the version for a folder | echo "1.17.1" > .terraform-version |
| Enable shell completion | terraform -install-autocomplete |
| See all subcommands | terraform -help |
Exercise
You run brew install terraform on a Mac and get version 1.5.7. Why?
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?
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 setrequired_versionin 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.