Introduction
Terraform is one of the most popular Infrastructure as Code (IaC) tools used to provision and manage cloud infrastructure across AWS, Azure, Google Cloud, Kubernetes, Datadog, GitHub, and many other platforms.
In real-world environments, DevOps and Platform Engineers often need to work with multiple Terraform versions because different projects may require different versions.
This is where tfenv becomes extremely useful.
What is Terraform?
Terraform is an open-source Infrastructure as Code (IaC) tool developed by HashiCorp that allows engineers to define infrastructure using code.
Example:
- AWS EC2 Instances
- VPCs
- RDS Databases
- EKS Clusters
- Kubernetes Resources
- Datadog Monitors
- GitHub Repositories
can all be managed using Terraform.
What is tfenv?
tfenv is a Terraform Version Manager similar to:
- pyenv for Python
- nvm for Node.js
- rbenv for Ruby
tfenv allows you to:
- Install multiple Terraform versions
- Switch Terraform versions instantly
- Use project-specific Terraform versions
- Avoid compatibility issues
Prerequisites
Before installing Terraform or tfenv, ensure:
Check macOS Version
sw_vers
Example:
ProductName: macOS
ProductVersion: 15.x
BuildVersion: xxxx
Install Xcode Command Line Tools
xcode-select --install
Verify:
xcode-select -p
Expected:
/Library/Developer/CommandLineTools
Step 1: Install Homebrew
Homebrew is the package manager for macOS.
Check if already installed:
brew --version
If not installed:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Verify:
brew doctor
Expected:
Your system is ready to brew.
Step 2: Install tfenv
Install tfenv using Homebrew.
brew install tfenv
Verify:
tfenv --version
Example:
tfenv 3.2.2
Step 3: Let tfenv Control Terraform
This is the most important step.
Do NOT install Terraform directly via Homebrew if you want tfenv to manage versions.
If Terraform was previously installed:
brew unlink terraform
Link tfenv:
brew link --overwrite tfenv
Refresh shell:
hash -r
Verify:
which tfenv
Expected:
/opt/homebrew/bin/tfenv
Verify Terraform symlink:
ls -l /opt/homebrew/bin/terraform
Expected:
/opt/homebrew/bin/terraform -> ../Cellar/tfenv/.../bin/terraform
Step 4: Install Terraform Versions
Install Terraform 1.10
tfenv install 1.10.5
Install Terraform 1.11
tfenv install 1.11.4
Install Terraform 1.12
tfenv install 1.12.2
Install Terraform 1.13
tfenv install 1.13.5
Install Terraform 1.14
tfenv install 1.14.2
Install Terraform 1.15
tfenv install 1.15.5
Step 5: View Installed Versions
tfenv list
Example:
1.10.5
1.11.4
1.12.2
1.13.5
1.14.2
* 1.15.5
The asterisk indicates the active version.
Step 6: Switch Terraform Versions
Switch globally:
tfenv use 1.14.2
Verify:
terraform version
Output:
Terraform v1.14.2
Switch again:
tfenv use 1.15.5
Step 7: Use Different Terraform Versions Per Project
Navigate to your project:
cd my-project
Create:
echo "1.14.2" > .terraform-version
Now whenever you enter the directory:
terraform version
Terraform automatically switches to:
Terraform v1.14.2
This is the recommended approach for teams.
Step 8: Verify Installation
Check Terraform location:
which terraform
Expected:
/opt/homebrew/bin/terraform
Check active version:
terraform version
Check tfenv:
tfenv --version
List versions:
tfenv list
Common Troubleshooting
Error: tfenv not found
Verify installation:
brew list tfenv
Check PATH:
echo $PATH
Reload shell:
source ~/.zshrc
Error: terraform command not found
Refresh shell:
hash -r
Verify:
which terraform
Error: Could not symlink terraform
Occurs when Terraform and tfenv both attempt to own:
/opt/homebrew/bin/terraform
Fix:
brew unlink terraform
brew link --overwrite tfenv
Error: tfenv-exec.sh line 31: @: unbound variable
This usually happens when:
- Broken symlink
- Partial tfenv installation
- Terraform linked incorrectly
Fix:
brew unlink terraform
brew link --overwrite tfenv
hash -r
Best Practices
For Personal Development
Use:
tfenv use latest
For Production
Pin exact version:
echo "1.14.2" > .terraform-version
Commit:
git add .terraform-version
git commit -m "Pin Terraform version"
For Teams
Every repository should contain:
.terraform-version
This ensures every engineer uses the same Terraform version.
Useful tfenv Commands
Install version:
tfenv install 1.15.5
List versions:
tfenv list
Switch version:
tfenv use 1.15.5
Show current version:
tfenv version-name
Uninstall version:
tfenv uninstall 1.12.2
Install latest:
tfenv install latest
Conclusion
For modern DevOps, Platform Engineering, SRE, and Cloud Infrastructure teams, tfenv is the recommended way to manage Terraform installations on macOS.
Instead of maintaining a single Terraform binary, tfenv allows engineers to:
- Install multiple Terraform versions
- Switch versions instantly
- Use project-specific versions
- Avoid compatibility issues
- Maintain reproducible infrastructure deployments
The recommended setup is:
brew install tfenv
brew unlink terraform
brew link --overwrite tfenv
tfenv install 1.15.5
tfenv use 1.15.5
terraform version
You now have a professional Terraform environment capable of supporting multiple projects and Terraform releases on macOS.
