Choosing an Installation Method

The choice of installation method is the first operational decision you make for Terraform. It dictates how upgrades are rolled out, how versions are pinned, how rollbacks work, and how an air-gapped network is handled. Get this wrong and the rest of the workflow is harder than it needs to be.

Five common paths

The five paths sysadmins actually use, in the order they are encountered in the wild.

+----------------------+ +----------------------+ +----------------------+
| HashiCorp apt repo   | | Standalone binary    | | tfenv (per-user)     |
| - Ubuntu / Debian    | | - any distro         | | - Ubuntu / Debian    |
| - GPG-signed         | | - air-gap friendly   | | - multi-version      |
| - managed upgrades   | | - no GPG             | | - per-engineer       |
+----------------------+ +----------------------+ +----------------------+
+----------------------+ +----------------------+
| asdf-vm              | | Homebrew             |
| - polyglot teams     | | - macOS only         |
| - one tool per lang  | | - dev workstations  |
+----------------------+ +----------------------+

The first three are the production-relevant choices. The fourth and fifth are common on engineer workstations but rarely used in production.

HashiCorp apt repository (production default)

The canonical install path on Ubuntu 24.04 and Debian 12. The package is signed by HashiCorp’s release key, integrated with apt update / apt upgrade, and pinned to a specific release stream.

Configuration.

# DESTRUCTIVE: install prerequisites and key
sudo apt-get update
sudo apt-get install -y gnupg software-properties-common

# Install the HashiCorp GPG key into /etc/apt/keyrings
wget -O- https://apt.releases.hashicorp.com/gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

# Verify the key fingerprint against the published value
gpg --no-default-keyring \
  --keyring /usr/share/keyrings/hashicorp-archive-keyring.gpg \
  --fingerprint

# Add the repository, signed by the key above
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

Trade-offs.

• Pro. Single source of truth. apt upgrade updates the package. GPG signature is verified by apt itself. Standard for any host that already uses apt.
• Pro. Integration with unattended-upgrades. You can pin to a specific minor version with apt-mark hold terraform and review before upgrading.
• Con. Single version per host. To run two Terraform installations side by side (rare in production), you need a version manager on top.
• Con. OpenTofu is in a separate repository. If you run both, install OpenTofu from its own repo or as a standalone binary.

When to use. Production servers, CI runners, any host with a single Terraform version and a single team that owns it.

Standalone binary

Download the zip from releases.hashicorp.com, verify the SHA-256, unzip into /usr/local/bin. The same pattern works for OpenTofu from github.com/opentofu/opentofu/releases.

# READ-ONLY first: confirm the checksum file
curl -fsSL https://releases.hashicorp.com/terraform/1.9.8/terraform_1.9.8_SHA256SUMS
curl -fsSL https://releases.hashicorp.com/terraform/1.9.8/terraform_1.9.8_linux_amd64.zip

# Verify before installing
sha256sum -c <(grep linux_amd64 terraform_1.9.8_SHA256SUMS) < terraform_1.9.8_linux_amd64.zip

# CONFIGURATION: install
sudo unzip -o terraform_1.9.8_linux_amd64.zip -d /usr/local/bin

Trade-offs.

• Pro. Air-gapped. Once the binary is on the host, no network access is required to run it. Verification is by hash, not GPG.
• Pro. Identical across distros. The same zip works on Ubuntu, Debian, RHEL, Alpine.
• Con. No upgrade story of its own. You script the download-verify-unzip cycle. Without that script, the host drifts.
• Con. No automatic security updates. You are the release manager.

When to use. Air-gapped networks, immutable infrastructure where the binary is baked into an image, hosts that need an exact version that the apt repository does not carry.

tfenv (per-user)

tfenv is a Terraform-specific version manager, modelled on rbenv. The engineer picks a version; tfenv install downloads it into ~/.tfenv/versions/ and writes a shim into the PATH.

# Engineer workstation only - not production
git clone --depth=1 https://github.com/tfutils/tfenv.git ~/.tfenv
echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.bashrc

# Pick a version
tfenv list-remote
tfenv install 1.9.8
tfenv use 1.9.8

# Pin a version per working directory
echo "1.9.8" > .terraform-version

Trade-offs.

• Pro. Per-engineer version selection. A polyglot team that maintains modules for Terraform 1.6 and OpenTofu 1.7 can keep both.
• Pro. Per-directory pinning. A .terraform-version file alongside the configuration selects the right version automatically.
• Con. Not for production. The install lives under the user’s home directory. The system has no record of which version is installed; apt cannot update it.
• Con. Upgrades are pull-driven. A new release lands when the engineer chooses to run tfenv install, not on a schedule.

When to use. Engineer workstations. Multi-version development. Rare in production, common in module-author workflows.

asdf-vm

asdf is a general-purpose version manager that handles Terraform, OpenTofu, kubectl, helm, and dozens of other tools via plugins. The trade-offs are similar to tfenv, with two differences:

• Pro. Single tool for all version managers. If your team uses tfenv, rbenv, nodenv, and so on, asdf unifies them.
• Con. Plugin management is its own moving part. The asdf-hashicorp plugin covers both Terraform and OpenTofu, but you must add it.

Use asdf when the team already runs it for other languages. Do not introduce asdf just for Terraform.

Homebrew (macOS only)

Homebrew on macOS installs Terraform into /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel). It is convenient for workstations but is not appropriate for Linux production.

Trade-offs.

• Pro. One command: brew install terraform.
• Pro. Auto-updated by brew upgrade.
• Con. macOS only.
• Con. Not for production. Production Linux uses apt, the binary, or a version manager.

When to use. macOS engineer workstations. Nothing else.

Right per-environment choice

Production failure modes

1. Mixing methods on the same host. Symptom: two terraform binaries in different PATH directories; which terraform returns whichever wins the PATH race. Recovery: standardise on one method, uninstall the other.

2. Forgetting to verify the binary. Symptom: a tampered or truncated binary is installed; terraform version returns something, but the binary is wrong. Recovery: always verify the SHA-256 of the standalone binary against the upstream SHA256SUMS file before installing. The apt repository verifies GPG automatically; do not skip the equivalent step for the binary.

3. Using the latest tag without a pin. Symptom: an apt upgrade moves the host from Terraform 1.9.x to 1.10.0 overnight, and a configuration that depended on a 1.9-only behaviour breaks. Recovery: apt-mark hold terraform until the configuration has been tested against the new version.

4. tfenv on a production server. Symptom: an engineer “fixed” the production host by running tfenv install; the binary is under a user’s home directory and disappears when the user is removed. Recovery: standardise on a system-level install for production; remove tfenv from production hosts.

5. Homebrew on Linux. Symptom: a Linux host running brew install terraform has an unexpected binary location and no integration with the system package manager. Recovery: do not use Homebrew on Linux. It is supported but not appropriate.

6. The standalone binary that never gets upgraded. Symptom: six months in, the host is on Terraform 1.7 while the team is on 1.9. Plans diverge. Recovery: schedule the binary upgrade. Bake the download-verify-install cycle into a script owned by the platform team.

Security and performance

• Trust chain. The apt repository verifies GPG on every package. The standalone binary verifies a SHA-256 you check by hand. For CI, the SHA-256 check belongs in the pipeline, not in a one-liner that an engineer ran once.
• Install footprint. The apt package is ~50 MB plus a few hundred KB of metadata. The standalone binary is ~80 MB. Neither is significant. The performance question is not the install but the provider plugin cache, covered separately.
• Network exposure. Both methods require HTTPS to apt.releases.hashicorp.com or releases.hashicorp.com. In an air-gapped network, the binary is downloaded once and shipped in; the apt repository requires a mirror.

Production guidance

• One method per host class. All production servers use apt; all CI runners use a pre-baked image; all workstations use tfenv. The rule is documented and enforced.
• Pin the version. Either apt-mark hold or a version-pinned Docker image. The team should know the exact version every host is running, and a script should report it.
• Verify by hash on every install. For the standalone binary, verify before installing. For the apt repository, trust the GPG signature and verify the fingerprint once.
• Schedule an upgrade review. Once a quarter, review the current Terraform release and decide whether to upgrade. Do not allow unattended upgrades to Terraform on production hosts.

What comes next

The next lesson covers the verification steps that confirm the install is correct: terraform version, the shell autocomplete, and a smoke test against a development backend.

Verification

On a host you have just installed Terraform, run the following to confirm the install is healthy. The output is illustrative.

# READ-ONLY: confirm the install
terraform version

Terraform v1.9.8
on linux_amd64
+ provider registry.terraform.io/hashicorp/aws v5.65.0

The second line confirms the architecture. The third line confirms that providers from a prior terraform init are still cached.

# CONFIGURATION: install shell autocomplete for bash
terraform -install-autocomplete

# READ-ONLY: confirm the binary location matches expectations
which terraform
command -v terraform
type terraform

If which terraform returns a path you do not recognise, you have two installs in the PATH. Standardise.