Installation #

Terraform is distributed as a single binary — no runtime dependencies, no JVM, no container engine to install separately. You download one file, run it, and you’re ready to work. This simplicity of distribution is one of the reasons Terraform is so popular — its barrier to entry is very low. This section walks through the installation process on macOS, Linux, and Windows, plus how to manage multiple Terraform versions side by side.

Choosing an Installation Method #

There are several ways to install Terraform. The choice depends on your operating system and whether you need to manage multiple versions at once.

flowchart TD
    A["Install Terraform"] --> B{"OS?"}
    B -->|"macOS"| C{"Have\nHomebrew?"}
    B -->|"Linux"| D{"Distro?"}
    B -->|"Windows"| E{"Have\nWinget?"}

    C -->|"Yes"| F["brew install\nhashicorp/tap/terraform\n✅ Easiest"]
    C -->|"No"| G["Download the binary\nfrom releases.hashicorp.com"]

    D -->|"Debian/Ubuntu"| H["Official HashiCorp\napt repository"]
    D -->|"RHEL/Fedora"| I["Official HashiCorp\nyum repository"]
    D -->|"Other"| J["Download the binary\nfrom releases.hashicorp.com"]

    E -->|"Yes"| K["winget install\nHashiCorp.Terraform"]
    E -->|"No"| L["choco install\nterraform"]

    A --> M{"Need multiple versions?"}
    M -->|"Yes"| N["Install tfenv\nthen tfenv install <version>"]
    M -->|"No"| O["Pick a method above"]

    style F fill:#e8f5e9,stroke:#2e7d32
    style H fill:#e8f5e9,stroke:#2e7d32
    style K fill:#e8f5e9,stroke:#2e7d32
    style N fill:#e3f2fd,stroke:#1565c0

Method	OS	Pros	Cons
Homebrew	macOS	Easiest, auto-update	Requires Homebrew
apt/yum repo	Linux	Integrated with the package manager	Requires repo setup
Winget	Windows	Native Windows package manager	Not supported on all Windows versions
Chocolatey	Windows	Popular, stable	Requires installing Chocolatey
Manual binary	All	Requires nothing	Manual updates
tfenv	macOS/Linux	Multi-version, auto-switch	Requires installing tfenv

Installing on macOS #

The most convenient way on macOS is using Homebrew. If you don’t have Homebrew yet, install it first from brew.sh.

# Using Homebrew (recommended)
brew tap hashicorp/tap
brew install hashicorp/tap/terraform

# Verify the installation
terraform version
# Terraform v1.6.x
# on darwin_arm64

# Update to the latest version
brew upgrade hashicorp/tap/terraform

If you don’t use Homebrew, download the binary directly from the official releases page.

# Download the binary directly
# Check the latest version at: https://releases.hashicorp.com/terraform/
TF_VERSION="1.6.6"
curl -LO "https://releases.hashicorp.com/terraform/${TF_VERSION}/terraform_${TF_VERSION}_darwin_arm64.zip"
unzip "terraform_${TF_VERSION}_darwin_arm64.zip"
sudo mv terraform /usr/local/bin/
rm "terraform_${TF_VERSION}_darwin_arm64.zip"

Installing on Linux #

On Linux, use HashiCorp’s official repository to get easy updates through the package manager.

Ubuntu / Debian #

# Add the official HashiCorp GPG key
wget -O- https://apt.releases.hashicorp.com/gpg | \
  gpg --dearmor | \
  sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg > /dev/null

# Add the repository
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

# Install
sudo apt update && sudo apt install terraform

# Verify
terraform version

CentOS / RHEL / Fedora #

# Add the official repository
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo

# Install
sudo yum -y install terraform

# Verify
terraform version

Manual Binary (Any Linux Distro) #

# Download and install the binary directly
TF_VERSION="1.6.6"
curl -LO "https://releases.hashicorp.com/terraform/${TF_VERSION}/terraform_${TF_VERSION}_linux_amd64.zip"
unzip "terraform_${TF_VERSION}_linux_amd64.zip"
sudo mv terraform /usr/local/bin/
rm "terraform_${TF_VERSION}_linux_amd64.zip"

# Verify
terraform version

Installing on Windows #

On Windows, use Winget (the built-in package manager of Windows 11) or Chocolatey.

# Using Winget (Windows 11+)
winget install HashiCorp.Terraform

# Using Chocolatey
choco install terraform

# Or manually:
# 1. Download the zip from https://releases.hashicorp.com/terraform/
# 2. Extract terraform.exe
# 3. Move it to a directory in your PATH
#    (e.g. C:\terraform, then add it to the System PATH)

# Verify (in PowerShell or Command Prompt)
terraform version

After a manual install on Windows, make sure the directory containing terraform.exe has been added to the System PATH so it can be accessed from any terminal. Open System Properties → Environment Variables → Path → Edit → New, then add the directory path.

Managing Multiple Versions with tfenv #

In the real world, you might work on several Terraform projects, each using a different version. An old project might still be on v1.3, a new project on v1.6. Switching versions manually is a recipe for frustration. tfenv solves this — it’s a version manager for Terraform, similar to nvm for Node.js or pyenv for Python.

# Install tfenv on macOS
brew install tfenv

# Install tfenv on Linux
git clone --depth=1 https://github.com/tfutils/tfenv.git ~/.tfenv
echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# For zsh: ~/.zshrc

Once tfenv is installed, you can manage multiple Terraform versions easily.

# List all available versions
tfenv list-remote

# Install several versions
tfenv install 1.6.6
tfenv install 1.5.7
tfenv install latest

# Activate a specific version globally
tfenv use 1.6.6

# List installed versions
tfenv list

tfenv’s most powerful feature is per-project version pinning. Just create a .terraform-version file in the project root, and tfenv will automatically use the right version whenever you’re in that directory.

# In project A's root (using Terraform 1.6)
echo "1.6.6" > .terraform-version

# In project B's root (using Terraform 1.5)
echo "1.5.7" > .terraform-version

# When you cd into project A:
$ terraform version
Terraform v1.6.6

# When you cd into project B:
$ terraform version
Terraform v1.5.7

# Switches versions automatically without manual configuration!

flowchart LR
    A["Project A\n.terraform-version = 1.6.6"] --> C["tfenv"]
    B["Project B\n.terraform-version = 1.5.7"] --> C
    C --> D["terraform v1.6.6\nwhen in Project A"]
    C --> E["terraform v1.5.7\nwhen in Project B"]

    style A fill:#e3f2fd,stroke:#1565c0
    style B fill:#fff3e0,stroke:#e65100
    style D fill:#e8f5e9,stroke:#2e7d32
    style E fill:#e8f5e9,stroke:#2e7d32

Commit the .terraform-version file to version control. This ensures all team members use the same Terraform version for each project — avoiding “works on my machine” caused by version differences.

Verifying the Installation #

After installation, verify that everything works correctly.

# Check the version
terraform version
# Terraform v1.6.6
# on darwin_arm64

# Check the binary location
which terraform
# /opt/homebrew/bin/terraform (macOS Homebrew)
# /usr/local/bin/terraform (Linux manual)

# Check that help works
terraform help
# Shows the list of subcommands

# Check help for a specific subcommand
terraform help plan
# Shows flags and options for terraform plan

# Enable tab completion for a more comfortable CLI experience
terraform -install-autocomplete
# Restart the terminal afterwards

# Now you can type:
# terraform pl<TAB>  →  terraform plan
# terraform app<TAB> →  terraform apply

Verifying the Installation #

After installing Terraform, verify that the installation works correctly.

# Check the version
terraform version
# Terraform v1.6.3
# on darwin_arm64

# Check that the binary runs
terraform --help
# Shows the list of available commands

# Check provider plugins
terraform providers
# Shows the providers required by the current configuration

# Simple test: create a test file and run it
mkdir test-install && cd test-install
echo 'output "hello" { value = "Terraform is working!" }' > main.tf
terraform init
terraform output
# hello = "Terraform is working!"
rm -rf test-install

# Common troubleshooting:

# Error: "terraform: command not found"
# → PATH isn't configured correctly
echo $PATH | tr ':' '\n' | grep terraform

# Error: "Error: Incompatible Terraform version"
# → The Terraform version isn't compatible with the configuration
# → Check required_version in the terraform block
terraform version

# Error: "Error: Failed to install provider"
# → Network problem or the registry is unreachable
terraform init -plugin-dir=/path/to/plugins

Version Management #

# Managing multiple Terraform versions with tfenv (macOS/Linux)
brew install tfenv
tfenv install 1.6.3
tfenv install 1.5.7
tfenv use 1.6.3
terraform version  # Terraform v1.6.3

# Or with tenv (a newer alternative)
brew install tenv
tenv tofu install latest
tenv terraform install 1.6.3

# Version pinning in a project
# .terraform-version file:
echo "1.6.3" > .terraform-version
# The tool will automatically use this version

# Check compatibility
terraform version -json | jq '.terraform_version'

# In the configuration, pin the minimum version
terraform {
  required_version = ">= 1.6.0, < 2.0.0"
  # Make sure the team uses a compatible version
}

Platform-Specific Installation #

# macOS with Homebrew (recommended)
brew tap hashicorp/tap
brew install hashicorp/terraform
brew upgrade hashicorp/terraform

# Linux (Debian/Ubuntu)
wget -O- 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 update && sudo apt install terraform

# Windows with Chocolatey
choco install terraform

# Verify the installation
terraform version
terraform --help

Version Manager (tfenv) #

# tfenv: Terraform version manager
# Install
brew install tfenv

# Install a specific version
tfenv install 1.6.0
tfenv install 1.5.5

# Set the default version
tfenv use 1.6.0

# List installed versions
tfenv list

# List available versions
tfenv list-remote

# .terraform-version file in the project root
echo "1.6.0" > .terraform-version
# tfenv will automatically switch to this version

# Alternative: tgswitch (for Terragrunt + Terraform)
brew install warrensbox/tap/tgswitch

# Or: tenv (supports Terraform, Terragrunt, OpenTofu)
brew install tenv

Summary #

Terraform is a single binary — no runtime dependencies, installable on macOS, Linux, and Windows in seconds.
Use a package manager (Homebrew, apt, yum, Winget, Chocolatey) for easy installation and updates — avoid manual downloads unless necessary.
tfenv for multiple versions — if you work across projects using different Terraform versions, tfenv handles switching automatically.
.terraform-version enables per-project version pinning — commit this file to version control so all team members stay consistent.
Enable tab completion (terraform -install-autocomplete) to speed up typing commands.
Verify the installation with terraform version and make sure the binary is in your PATH.

← Previous: State Next: CLI →