Installation

This guide covers installing Terraform on various operating systems, verifying the installation, and setting up optional features like shell completion.

Pre-built Binaries (Recommended)

The easiest way to install Terraform is to download a pre-built binary from the HashiCorp Releases website.

macOS
Linux
Windows

Using Homebrew

The recommended way to install Terraform on macOS is using Homebrew:

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

To update Terraform:

brew update
brew upgrade hashicorp/tap/terraform

Manual Installation

Download the appropriate package from the downloads page
Extract the binary:
```
unzip terraform_*_darwin_*.zip
```
Move it to a directory in your PATH:
```
sudo mv terraform /usr/local/bin/
```

Using Package Manager

Ubuntu/Debian:

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

Fedora/RHEL/CentOS:

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

Manual Installation

Download the appropriate package:

wget https://releases.hashicorp.com/terraform/1.7.0/terraform_1.7.0_linux_amd64.zip

Extract the binary:
```
unzip terraform_1.7.0_linux_amd64.zip
```
Move it to a directory in your PATH:
```
sudo mv terraform /usr/local/bin/
```
Verify the installation:
```
terraform version
```

Using Chocolatey

If you have Chocolatey installed:

choco install terraform

Manual Installation

Download the appropriate package from the downloads page
Extract the ZIP file
Move terraform.exe to a directory in your PATH, such as C:\Windows\System32

Alternatively, create a new directory and add it to your PATH:

Create directory: C:\terraform
Add to PATH via System Properties > Environment Variables
Place terraform.exe in that directory

Terraform releases follow semantic versioning. Check the releases page for the latest version.

Building from Source

If you prefer to build Terraform from source, or need a custom build, follow these instructions.

Prerequisites

Install Go

Ensure you have Go installed. Terraform requires Go 1.25.7 or later (as specified in .go-version).Download Go from golang.org/dl or use your package manager:

# macOS
brew install [email protected]

# Ubuntu/Debian
sudo apt install golang-1.25

# Fedora
sudo dnf install golang

Clone the Repository

Clone the Terraform repository:

git clone https://github.com/hashicorp/terraform.git
cd terraform

Build Terraform

Build the binary using the Go toolchain:

go build -o bin/terraform .

This creates a terraform binary in the bin/ directory.

Build Options

Terraform accepts certain options passed using ldflags at build time:

Disable Dev Version Reporting

By default, Terraform includes a -dev flag when reporting its version (e.g., 1.5.0-dev). To disable this:

go build -ldflags "-w -s -X 'github.com/hashicorp/terraform/version.dev=no'" -o bin/terraform .

Enable Experimental Features

Experimental features are disabled by default. To enable them:

go build -ldflags "-w -s -X 'main.experimentsAllowed=yes'" -o bin/terraform .

Experimental features are not recommended for production use. In official builds, experiments are only allowed in alpha releases.

CGO Settings

For most platforms, build with CGO_ENABLED=0 for a statically linked binary:

CGO_ENABLED=0 go build -o bin/terraform .

For macOS/Darwin, use CGO_ENABLED=1 to avoid DNS resolution issues:

CGO_ENABLED=1 go build -o bin/terraform .

Install the Built Binary

After building, move the binary to a directory in your PATH:

# macOS/Linux
sudo mv bin/terraform /usr/local/bin/

# Or add the bin directory to your PATH
export PATH=$PATH:$(pwd)/bin

Verify Installation

After installing Terraform, verify it’s available:

terraform version

You should see output similar to:

Terraform v1.7.0
on linux_amd64

To see all available commands:

terraform -help

Run terraform -help to see a list of all available commands and their descriptions.

System Requirements

Terraform has minimal system requirements:

Operating System: macOS, Linux, Windows, or other Unix-like systems
Memory: At least 512MB RAM (more recommended for large infrastructures)
Disk Space: Approximately 100MB for the binary and plugins
Network: Internet access to download providers and modules (unless using air-gapped installations)

Terraform’s memory usage scales with the size and complexity of your infrastructure. Large deployments may require several gigabytes of RAM.

Shell Completion Setup

Terraform supports shell completion for bash, zsh, and fish. This provides tab-completion for commands and options.

Install Shell Completion

Bash
Zsh
Fish

Install the completion script:

terraform -install-autocomplete

Then reload your shell:

source ~/.bashrc

Install the completion script:

terraform -install-autocomplete

Then reload your shell:

source ~/.zshrc

Install the completion script:

terraform -install-autocomplete

Completions will be available after restarting your shell.

Uninstall Shell Completion

To remove shell completion:

terraform -uninstall-autocomplete

The -install-autocomplete command modifies your shell configuration file (.bashrc, .zshrc, etc.) to enable tab completion.

Environment Variables

Terraform supports several environment variables for configuration:

Variable	Description
`TF_CLI_ARGS`	Additional CLI arguments to append to all commands
`TF_DATA_DIR`	Override the default `.terraform` directory location
`TF_IN_AUTOMATION`	Set to any value to suppress prompts (for CI/CD)
`TF_LOG`	Enable logging (values: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`)
`TF_LOG_PATH`	Path to write log output

Example usage:

# Enable debug logging
export TF_LOG=DEBUG
export TF_LOG_PATH=./terraform.log

# Run Terraform
terraform apply

Next Steps

Now that Terraform is installed, you’re ready to start using it:

Quickstart Guide

Create your first infrastructure with Terraform

Core Concepts

Learn about Terraform’s architecture and workflow

Configuration Language

Understand HashiCorp Configuration Language (HCL)

Provider Registry

Browse available providers and modules

Troubleshooting

Command Not Found

If you see command not found: terraform, the binary is not in your PATH:

Verify the binary location: which terraform
Add the directory to your PATH:
```
export PATH=$PATH:/path/to/terraform
```
Make the change permanent by adding it to ~/.bashrc, ~/.zshrc, or equivalent

Permission Denied

If you see a permission error when running Terraform:

# Make the binary executable
chmod +x /path/to/terraform

Version Mismatch

If multiple versions of Terraform are installed, use a version manager like tfenv:

# Install tfenv
brew install tfenv

# Install a specific Terraform version
tfenv install 1.7.0
tfenv use 1.7.0

For team environments, consider using .terraform-version files to specify the required Terraform version for each project.

Upgrading Terraform

To upgrade Terraform:

Download the new version using the same method as installation
Replace the old binary with the new one
Run terraform version to verify

Always check the upgrade guides before upgrading between major versions, as there may be breaking changes.

Before upgrading production environments:

Test the new version in a development environment
Review the changelog for breaking changes
Update any deprecated syntax in your configurations
Run terraform plan to verify the upgrade doesn’t cause unexpected changes

Getting Started

Core Concepts

Configuration Language

Workflow

State Management

Providers

Advanced Features

Pre-built Binaries (Recommended)

Using Homebrew

Manual Installation

Using Package Manager

Manual Installation

Using Chocolatey

Manual Installation

Building from Source

Prerequisites

Build Options

Disable Dev Version Reporting

Enable Experimental Features

CGO Settings

Install the Built Binary

Verify Installation

System Requirements

Shell Completion Setup

Install Shell Completion

Uninstall Shell Completion

Environment Variables

Next Steps

Quickstart Guide

Core Concepts

Configuration Language

Provider Registry

Troubleshooting

Command Not Found

Permission Denied

Version Mismatch

Upgrading Terraform

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Configuration Language

Workflow

State Management

Providers

Advanced Features

​Pre-built Binaries (Recommended)

​Using Homebrew

​Manual Installation

​Using Package Manager

​Manual Installation

​Using Chocolatey

​Manual Installation

​Building from Source

​Prerequisites

​Build Options

​Disable Dev Version Reporting

​Enable Experimental Features

​CGO Settings

​Install the Built Binary

​Verify Installation

​System Requirements

​Shell Completion Setup

​Install Shell Completion

​Uninstall Shell Completion

​Environment Variables

​Next Steps

Quickstart Guide

Core Concepts

Configuration Language

Provider Registry

​Troubleshooting

​Command Not Found

​Permission Denied

​Version Mismatch

​Upgrading Terraform

Build docs developers (and LLMs) love

Pre-built Binaries (Recommended)

Using Homebrew

Manual Installation

Using Package Manager

Manual Installation

Using Chocolatey

Manual Installation

Building from Source

Prerequisites

Build Options

Disable Dev Version Reporting

Enable Experimental Features

CGO Settings

Install the Built Binary

Verify Installation

System Requirements

Shell Completion Setup

Install Shell Completion

Uninstall Shell Completion

Environment Variables

Next Steps

Troubleshooting

Command Not Found

Permission Denied

Version Mismatch

Upgrading Terraform