Navigation

Infrastructure as Code iac getting-started 4 min read

Installing Terraform

Terraform ships as a single self-contained binary, so installation is usually a one-line affair through your platform’s package manager. Getting it right early matters: the CLI version determines which HCL2 features and provider protocols you can use, and teams that pin a shared version avoid the classic “works on my machine” drift in state and plan output. This page walks through installing Terraform 1.5+ (and the drop-in OpenTofu alternative) on macOS, Linux, and Windows, managing multiple versions with tfenv, and verifying your setup.

Choosing Terraform or OpenTofu

Since HashiCorp relicensed Terraform under the BUSL in 2023, the Linux Foundation’s OpenTofu has emerged as an open-source fork that remains a near drop-in replacement. Both read the same .tf files, use the same provider registry protocol, and expose a nearly identical CLI (tofu instead of terraform). If your organization needs a fully open-source license, OpenTofu is worth evaluating; otherwise the official Terraform CLI is the most widely documented choice. The commands in these docs use terraform, but tofu is interchangeable.

Tool	Command	License	Provider registry
Terraform	`terraform`	BUSL 1.1	registry.terraform.io
OpenTofu	`tofu`	MPL 2.0	registry.opentofu.org

Installing on macOS

The simplest path on macOS is Homebrew with HashiCorp’s official tap. The tap ensures you get genuine signed builds rather than a community formula.

brew tap hashicorp/tap
brew install hashicorp/tap/terraform

To install OpenTofu instead:

brew install opentofu

Upgrading later is just brew upgrade hashicorp/tap/terraform.

Installing on Linux

On Debian and Ubuntu, add the HashiCorp APT repository so you receive signed packages and automatic updates through apt.

wget -O- https://apt.releases.hashicorp.com/gpg | \
  gpg --dearmor | \
  sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg > /dev/null

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 update && sudo apt install terraform

For RHEL, Fedora, or Amazon Linux, use the dnf repository instead:

sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
sudo dnf install terraform

Tip: On minimal or air-gapped systems you can skip package managers entirely. Download the zip for your architecture from releases.hashicorp.com, unzip it, and move the binary onto your PATH with sudo mv terraform /usr/local/bin/. Always verify the SHA256SUMS signature for production installs.

Installing on Windows

On Windows, Chocolatey is the most convenient option from an elevated PowerShell prompt:

choco install terraform

If you prefer the built-in Windows Package Manager:

winget install Hashicorp.Terraform

Both place terraform.exe on your PATH automatically. WSL2 users should instead follow the Linux APT instructions above, which keeps tooling consistent with most CI environments.

Managing versions with tfenv

Real projects often pin specific Terraform versions, and you may need to switch between them per repository. tfenv is a lightweight version manager modeled on rbenv/nvm that handles this cleanly.

brew install tfenv        # macOS
tfenv install 1.9.5       # install a specific version
tfenv install latest      # or the newest release
tfenv use 1.9.5           # activate it globally

If a repository contains a .terraform-version file, tfenv automatically selects that version when you run commands inside the directory. This makes the pinned version self-documenting and reproducible for the whole team.

echo "1.9.5" > .terraform-version
terraform version   # transparently resolves to 1.9.5 via tfenv

Warning: Once a project’s state is written by a newer Terraform version, older versions will refuse to operate on that state. Pin a version in .terraform-version and a required_version constraint in your config to prevent accidental upgrades.

You can also declare the constraint directly in HCL so terraform init fails fast on a mismatched CLI:

terraform {
  required_version = ">= 1.5.0, < 2.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

Verifying the installation

Confirm the CLI is on your PATH and report its version and platform. The version command also lists installed provider versions inside an initialized directory and warns if a newer release is available.

terraform version

Output:

Terraform v1.9.5
on darwin_arm64

A successful terraform -help listing the core commands (init, plan, apply, destroy) confirms the binary is fully functional.

Enabling shell autocomplete

Terraform ships built-in completion for Bash and Zsh. Install it once and reload your shell to get tab-completion for subcommands and flags.

terraform -install-autocomplete

This appends the appropriate hook to your ~/.bashrc or ~/.zshrc. After running source ~/.zshrc (or opening a new terminal), typing terraform pl<Tab> expands to terraform plan. OpenTofu provides the same feature via tofu -install-autocomplete.

Best Practices

Install through the official HashiCorp tap or APT/RPM repositories so you get signed, verifiable builds rather than unofficial mirrors.
Pin a required_version in your terraform {} block and a .terraform-version file so every contributor and CI runner uses the same CLI.
Use tfenv (or tenv for OpenTofu) to switch versions per project instead of juggling manual installs.
Verify with terraform version after upgrading, and check that it matches your project’s constraints before running plan or apply.
Keep CI pipelines on the exact same version as local development to avoid surprising differences in plan output.
Enable shell autocomplete to reduce typos in long subcommand and flag sequences.