patternbashterraformTip

tfenv manages multiple Terraform versions on a developer machine

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

tfenvterraform versionversion manager.terraform-versionversion pinningopentofutofuenv

Error Messages

Error: Unsupported Terraform Core version

Problem

Different Terraform projects require different Terraform CLI versions. Manually downloading and swapping binaries is error-prone. Running the wrong version can produce plan output that differs from what CI produces, causing unexpected changes.

Solution

Install tfenv and add a .terraform-version file to each project root. tfenv reads this file and automatically uses the correct Terraform binary.

# Install tfenv (macOS)
brew install tfenv

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

# Pin a version per project
echo "1.7.5" > .terraform-version

# tfenv automatically selects the version when you enter the directory
cd my-project
terraform version  # Uses 1.7.5 from .terraform-version

# List installed versions
tfenv list

# Install the version specified in .terraform-version
tfenv install

Why

Terraform has breaking changes between minor versions (especially pre-1.0). CI should match developer environments exactly. A .terraform-version file in source control ensures every team member uses the same version.

Gotchas

Commit .terraform-version to source control — it is not sensitive
tfenv respects TFENV_TERRAFORM_VERSION environment variable for overriding the file
OpenTofu (the open-source Terraform fork) has tofuenv as an equivalent tool
CI systems should also use tfenv or a direct binary download matching .terraform-version

Context

Developer machines and CI systems that work with multiple Terraform projects requiring different versions

Revisions (0)

No revisions yet.